Skip to main content

ESPHome 使用手册 - 高级：reTerminal E 系列

前置条件

本页假定你已经完成了 reTerminal E 系列的 ESPHome 基础使用手册（设备已连接 Wi-Fi、已与 Home Assistant 集成、首个仪表板已渲染）。有关平台级 YAML 骨架和 Home Assistant 集成步骤，请参阅 使用 ESPHome。


本文在我们之前的 ESPHome 基础用法指南 的基础上，探索适用于 reTerminal E 系列电子墨水屏设备的高级 ESPHome 配置。如果你刚接触 ESPHome 或 reTerminal E 系列，建议先阅读基础指南，再来尝试这些高级应用。

硬件能力​

reTerminal E 系列电子墨水屏包含多种硬件组件，可以通过 ESPHome 在 Home Assistant 中加以利用：

  • 三个可编程按键（GPIO3、GPIO4、GPIO5）

  • 蜂鸣器（GPIO45）

  • 电池电量监控（GPIO1 电压检测）

  • 板载 LED（GPIO6）

  • 温湿度传感器（I²C 接口）

下面我们来看看如何在实际应用中使用这些组件。

reTerminal E 系列电子墨水屏硬件组件控制​

下面我们将介绍如何在 Home Assistant 中使用 reTerminal E 系列电子墨水屏上的各个硬件组件。

按键和 LED​

本示例演示如何使用 reTerminal E 系列电子墨水屏上的三个按键来控制功能，并通过板载 LED 提供视觉反馈。

你可以将下面的示例代码复制并粘贴到 Yaml 文件中 captive_portal 代码行之后来使用。

# Button configuration
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO3         # Green button
      mode: INPUT_PULLUP
      inverted: true
    id: button_1
    name: "Button 1"
    on_press:
      then:
        - light.turn_on: onboard_led
        - delay: 500ms
        - light.turn_off: onboard_led

  - platform: gpio
    pin:
      number: GPIO4          # Right white button
      mode: INPUT_PULLUP
      inverted: true
    id: button_2
    name: "Button 2"
    on_press:
      then:
        - light.turn_on: onboard_led
        - delay: 200ms
        - light.turn_off: onboard_led
        - delay: 200ms
        - light.turn_on: onboard_led
        - delay: 200ms
        - light.turn_off: onboard_led

  - platform: gpio
    pin:
      number: GPIO5           # Left white button
      mode: INPUT_PULLUP
      inverted: true
    id: button_3
    name: "Button 3"
    on_press:
      then:
        - light.toggle: onboard_led

# LED configuration
output:
  - platform: gpio
    pin: GPIO6
    id: led_output
    inverted: true

light:
  - platform: binary
    name: "Onboard LED"
    output: led_output
    id: onboard_led

该配置：

  • 将三个按键全部设置为带上拉电阻的输入
  • 配置按键 1 以短暂闪烁 LED
  • 配置按键 2 以双闪模式闪烁 LED
  • 配置按键 3 以切换 LED 的开/关
  • 使 LED 作为可控灯光实体在 Home Assistant 中可用

蜂鸣器控制​

reTerminal E 系列电子墨水屏在 GPIO45 上集成了一个蜂鸣器，可用于提供声音反馈。以下是配置方法：

你可以将下面的示例代码复制并粘贴到 Yaml 文件中 captive_portal 代码行之后来使用。

# This component creates a raw PWM (Pulse Width Modulation) output signal.
# For ESP32, the correct platform is 'ledc', which uses the dedicated LED Control hardware peripheral.
output:
  - platform: ledc   # CORRECTED: 'ledc' is the correct platform for ESP32 PWM.
    pin: GPIO45
    id: buzzer_pwm
    # The frequency determines the pitch of the buzzer's sound. 1000Hz is a mid-range tone.
    frequency: 1000Hz

# Create a light entity to provide a user-friendly way to control the buzzer.
# The 'brightness' of the light will control the PWM duty cycle, which effectively changes the buzzer's volume.
light:
  - platform: monochromatic
    output: buzzer_pwm
    name: "Buzzer"
    id: buzzer
    # Setting transition length to 0s makes the buzzer turn on and off instantly.
    default_transition_length: 0s

