ESPHome

概述

这篇文档介绍如何为 reTerminal Sticky 使用 ESPHome 玩法广场页面。

你会了解 ESPHome 是什么、需要准备哪些硬件和软件、如何从玩法广场生成 YAML、如何烧录、烧录后如何使用设备，以及后续去哪里继续学习。

平台介绍

ESPHome 是一种基于 YAML 的固件配置方式，常用于 Home Assistant。你可以用可读的配置文件描述设备行为，然后从这个配置编译并烧录固件。

对 Sticky 来说，玩法广场页面会根据你选择的硬件选项生成用于起步的 YAML。

主要好处包括：

搭建本地智能家居看板
显示传感器、天气或自动化状态
用生成的 YAML 测试 Sticky 的硬件功能
保持设备配置可阅读、可修改

Note

玩法广场页面负责生成 YAML。实际烧录需要使用 ESPHome Web 或 ESPHome CLI。

准备工作

开始之前，请准备：

reTerminal Sticky
USB-C 数据线
桌面版 Chrome 或 Edge，用于 ESPHome Web
Wi-Fi 名称和密码，或 ESPHome !secret 配置
如果使用命令行烧录，需要提前安装 ESPHome CLI
如果烧录后要接入 Home Assistant，需要准备好 Home Assistant 环境

从玩法广场烧录

点击下方按钮，进入 ESPHome 玩法广场页面：

打开 ESPHome 玩法广场

然后按下面步骤操作：

在 Device and Wi-Fi 中，确认目标设备为 reTerminal Sticky。
填写 Wi-Fi SSID 和密码，或留空以保留 !secret 占位符。

在 Hardware options 中，先从 Defaults 开始。
根据需要增加或减少硬件配置块。

在 Preview and export 中检查生成的 YAML。
使用 Copy to clipboard 或 Download .yaml 导出配置。

检查并修改生成的 YAML

在编译或烧录之前，先打开生成的 YAML 文件，重点检查下面几部分。默认示例的目标是先验证 Sticky 的硬件链路，再作为你继续制作 ESPHome 项目的基础文件。

填写必需的密钥

生成的 YAML 可能会通过 !secret 引用 Wi-Fi、Home Assistant 原生 API 和 OTA 更新所需的敏感信息。!secret 的意思是：真实值放在同一个配置目录下的 secrets.yaml 文件中，主 YAML 只写引用名。

默认 YAML 里的 API 和 OTA 部分是这样的：

# Home Assistant native API
api:
  encryption:
    key: !secret api_encryption_key

# OTA (Over-The-Air) firmware update
ota:
  - platform: esphome
    password: !secret ota_password

请在 reterminal-sticky.yaml 同级目录创建 secrets.yaml，并写入对应的值：

wifi_ssid: "Your WiFi SSID"
wifi_password: "Your WiFi Password"
api_encryption_key: "Your 32-byte base64 API encryption key"
ota_password: "Your OTA update password"

API 加密密钥可以用下面的命令生成：

openssl rand -base64 32

当 api_encryption_key 或 ota_password 只在主 YAML 里被引用、但没有在 secrets.yaml 里定义时，ESPHome 会在配置校验阶段停止。临时本地测试时，也可以把 !secret ... 直接替换成带引号的实际值。长期维护项目时，把密钥放在 secrets.yaml 里会更清晰。

了解示例代码做了什么

生成的示例会启用 Sticky 的主要硬件模块，并把它们暴露成 ESPHome 实体：

substitutions：设置 ESPHome 和 Home Assistant 里看到的设备名。
esphome.on_boot：设备启动时拉高 Sticky 的电源保持引脚，并读取 RTC 时间。
esp32、logger、spi、i2c：定义开发板、串口日志、墨水屏 SPI 总线和传感器 I2C 总线。
font：加载墨水屏显示用到的字体。
output 和 light：保持电源轨开启，控制充电使能引脚，并把蜂鸣器做成可控制输出。
sensor：读取 SHT40 温湿度，以及 BQ27220 电池电量、电压和电流。
binary_sensor：映射 UP、DOWN、OK 三个按键，并报告充电状态。
time：读取 PCF8563 RTC，并可从 Home Assistant 同步时间。
api、ota、wifi、captive_portal：负责联网、接入 Home Assistant 和后续无线更新。
display：负责渲染墨水屏画面。