# This section defines the physical button that will trigger the buzzer.
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO3            # The GPIO pin connected to the green button.
      mode: INPUT_PULLUP       # Use the internal pull-up resistor.
      inverted: true           # The signal is low when pressed.
    id: button_1
    # 'on_press' defines the sequence of actions to execute when the button is pressed.
    on_press:
      then:
        # First beep: turn on at 50% volume (brightness) for 200 milliseconds.
        - light.turn_on:
            id: buzzer
            brightness: 50%
        - delay: 200ms
        - light.turn_off: buzzer
        # Pause for 100 milliseconds between beeps.
        - delay: 100ms
        # Second beep: turn on at 70% volume for 200 milliseconds.
        - light.turn_on:
            id: buzzer
            brightness: 70%
        - delay: 200ms
        - light.turn_off: buzzer

该配置：

  • 将蜂鸣器设置为 PWM 输出
  • 创建一个用于控制蜂鸣器的灯光实体
  • 配置按键 1 在按下时播放一个短促的蜂鸣模式
tip

你可以调整 frequency 参数来改变蜂鸣器的音调。数值越高，音调越尖锐。

电池监控​

reTerminal E 系列电子墨水屏可以通过 GPIO1 上的模拟输入监控电池电量。以下是设置方法：

esphome:
  name: reterminal-e10xx
  friendly_name: reTerminal_E10xx
  on_boot:
    priority: 600
    then:
      - output.turn_on: bsp_battery_enable

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: arduino

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "m+rOiVDwjdvePoiG1zritvcD0Kl/a2zmsnuG+4IfWlw="

ota:
  - platform: esphome
    password: "710fecea969062a5775b287a54f3c0f5"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Reterminal-E10Xx"
    password: "tRc2fXaYE54Q"

captive_portal:

output:
  - platform: gpio
    pin: GPIO21
    id: bsp_battery_enable

sensor:
  - platform: adc
    pin: GPIO1
    name: "Battery Voltage"
    id: battery_voltage
    update_interval: 60s
    attenuation: 12db
    filters:
      - multiply: 2.0  # Voltage divider compensation

  - platform: template
    name: "Battery Level"
    id: battery_level
    unit_of_measurement: "%"
    icon: "mdi:battery"
    device_class: battery
    state_class: measurement
    lambda: 'return id(battery_voltage).state;'
    update_interval: 10s
    filters:
      - calibrate_linear:
          - 4.15 -> 100.0
          - 3.96 -> 90.0
          - 3.91 -> 80.0
          - 3.85 -> 70.0
          - 3.80 -> 60.0
          - 3.75 -> 50.0
          - 3.68 -> 40.0
          - 3.58 -> 30.0
          - 3.49 -> 20.0
          - 3.41 -> 10.0
          - 3.30 -> 5.0
          - 3.27 -> 0.0
      - clamp:
          min_value: 0
          max_value: 100

该配置：

  • 通过 ADC 读取电池电压
  • 使用校准曲线将电压转换为电池百分比
  • 使原始电压值和百分比值都可以在 Home Assistant 中使用
caution

要测量电池电量，你需要使 GPIO21 引脚处于使能状态。否则无法从 GPIO1 读取电池电压值。

示例 2. 将 Home Assistant 仪表板截屏显示​

本示例演示如何捕获 Home Assistant 仪表板的截图，并将其显示在 reTerminal E 系列设备上。

安装 Puppet 插件​

步骤 1. 首先，你需要安装 Puppet 插件。点击下方按钮，它会直接带你进入 Home Assistant 实例中的插件安装页面：

步骤 2. 在插件页面中，点击 "INSTALL" 按钮，并等待安装完成。

创建访问令牌​

步骤 3. 安装完成后，进入 Puppet 插件的 Configuration 页面。如你所见，这里需要输入令牌。你需要为该插件创建一个访问令牌。

步骤 4. 在 Home Assistant 中点击左下角的用户名进入个人资料页面，然后在页面底部选择 "Long-Lived Access Tokens"。

步骤 5. 创建一个新的令牌，并使用类似 "Puppet Screenshot" 这样的描述性名称，然后复制生成的令牌。