默认显示内容是固定模板。屏幕会打印标题、RTC 时间、温度、湿度、电池百分比、按键提示和底部说明。它不会自动把 Home Assistant 仪表盘照搬到屏幕上。如果你想显示自己的布局、天气、任务列表、房间状态或其他 Home Assistant 数据，需要修改 display.lambda 这一段。

自定义墨水屏画面

屏幕内容写在这里：

display:
  - platform: epaper_spi
    id: epaper_display
    model: seeed-reterminal-sticky
    update_interval: 300s
    lambda: |-
      it.printf(400, 15, id(font_medium), COLOR_OFF, TextAlign::TOP_CENTER,
                "reTerminal Sticky");

lambda: |- 里面就是画屏幕的逻辑。你可以把屏幕理解成一张 800 x 480 的纸：x 从左往右，y 从上往下。例如 it.printf(30, 120, ...) 就是在偏左、靠上往下一些的位置打印内容。

常见修改方式：

修改 it.print(...) 或 it.printf(...) 里的字符串，就能改固定文字。
修改前两个数字，例如 30, 120，就能调整文字位置。
在 id(font_small)、id(font_medium)、id(font_large) 之间切换，就能调整字号；也可以在 font: 里新增字体。
修改 update_interval: 300s，就能调整屏幕刷新间隔。
打印传感器数值前先判断 has_state()，这样传感器刚启动、暂时没有数值时，屏幕也能正常刷新。

比如下面这个简化版显示块，会显示自定义标题、温度、湿度和电量：

display:
  - platform: epaper_spi
    id: epaper_display
    model: seeed-reterminal-sticky
    update_interval: 300s
    lambda: |-
      it.printf(400, 20, id(font_medium), COLOR_OFF, TextAlign::TOP_CENTER,
                "Kitchen Status");
      it.line(20, 60, 780, 60, COLOR_OFF);

      if (id(temp_sensor).has_state()) {
        it.printf(30, 110, id(font_large), COLOR_OFF,
                  "Temp: %.1f C", id(temp_sensor).state);
      }

      if (id(hum_sensor).has_state()) {
        it.printf(30, 180, id(font_large), COLOR_OFF,
                  "Humidity: %.1f %%", id(hum_sensor).state);
      }

      if (id(battery_level).has_state() && !isnan(id(battery_level).state)) {
        it.printf(30, 260, id(font_medium), COLOR_OFF,
                  "Battery: %.0f%%", id(battery_level).state);
      }

如果你想显示 Home Assistant 里的数值，先把对应实体导入 YAML，再在 display.lambda 里打印它。数字类实体可以用 homeassistant sensor：

sensor:
  - platform: homeassistant
    id: living_room_temperature
    entity_id: sensor.living_room_temperature

然后在屏幕上使用这个 id：

display:
  - platform: epaper_spi
    id: epaper_display
    model: seeed-reterminal-sticky
    lambda: |-
      if (id(living_room_temperature).has_state()) {
        it.printf(30, 120, id(font_large), COLOR_OFF,
                  "Living Room: %.1f C", id(living_room_temperature).state);
      }

如果要显示 Home Assistant 里的文本状态，可以用 text_sensor，并在打印时使用 .state.c_str()：

text_sensor:
  - platform: homeassistant
    id: weather_summary
    entity_id: sensor.weather_summary

display:
  - platform: epaper_spi
    id: epaper_display
    model: seeed-reterminal-sticky
    lambda: |-
      it.printf(30, 120, id(font_medium), COLOR_OFF,
                "Weather: %s", id(weather_summary).state.c_str());

如果使用 ESPHome CLI，每次修改 YAML 后，先运行 esphome config reterminal-sticky.yaml 检查配置。检查通过后，再运行 esphome run reterminal-sticky.yaml 编译和上传。

如果想用浏览器烧录，请打开 ESPHome Web：

打开 ESPHome Web