步骤 6. 返回 Puppet 插件的配置界面，并将令牌粘贴到 "Long-Lived Access Token" 字段中。

步骤 7. 保存配置并重启 Puppet 插件。

了解 Screenshot API​

Puppet 插件在端口 10000 上启动一个服务器，用于生成任意 Home Assistant 页面截图。以下是使用方法：

基本截图 URL 格式​

http://homeassistant.local:10000/lovelace/0?viewport=800x480

此 URL 将以 800x480 分辨率捕获你的默认仪表盘截图（非常适合 reTerminal E 系列）。

电子纸优化​

对于电子纸显示屏，添加 eink 参数以减少颜色调色板：

http://homeassistant.local:10000/lovelace/0?viewport=800x480&eink=2

值 2 表示 2 色（黑白）调色板。

反转颜色​

添加 invert 参数以反转黑白：

http://homeassistant.local:10000/lovelace/0?viewport=800x480&eink=2&invert

捕获不同页面​

你可以通过更改 URL 路径来捕获任意 Home Assistant 页面：

http://homeassistant.local:10000/todo?viewport=800x480&eink=2&invert

在浏览器中输入你的截图 URL 进行测试。你应该会看到所选 Home Assistant 页面的截图。

ESPHome 配置​

步骤 11. 将以下代码添加到你的 ESPHome 配置中，放在 captive_portal 部分之后：


……
psram:
  mode: octal
  speed: 80MHz

……

captive_portal:

spi:
  clk_pin: GPIO7
  mosi_pin: GPIO9

http_request:
  verify_ssl: false
  timeout: 20s
  watchdog_timeout: 25s

online_image:
  - id: dashboard_image
    format: PNG
    type: GRAYSCALE
    buffer_size: 65536
    url: http://homeassistant.local:10000/lovelace/0?viewport=800x480&eink=2&invert
    update_interval: 1min
    on_download_finished:
      - component.update: epaper_display

display:
  - platform: waveshare_epaper
    id: epaper_display
    model: 7.50inv2 # You can use 7.50inv2alt when you draw complex info and it display not good.
    cs_pin: GPIO10
    dc_pin: GPIO11
    reset_pin:
      number: GPIO12
      inverted: false
    busy_pin:
      number: GPIO13
      inverted: true
    update_interval: 300s
    lambda: |-
      it.image(0, 0, id(dashboard_image));
caution

如果本地 DNS 解析在你的网络中不起作用，请将 homeassistant.local 替换为你的 Home Assistant 实际 IP 地址。

当你的配置成功上传并运行后，你的 reTerminal E 系列电子纸显示屏将显示 Home Assistant 仪表盘的截图：

示例 3：深度睡眠模式​

tip

如果你开始使用深度睡眠程序，我们建议你最好配合右侧的白色按键使用，并将右侧的白色按键设置为唤醒睡眠按键。这样，当你想要更新程序时，就不会遇到设备处于睡眠状态而无法通过串口上传程序的尴尬情况。

此示例演示如何使用深度睡眠模式显著降低功耗，使你的 reTerminal E 系列电子纸显示屏适用于电池供电应用。

你可以通过复制下面的代码，并将其粘贴到 Yaml 文件中 captive_portal 代码行之后来使用此示例。

globals:
  - id: sleep_counter
    type: int
    restore_value: yes  # Use RTC storage to maintain counter during sleep
    initial_value: '0'

# Deep sleep configuration
deep_sleep:
  id: deep_sleep_1
  run_duration: 30s  # Device remains awake for 30 seconds
  sleep_duration: 5min  # Then sleeps for 5 minutes
  # Optional: Use a button to wake from sleep
  wakeup_pin: GPIO4
  wakeup_pin_mode: INVERT_WAKEUP

interval:
  - interval: 29s  # Schedule sleep just before run_duration ends
    then:
      - logger.log: "Entering deep sleep now..."

font:
  - file: "gfonts://Inter@700"
    id: font1
    size: 24

spi:
  clk_pin: GPIO7
  mosi_pin: GPIO9

display:
  - platform: waveshare_epaper
    id: epaper_display
    model: 7.50inv2
    cs_pin: GPIO10
    dc_pin: GPIO11
    reset_pin:
      number: GPIO12
      inverted: false
    busy_pin:
      number: GPIO13
      inverted: true
    update_interval: 5min
    lambda: |-
      id(sleep_counter) += 1;
      ESP_LOGD("main", "Wakeup count: %d", id(sleep_counter));
      it.printf(100, 100, id(font1), "Wakeup count: %d", id(sleep_counter));

此配置：

  • 创建一个在睡眠周期之间保持持久的计数器
  • 将设备配置为唤醒 30 秒，然后睡眠 3 分钟
  • 使用当前唤醒次数更新显示屏
  • 可选地配置一个按键来唤醒设备

运行时，你会看到每次设备从睡眠中唤醒时计数器都会递增：

示例 4：综合示例​

tip

为了更好地理解，我们强烈建议你先运行上面的基础示例，再尝试这个综合示例。

这个高级示例将多个功能组合成一个完整的 reTerminal E 系列仪表盘解决方案。它演示了：

  1. 天气和室内环境显示
  2. 带图标的电池监控
  3. 时间和日期显示
  4. 使用按键进行页面切换
  5. 电池监控
点击此处查看完整代码
esphome:
  name: reterminal_e1001
  friendly_name: reTerminal_E1001
  on_boot:
    priority: 600
    then:
      - output.turn_on: bsp_sd_enable
      - output.turn_on: bsp_battery_enable
      - delay: 200ms
      - component.update: battery_voltage
      - component.update: battery_level


esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: arduino

# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "g93yP72UIyVsz9WfffaDMK+JeIQYROIFRK+VIQjkM+g="

ota:
  - platform: esphome
    password: "1ff187393ee444aa2e892779dc78e488"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "reTerminal-E1001"
    password: "yoUkaGlJaDpC"

captive_portal:

# Deep-sleep, wake by GPIO4
deep_sleep:
  id: deep_sleep_1
  run_duration: 1min
  sleep_duration: 60min
  wakeup_pin: GPIO4          # Right white button
  wakeup_pin_mode: INVERT_WAKEUP

# SPI / I²C
spi:
  clk_pin: GPIO7
  mosi_pin: GPIO9
i2c:
  scl: GPIO20
  sda: GPIO19

# Fonts
font:
  - file: "gfonts://Inter@700"
    id: small_font
    size: 24
  - file: "gfonts://Inter@700"
    id: mid_font
    size: 36
  - file: "gfonts://Inter@700"
    id: big_font
    size: 180
  - file: "gfonts://Inter@700"
    id: time_font
    size: 96      # for the big time display
  - file: 'fonts/materialdesignicons-webfont.ttf'
    id: font_mdi_large
    size: 70
    glyphs:
      - "\U000F050F"  # thermometer
      - "\U000F058E"  # humidity
  - file: 'fonts/materialdesignicons-webfont.ttf'
    id: font_bat_icon
    size: 24
    glyphs:
      - "\U000F007A"  # mdi-battery-10
      - "\U000F007B"  # mdi-battery-20
      - "\U000F007C"  # mdi-battery-30
      - "\U000F007D"  # mdi-battery-40
      - "\U000F007E"  # mdi-battery-50
      - "\U000F007F"  # mdi-battery-60
      - "\U000F0080"  # mdi-battery-70
      - "\U000F0081"  # mdi-battery-80
      - "\U000F0082"  # mdi-battery-90
      - "\U000F0079"  # mdi-battery

globals:
  - id: page_index
    type: int
    restore_value: true
    initial_value: '0'
  - id: battery_glyph
    type: std::string
    restore_value: no
    initial_value: "\"\\U000F0079\""   # default full battery