用 USB-C 数据线连接 Sticky，在 ESPHome Web 要求选择配置时选择 YAML，然后选择 Sticky 对应串口，并在烧录完成前保持 USB 线连接。

如果你习惯命令行，需要先按照 ESPHome 命令行指南安装 ESPHome CLI。确认终端里可以使用 esphome 命令后，把 YAML 保存为 reterminal-sticky.yaml，然后运行：

esphome run reterminal-sticky.yaml

烧录完成后

烧录完成后，可以按下面几项检查和体验：

使用 ESPHome 玩法广场页面里的设备日志面板检查串口输出。
确认 Sticky 正常启动并连接 Wi-Fi。
如果使用 Home Assistant，把生成的设备加入 Home Assistant。
测试 YAML 中启用的显示、传感器或控制功能。
将 YAML 保存到你的 ESPHome 配置目录中，方便后续维护。

ESPHome 基础用法

ESPHome 的核心是 YAML 配置文件。YAML 用来描述设备有哪些硬件、如何连接 Wi-Fi、要向 Home Assistant 暴露哪些实体，以及屏幕要显示什么内容或设备要执行什么控制。

对 Sticky 来说，生成的 YAML 是后续维护的起点：

把生成的 YAML 保存到 ESPHome 配置目录中，后续修改、重新编译和更新都从同一个文件开始。
如果 YAML 会放进共享目录或版本管理目录，Wi-Fi 名称和密码建议使用 !secret。
先从默认硬件配置开始，再按需要启用显示、传感器、按键、音频或其他外设功能。
烧录后通过 ESPHome 日志检查 Wi-Fi 连接、启动信息、传感器读数和屏幕刷新情况。
设备被 Home Assistant 发现后，可以把它加入 Home Assistant，再把相关实体放到仪表盘或自动化里。
第一次 USB 烧录成功后，只要设备能连上网络，后续修改 YAML 通常可以用 ESPHome 的无线更新流程。

常见用途包括本地状态看板、天气面板、Home Assistant 实体汇总、电池或传感器监控、按键触发动作，以及自定义电子墨水屏页面。ESPHome 的优势是设备行为都留在 YAML 里，后续可以继续阅读、修改和维护。

资源

需要查看主文档、网页烧录器、Home Assistant 流程、命令行流程、组件参考或源码时，可以打开下面的资源。

ESPHome 文档：查看总览、指南、组件、自动化、Cookbook 和版本说明。
ESPHome Web：通过 Chrome 或 Edge 在浏览器里烧录。
ESPHome 与 Home Assistant：适合通过 Home Assistant 管理 ESPHome 的用户。
ESPHome 命令行指南：适合需要安装、编译、上传和查看日志的命令行用户。
ESPHome 组件参考：查看传感器、显示、按键、输出、网络和集成能力。
ESPHome YAML 指南：查看 !secret、变量替换、文件包含和 YAML 结构。
ESPHome 安全最佳实践：查看 API 密钥、OTA 密码和版本管理配置建议。
ESPHome Display 组件：查看显示 lambda、坐标、字体、文字、图形和页面。
Home Assistant Sensor：把 Home Assistant 里的数字实体导入 ESPHome。
Home Assistant Text Sensor：把 Home Assistant 里的文本实体导入 ESPHome。
ESPHome GitHub：查看源码、Issue 和项目更新。

特别鸣谢

特别感谢 clydebarrow 愿意使用 reTerminal Sticky、体验 ESPHome 在 Sticky 上的使用流程，并帮助 Sticky 接入 ESPHome 的工作流。

我们真诚感谢这份支持。它让 Sticky 不只是一块硬件，而是可以被 Home Assistant 和 ESPHome 用户直接拿来构建项目的设备。借助这些适配工作，社区用户可以更方便地在 Sticky 上制作本地状态看板、传感器页面、自动化控制入口，以及自定义电子墨水屏项目。

也感谢 ESPHome 维护者、Home Assistant 社区和所有相关贡献者，持续维护开放的本地自动化基础，让这条玩法广场 YAML 生成路径可以被更多 Sticky 用户使用。