sensor:
  - platform: sht4x
    temperature:
      name: "Temperature"
      id: temp_sensor
    humidity:
      name: "Relative Humidity"
      id: hum_sensor
  - platform: adc
    pin: GPIO1
    name: "Battery Voltage"
    id: battery_voltage
    update_interval: 60s
    attenuation: 12db
    filters:
      - multiply: 2.0
  - platform: template
    name: "Battery Level"
    id: battery_level
    unit_of_measurement: "%"
    icon: "mdi:battery"
    device_class: battery
    state_class: measurement
    lambda: 'return id(battery_voltage).state;'
    update_interval: 60s
    on_value:
      then:
        - lambda: |-
            int pct = int(x);
            if (pct <= 10)      id(battery_glyph) = "\U000F007A";
            else if (pct <= 20) id(battery_glyph) = "\U000F007B";
            else if (pct <= 30) id(battery_glyph) = "\U000F007C";
            else if (pct <= 40) id(battery_glyph) = "\U000F007D";
            else if (pct <= 50) id(battery_glyph) = "\U000F007E";
            else if (pct <= 60) id(battery_glyph) = "\U000F007F";
            else if (pct <= 70) id(battery_glyph) = "\U000F0080";
            else if (pct <= 80) id(battery_glyph) = "\U000F0081";
            else if (pct <= 90) id(battery_glyph) = "\U000F0082";
            else                id(battery_glyph) = "\U000F0079";
    filters:
      - calibrate_linear:
          - 4.15 -> 100.0
          - 3.96 -> 90.0
          - 3.91 -> 80.0
          - 3.85 -> 70.0
          - 3.80 -> 60.0
          - 3.75 -> 50.0
          - 3.68 -> 40.0
          - 3.58 -> 30.0
          - 3.49 -> 20.0
          - 3.41 -> 10.0
          - 3.30 -> 5.0
          - 3.27 -> 0.0
      - clamp:
          min_value: 0
          max_value: 100

output:
  - platform: gpio
    pin: GPIO6
    id: bsp_led
    inverted: true
  - platform: gpio
    pin: GPIO16
    id: bsp_sd_enable
  - platform: gpio
    pin: GPIO21
    id: bsp_battery_enable

# Onboard LED
light:
  - platform: binary
    name: "Onboard LED"
    output: bsp_led
    id: onboard_led

binary_sensor:
  - platform: gpio    # Next page
    pin:
      number: GPIO3
      mode: INPUT_PULLUP
      inverted: true
    id: key1
    name: "Key1"
    on_press:
      then:
        - lambda: |-
            id(page_index) = (id(page_index) + 1) % 2;
            id(epaper_display).update();

  - platform: gpio     # Prev page
    pin:
      number: GPIO5
      mode: INPUT_PULLUP
      inverted: true
    id: key2
    name: "Key2"
    on_press:
      then:
        - lambda: |-
            id(page_index) = (id(page_index) - 1 + 2) % 2;
            id(epaper_display).update();

  # - platform: gpio
  #   pin:
  #     number: GPIO4
  #     mode: INPUT_PULLUP
  #     inverted: true
  #   id: key2
  #   name: "Key2"
  #   on_press:
  #     then:
  #       - lambda: |-
  #           id(page_index) = (id(page_index) - 1 + 3) % 3;
  #           id(epaper_display).update();

# Home Assistant time
time:
  - platform: homeassistant
    id: ha_time

# e-paper
display:
  - platform: waveshare_epaper
    id: epaper_display
    model: 7.50inv2
    cs_pin: GPIO10
    dc_pin: GPIO11
    reset_pin:
      number: GPIO12
      inverted: false
    busy_pin:
      number: GPIO13
      inverted: true
    update_interval: never
    lambda: |-
      // ----------  PAGE 0  ----------
      if (id(page_index) == 0) {
        const int scr_w = 800;
        const int scr_h = 480;

        // Battery in upper-right corner
        it.printf(670, 13, id(font_bat_icon), "%s", id(battery_glyph).c_str());
        it.printf(700, 10, id(small_font), "%.0f%%", id(battery_level).state);

        //line
        it.filled_rectangle(400, 100, 2, 280);

        // Convert °C to °F
        float temp_f = id(temp_sensor).state * 9.0 / 5.0 + 32.0;

        // ---------------------------------------------------------
        // Horizontal split: two 400 px columns
        const int col_w = scr_w / 2;

        const int icon_y   = 100;   // Icon baseline
        const int value_y  = 220;   // Number baseline
        const int unit_y   = 300;   // Unit baseline
        const int label_y  = 380;   // Text label baseline

        const int icon_size = 70;   // icon font size
        const int val_size  = 120;  // number font size
        const int unit_size = 44;   // unit font size
        const int label_size= 36;   // label font size

        // --- Left column : Temperature -----------------------------
        const int left_mid = col_w / 2 - 30;   // 200 px

        // Icon
        it.printf(left_mid, icon_y, id(font_mdi_large), TextAlign::CENTER, "\U000F050F");
        // Value
        it.printf(left_mid, value_y, id(big_font), TextAlign::CENTER, "%.0f", temp_f);
        // Unit
        it.printf(left_mid + 150, unit_y, id(mid_font), TextAlign::CENTER, "°F");
        // Label
        it.printf(left_mid, label_y, id(mid_font), TextAlign::CENTER, "Temperature");

        // --- Right column : Humidity -------------------------------
        const int right_mid = col_w + col_w / 2;   // 600 px

        // Icon
        it.printf(right_mid, icon_y, id(font_mdi_large), TextAlign::CENTER, "\U000F058E");
        // Value
        it.printf(right_mid, value_y, id(big_font), TextAlign::CENTER, "%.0f", id(hum_sensor).state);
        // Unit
        it.printf(right_mid + 150, unit_y, id(mid_font), TextAlign::CENTER, "%%");
        // Label
        it.printf(right_mid, label_y, id(mid_font), TextAlign::CENTER, "Humidity");
      }
      // ----------  PAGE 1  ----------
      else{
        // Battery top-right
        it.printf(670, 13, id(font_bat_icon), "%s", id(battery_glyph).c_str());
        it.printf(700, 10, id(small_font), "%.0f%%", id(battery_level).state);

        auto now = id(ha_time).now();
        struct tm timeinfo = now.to_c_tm();

        // centering time HH:MM
        char timeStr[6];
        strftime(timeStr, sizeof(timeStr), "%H:%M", &timeinfo);
        it.printf(400, 180, id(time_font), TextAlign::CENTER, timeStr);

        // Date: Day of week
        const char *weekday[] = {"Sun","Mon","Tue","Wed","Thu","Fri","Sat"};
        const char *wday = weekday[timeinfo.tm_wday];

        // Date: month - day
        char dateStr[12];
        strftime(dateStr, sizeof(dateStr), "%b %d", &timeinfo);  // e.g. Jun 15

        // Day of the week + date below the time
        it.printf(400, 280, id(mid_font), TextAlign::CENTER, "%s, %s", wday, dateStr);
      }

当你的配置成功上传并运行后，你的 reTerminal E 系列电子墨水屏将显示一个包含环境数据、时间和电池状态的综合仪表盘：

理解这个综合示例​

此示例实现了：

  1. 多页面：显示屏在两个页面之间切换——气候仪表盘和时间/日期显示
  2. 按键导航：使用 GPIO3 和 GPIO5 上的按键在页面之间导航
  3. 电池监测：电池电量通过相应图标显示，并会根据电量水平变化
  4. 硬件初始化：在启动时启用 SD 卡和电池监测电路
  5. 温湿度显示：通过 I²C 使用板载 SHT4x 传感器
  6. 动态图标：Material Design Icons 会根据传感器数值变化

常见问题​

问题 1：为什么没有数据？​

在这种情况下，你应该前往 Settings -> Devices & Services -> Integrations 来**重新配置（RECONGFIGURE）**设备。还没有找到你的电子墨水面板？尝试重启 Home Assistant。

Q2：为什么我无法在 Home Assistant 中获取这些数据？​

在这种情况下，你需要前往 Settings -> Devices & Services -> Integrations，将你的设备添加到 Home Assistant 中。

Q3：通过 Wi-Fi 上传程序失败？​

在这种情况下，你的设备要么处于离线状态，要么处于深度睡眠模式。请确保它已连接到你的网络，或者先将其从睡眠模式唤醒，然后再尝试上传。

技术支持与产品讨论​

感谢你选择我们的产品！我们将为你提供多种支持，以确保你在使用我们产品的过程中尽可能顺利。我们提供多种沟通渠道，以满足不同的偏好和需求。

Loading Comments...