跳转到内容
ESPHome - 让智能家居更简单2026.7.0

更新日志

UFM-​0​1​ ​Flow ​Meter
Flow ​&​ ​Temperature
Waveshare ​CH3​2​V0​0​3​ ​IO ​Expander
IT8​9​5​1​
QMI8​6​5​8​
Accelerometer ​&​ ​Gyroscope
CST9​2​2​0​
Pixoo
ST7​1​2​3​
CST3​2​8​
Provisioning
GSL3​6​7​0​

发布概览

Section titled “发布概览”

ESPHome 2026.7.0 将 ESP32 和 nRF52 的默认工具链切换为原生构建（ESP-IDF 和 nRF Connect SDK），并落地了首批面向 EN18031 合规的协调安全基础设施：NVS 加密、OTA 降级保护，以及新的传输无关配置组件。贯穿本版的性能和内存优化工作包括：覆盖约 50 个组件的树级单精度浮点数扫描、针对 ESP8266 的 DRAM 节省、ESP-IDF 默认启用 ccache，以及共享的机器全局工具链缓存。

在功能方面，本次发布带来了一次重大的 Modbus 改造（重写解析器和无堆发送路径）、大幅扩展的 LVGL（动画、动态旋转、启动暂停）、新 ESP32-S31 上的千兆以太网、ESP-NOW v2 负载、ESP32 上 RTC 支持的偏好设置、11 个覆盖触摸屏控制器、电子墨水屏面板、IMU 和 Divoom Pixoo 64 的新组件，以及新 2.0.2 SDK 上的 Zigbee 端点合并。旧版 Tornado Web 仪表盘已退役，改为外部的设备构建器，同时放弃了对 Python 3.11 的支持。

升级检查清单

Section titled “升级检查清单”
  • 如果您的 ESP32 配置没有显式设置 toolchain:，现在将使用原生 ESP-IDF 编译；添加 toolchain: platformio 以保持先前行为
  • 如果您的 nRF52 配置没有显式设置 toolchain:，现在将使用原生 nRF Connect SDK 构建；添加 toolchain: platformio 以保持先前行为
  • 如果您在 Python 3.11 上使用 pip 安装 ESPHome，请升级到 Python 3.12 或更高版本
  • 如果您使用 pip 安装 ESPHome 并使用内置的 esphome dashboard 命令，请安装并运行 esphome-device-builder 代替
  • 如果您有 ESP32 Zigbee 设备，升级后必须重新加入、重新访谈和重新配置每个设备
  • 如果您在 Zigbee reporting: 下设置了 enabled 或 coordinator，请移除这些键
  • 如果您使用 web_server: version: 1，请在 2027.1.0 之前计划迁移到 v2 或 v3
  • 如果您按对象 ID 寻址 web_server URL，请切换到实体名称
  • 如果有托管在别处的浏览器页面调用您的 web_server 端点，请将其来源添加到 web_server: allowed_origins:
  • 如果您依赖 web_server 默认启用的私有网络访问，请设置 enable_private_network_access: true 并将调用来源添加到 allowed_origins:
  • 如果您使用 packages: !include mypackage.yaml，请将 include 包装在列表中：packages: [!include mypackage.yaml]
  • 如果您使用 FOUR_SCAN_16PX_HIGH、FOUR_SCAN_32PX_HIGH 或 FOUR_SCAN_64PX_HIGH 作为 hub75 的 scan_wiring，请重命名为 SCAN_1_4_16PX_HIGH、SCAN_1_8_32PX_HIGH 或 SCAN_1_8_64PX_HIGH
  • 如果您在 modbus: 下设置了 disable_crc，请将其移除
  • 如果您在 modbus: 服务器上设置了 send_wait_time 或 turnaround_time，请移除这些键
  • 如果您依赖 modbus 客户端计时，请注意默认值已变更为 send_wait_time: 2000ms 和 turnaround_time: 600ms
  • 如果您使用 generic-ln882hki 板，请根据出厂固件切换到 generic-ln882h 或 generic-ln882h-tuya
  • 如果您使用 LN882H wb02a 板以及 D1、D7、D8、D9 或默认 I2C 引脚别名，请更新您的引脚号以匹配新映射
  • 如果您的 lambda 或自动化将灯光亮度设置为 0，请注意该值现在会被保留，而不是被钳位到 1.0
  • 如果两个 Home Assistant 实例共享同一个 bluetooth_proxy，最新订阅者现在胜出，而非最旧的
  • 如果您为没有 DCDC 稳压器的 nRF52 板构建，DCDC 设置不再强制，生成代码略有变化
  • 如果您的 lambda 调用 value_accuracy_to_string() 或 MideaData::to_string()，请迁移到缓冲区变体（value_accuracy_to_buf() 和 to_str(buffer)）

ESP32 和 nRF52 的原生工具链现已成为默认

Section titled “ESP32 和 nRF52 的原生工具链现已成为默认”

esp32 平台的默认工具链从 PlatformIO 切换为原生 ESP-IDF （#16910）。从本版本起，未显式设置 toolchain: 选项的配置将使用 ESP-IDF 编译。自 2026.1.0 以来显示的框架迁移通知，随着默认设置的落地也已移除 （#17023）。

工具链选择构建后端，而非框架：Arduino 和 ESP-IDF 框架均可在任一工具链上构建，原生工具链将 Arduino 作为 ESP-IDF 组件引入。显式设置 toolchain: platformio 的配置将继续与之前完全一样构建，而由向导或包生成的新配置将自动使用原生 ESP-IDF 工具链。ESP-IDF 现在被推荐同时作为工具链和框架的首选。

nrf52 平台做出相同的转变：本轮早些时候由 @tomaszduda23 添加的原生 nRF Connect SDK 构建（#16898）现已成为默认工具链 （#17319）。未显式设置 toolchain: 选项的配置将针对 nRF Connect SDK 2.9.2 构建，安装到下文所述的新共享工具链缓存中，同时 toolchain: platformio 在此也仍可作为退出选项。

ESPHome 设备构建器

Section titled “ESPHome 设备构建器”

捆绑的 ESPHome 设备构建器 已更新，本轮大部分工作投入到了远程构建服务器上。

编译固件是设备构建器最慢的操作，在 Home Assistant Green 或 Raspberry Pi 这样的小型主机上，单次构建可能需要数分钟。远程构建服务器可以让该仪表盘将编译任务交给网络中更快的机器，例如运行 ESPHome Desktop 的台式机或笔记本电脑，后者构建固件并像往常一样发送回来安装。您的设备、配置和仪表盘都留在原处；只有构建任务发生了转移。

与构建服务器配对变得更容易了

为其他仪表盘构建的机器现在会在自己的仪表盘上标明这一点 （frontend#1240）。一旦另一个仪表盘与其配对，或开启远程构建后，设备列表上方会出现构建服务器部分，引导您通过三个步骤完成配对，而无需在设置中自行寻找各个组件。

在 ESPHome 设备构建器中配对构建服务器

从那里您可以打开配对窗口并观看倒计时，复制地址到发送仪表盘上输入 （#2075），并与发送方显示的指纹进行比对。配对后，该部分列出对端及其连接状态和构建队列，任何等待您处理的配对请求显示在顶部。设置中新增了相应的说明，旧的 仅用于远程计算 开关现在改为 远程计算仪表盘，决定先打开哪个部分，而不会隐藏任何内容。

远程构建在运行后也变得更加稳定。如果接收方重启，发送方现在会在 mDNS 上重新出现后立即重连，而不会等待退避超时（#2084）。接收方现在也可以提供 ESPHome 的 Beta 版本，因此运行不同版本的构建服务器（相对于 Beta 频道上的发送方）不再会悄悄回退到本地构建 （#2082）。某版本的第一个构建会从 PyPI 安装 ESPHome，可能需要几分钟，作业日志现在会明确告知，而不会静默等待 （#2083）。

如果您从未尝试过此功能，终端现在会显示构建计时器，而在没有配对构建服务器的仪表盘上，本地编译超过五分钟会提示将构建任务发送到更快的机器 （frontend#1183）。

离线与深度休眠更新

更新未唤醒的设备一直都是一个时机问题。针对休眠或不可达设备的 OTA 只会失败，这对于运行深度休眠的用户来说是熟悉的问题。

由 @rwalker777 贡献的排队离线更新修复了这一问题 （#1430， frontend#911）。如果设备在安装时处于离线状态，设备构建器会编译固件、排队更新，并在设备下次出现在网络上时刷入，无需您当时在场。

相关基础工作在 2026.6.0 中已完成，现在已准备好投入生产使用。它适用于整个设备集群：选择任意数量的设备并点击更新，无法到达的设备只会编译一次并排队等待下次出现，而不会失败（#1929）。在点击安装和构建完成之间掉线的设备也会被排队，而不是在最后一步失败 （#1964），而排队的更新在您返回时会重新打开为安装，携带排队的消息 （frontend#1181）。

快速入门导览

从全新安装到运行设备一直是 ESPHome 最困难的部分，本次发布对此进行了真正的尝试。设置现已以提供引导式导览作为结尾，导览通过使用设备构建器来教授，而不是描述它。

它一次突出显示一个真实控件，解释其用途，在重要步骤上等待您点击而不是自行跳过。经过十一步，它带您完成创建第一个设备、选择板子、命名、输入 WiFi 信息、熟悉设备导航器和编辑器、观察 YAML 面板同步变化、以及安装到板子的过程，最终在仪表盘上看到新设备。大约需要五分钟，您会得到一个真实设备而非一次性演示，可以随时关闭并在之后继续，且始终可从右上角菜单访问。

该导览是 @Erioldoesdesign、 @stvncode 和 @marcelveldt 的团队协作成果，涵盖设计、线框图和构建（frontend#1045、 frontend#1232）。围绕它的设置流程也同时进行了重建：新的欢迎屏幕、一个让初学者可以一键选择推荐路径的体验问题，以及一个将您转交至导览的结束屏幕。如果您在网络上已有设备构建器运行时设置桌面应用，设置会指出这一点并解释如何配对两者，从而让新机器立即为您已有的仪表盘构建固件 （frontend#1235）。

YAML 错误解释与自动修复

许多针对 ESPHome 报告的问题实际上并非 Bug，而是在编辑 YAML 时的小错误。本次发布致力于解决这一整类问题。

以前空格错误只会得到原始解析器输出，如 mapping values are not allowed here 或 could not find expected ':'，而且只有当您想到去悬停提示波浪线时才能看到。它指向的行通常是解析器放弃的位置，而不是您出错的地方，对于不熟悉 YAML 的人来说几乎没有帮助。

编辑器现在会读取错误并告诉您实际出了什么问题，在固定横幅中命名需要更改的行和操作方法：“缩进不匹配：第 12 行 - platform 的缩进少于其属性。将第 12 行缩进 2 个空格，使 - platform 与其对齐。“旁边是一个 尝试自动修复 按钮，为您做出精确更改。这是一个尽力而为的猜测而非魔法，因此会在应用前针对您的配置进行验证，会告知是否还有其他错误残留，并以普通编辑的方式落地，您可以撤销 （frontend#1121、 frontend#1147、 frontend#1148）。

缩进并不是它解释的唯一问题。在需要空格的地方使用 Tab、以 @、% 或 * 开头需要引号的值、未闭合的引号、重复键、未闭合的括号或花括号，都会得到相同的平实语言处理。缺少空格的列表标记 -platform: gpio 会提供一键修复为 - platform: gpio（frontend#1149）。同样适用于脱离所属块的键，例如遗留在 api: 直接下方的 encryption 键，两个方向均可；设备构建器首先检查其组件目录以确认键的归属，如果无法确定则不给出错误猜测 （frontend#1164）。

设备日志行现在会链接到解释它们的文档 （frontend#1116、 frontend#1118）。十个常见警告和错误有定制解释，包括 took a long time for an operation、WiFi 重连循环、重复重置、OTA 回滚和 Bluetooth proxy 连接槽用尽，任何其他标记了组件的行会直接链接到该组件页面。

无头构建服务器

@jesserockz 添加了 --remote-build-only，将设备构建器作为专用构建盒子运行，完全没有 Web 界面（#1861）：

Terminal window
esphome-device-builder --remote-build-only /var/lib/esphome-builder

它仅提供对端链接，因此没有人可以点击 Accept。改为在首次启动时打开配对窗口，并将身份指纹和一次性密钥打印到控制台。从发送仪表盘配对，确认指纹与控制台匹配，并输入密钥，配对对话框知道要提前要求输入 （#1881、 frontend#1120）。该窗口仅配对一个仪表盘，然后关闭。

如果您希望保留 Web 界面但仍然将机器专用于构建，请在设置中开启 远程计算仪表盘，其下方会出现 隐藏设备构建器 选项，仅保留 构建服务器 视图 （#2077、 frontend#1244）。设备构建器也可以通过 --socket 监听 UNIX 套接字以支持反向代理配置，由 @vexofp 贡献 （#1862）。

构建

启动构建后不再灰显返回该构建的按钮。更新和安装现在会打开正在运行的作业，编辑仍可点击以便在编译时查看 YAML （frontend#1191、 frontend#1193、 frontend#1197）。下载和重试现在等待正在运行的构建完成，而不是取消并重新启动，这也意味着下载不会再给您一个半写入的二进制文件 （frontend#1199、 frontend#1201、 frontend#1204）。

批量 仅编译 动作允许您在部署之前跨多个设备检查更改 （frontend#1176）。ESP-IDF 构建现在会显示编译进度，从 ninja 构建计数器读取，而不是 ESP-IDF 从不打印的百分比 （#1880）。

特别感谢 @breti，其 QA 测试和详细问题报告贯穿了整个版本发布，但在任何 PR 统计中都不曾出现。

面向 EN18031 的安全与配置基础工作

Section titled “面向 EN18031 的安全与配置基础工作”

本次发布落地了三块协调的安全基础设施，由 @kbx81 主导，共同推动 ESPHome 向联网消费设备的 EN18031 合规迈进。

ESP32 上的 NVS 加密（#17004）

使用 HMAC 外设的非易失性存储可选加密。密钥在运行时从用户选择的 eFuse 块中的 HMAC 密钥派生，因此不需要闪存加密。支持搭载 HMAC 外设的 ESP32 变体：S2、S3、C3、C5、C6、H2 和 P4。将 HMAC 密钥烧录到 eFuse 块中是永久且不可逆的操作，因此用户在启用此功能前应仔细阅读 esp32 文档。

OTA 降级保护（#17315）

已签名 ESP-IDF OTA 的软件防回滚。在切换启动分区之前，将分阶段镜像中烘焙的版本（来自 project: version:）与当前运行版本进行比较。覆盖所有 OTA 源：原生、http_request.ota 和 web_server。需要已签名的 OTA 才能生效。

配置组件（#17152）

一个全新的传输无关配置组件，管理未配置设备的配置窗口。api 和 esp32_improv 等来源向该组件注册，窗口在超时时关闭，此时任何配置相关的 API 客户端会通过 DISCONNECT_REASON_PROVISIONING_CLOSED 断开连接。

性能：单精度浮点数运算

Section titled “性能：单精度浮点数运算”

由 @swoboda1337 主导，一次树级扫描将约 50 个组件中的静默 double 提升模式替换为单精度等效实现 （#17252、 #17253、 #17254、 #17255、 #17256、 #17260）。

该问题在 ESP32 上不可见，因为 ESP-IDF 未启用 -Wdouble-promotion：如 2.0 的字面量和 fmod、round、fabs 等函数会悄悄地将单精度值提升为 double，在没有硬件 double 的芯片上通过软 double 库运行结果，然后再收窄回 float。

测量影响：

  • hsv_to_rgb 代码大小：ESP32 上从 108 字节降至 69 字节（-36%）
  • 消除的软 double 辅助函数调用：每个调用点约 8 次
  • 涉及的组件：display、light、climate、大多数传感器驱动、openthread、mqtt、 speaker、graph 等等

最后一波收尾（#17260）还将 sx126x 中的热点表达式如 std::pow(2, sf) 重写为 constexpr 位移，并将几个调用点切换为 std::numbers::pi_v<float>。

内存：ESP8266 DRAM 节省

Section titled “内存：ESP8266 DRAM 节省”

ESP8266 上的每个字节 RAM 都很重要，由 @bdraco 进行的三项聚焦更改在不改变运行时行为的情况下回收了可观的 DRAM。

  • libstdc++ 抛出消息字符串（#17341）——覆盖 std::__throw_* 辅助函数以丢弃从未读取的消息参数。在一个 ratgdo 构建上节省约 96 字节 RAM。崩溃行为不变。
  • lwIP glue DHCP 存根字符串（#17395）——dhcp_cleanup() 和 dhcp_release() 存根的静默等效实现。释放 48 字节 RAM 和 88 字节闪存，并移除每次 WiFi 断开时嘈杂的 STUB: dhcp_cleanup 日志。
  • dashboard_import 包 URL（#17127）——将 mDNS TXT package_import_url 字符串从 .rodata（DRAM）移至闪存。这是最后一个被固定在 RAM 中的 mDNS TXT 值。

构建系统：ccache 与共享工具链缓存

Section titled “构建系统：ccache 与共享工具链缓存”

由 @swoboda1337 主导，ESP-IDF 和 nRF SDK 工具链同时获得了编译器级缓存和安装级共享。

ESP-IDF 构建现在默认启用 ccache（#17163、 #17136），当 ccache 二进制文件存在时，使用依赖模式（depfile 哈希而非预处理）和 IDF 工具路径下的缓存目录。可通过 IDF_CCACHE_ENABLE=0 退出。在 23 批 CI 矩阵中，累计 runner 时间从 543 分钟降至 504 分钟（约 7%），墙钟时间从 154 分钟降至 139 分钟。

工具链现在安装到机器全局缓存目录 （#17306、 #17353）。ESP-IDF 安装到 ~/.cache/esphome/idf，nRF Connect SDK 安装到 ~/.cache/esphome/sdk-nrf，因此多 GB 的工具链安装在机器上的每个项目之间共享，而非按配置复制。Docker 和 Home Assistant 插件用户将其固定到持久卷，现有安装会在升级后重新下载一次。

配置验证也更快了，感谢 @frenck 的导入延迟： aioesphomeapi.posix_tz 延迟使主机配置的 esphome config 中位墙钟时间减少约 33%，从 445 ms 降至 297 ms （#17214），延迟 requests 导入再节省约 70 ms（约 16%） （#17215）。

组件别名基础设施

Section titled “组件别名基础设施”

一个新的核心机制（#16826）允许重命名组件而不破坏现有 YAML 配置。组件声明 ALIASES = [...]（以及可选的 ALIAS_REMOVAL_VERSION），配置验证中的预扫描会重写旧键，同时 sys.meta_path 查找器解析 esphome.components.<oldname> 的 Python 导入。别名通过 AST 扫描发现，因此组件无需导入即可枚举。

新基础设施的第一个用户是 rp2 重命名 （#17145，由 @jesserockz 提交），将 rp2040 平台重命名为 rp2 以反映其对 RP2040 和 RP2350 两者的覆盖。旧版 rp2040: YAML 键和 esphome.components.rp2040 导入继续作为弃用别名工作，将在 2027.7.0 中移除。新的 rp2_2040 和 rp2_2350 变体 kwargs 已添加到 SplitDefault 和 require_framework_version 中，与 ESP32 模式一致。

Modbus 全面改造

Section titled “Modbus 全面改造”

@exciton 通过多个 PR 完成了对 modbus 组件的重大改造。

客户端与服务器拆分（#11969）——Modbus 被拆分为 ModbusClientHub 和 ModbusServerHub，彻底退役了角色枚举。客户端组件移至 ModbusClientDevice（#11987），核心 API 表面在发布前重命名并稳定 （#17434、 #17378）。外部组件需要立即根据新 API 更新，下一版本计划进一步的客户端模式 API 清理。

重写解析器——逐字节解析被替换为基于缓冲区、感知帧长度的解析器，正确处理对端服务器响应、不支持的功能码和自定义功能码。响应跟踪使用 std::optional<ModbusDeviceCommand>，启用地址+功能码匹配、每个地址多个设备，以及两个新回调：on_modbus_no_response() 和 on_modbus_not_sent()。

无堆发送路径——新的 SmallInlineBuffer<8> 和 StaticVector<uint8_t, MAX_PDU_SIZE> 意味着 8 字节 Modbus 帧（读取和单寄存器写入的常见情况）内联在 deque 节点中，每帧零堆活动（#17282）。

服务器改进（#17205）——多寄存器值现在按完整跨度匹配，新增 allow_partial_read 选项，重叠寄存器被拒绝，过时的 RAW 值类型已从服务器模式中移除。

默认 send_wait_time 从 250ms 移至 2000ms，turnaround_time 从 100ms 移至 600ms。如果您以前是为了补偿旧解析器而覆盖这些值，请重新评估是否仍需要这些覆盖。

LVGL：动画、旋转与运行时更新

Section titled “LVGL：动画、旋转与运行时更新”

@clydebarrow 在本版本中对 lvgl 组件进行了大幅扩展。

  • 动画（#16796）——完整的 LVGL 动画支持，包括 from/to 插值、计时函数（gravity 等）、持续时间、循环和 auto_start。
  • 动态旋转（#16773）——以度为单位的模板化 lvgl.display.set_rotation，新的 on_landscape 和 on_portrait 触发器，以及 lvgl.update 中的布局选项更新。
  • 直接的 mapping 语法（#15863）——更简洁的 LVGL 文本和图像 src 更新，直接使用 mapping。
  • 启动暂停（#16973）——新的 paused 配置选项在启动时抑制 LVGL 更新。对于不应在 API 连接前渲染无效状态的电子墨水屏尤其有用。
  • 显示繁忙期间继续活动（#17374）——当使用 update_when_display_idle（电子墨水屏常见）时，LVGL 现在在显示刷新进行时仍处理用户输入并运行计时器。LVGL 刷新间隔（之前固定为 16 ms）现在可配置。

网络与连接

Section titled “网络与连接”

ESP32-S31 上的千兆以太网（#17277）——为新的支持 RGMII 的 ESP32-S31 变体添加了 type: GENERIC 和 type: YT8531 PHY，需要 ESP-IDF 6.1。YT8531 处理器覆盖自动协商重新启用和 RGMII Tx/Rx 延迟。ethernet 组件上新增了 power_pin 和 phy_registers 选项。

ESP-NOW v2 负载（#17360）—— espnow 组件新增 max_payload_size 选项，接受高达 1470 字节的帧（之前限制为 250）。默认值仍为 250；升至 1470 约消耗 44 KB RAM，默认值约 8 KB。需要 ESP-IDF ≥ 5.4 或 Arduino ≥ 3.2。

LN882X MQTT 支持（#17297）——LN882H 板终于可以 使用 mqtt 组件了。此前 LN882X 尽管共享 LibreTiny 后端却被阻止。

SX126x 数据增白（#17102）——通过新的 whitening_enable 和 whitening_initial 选项配置 FSK 数据增白（CCITT 算法）。

Bluetooth proxy 订阅者语义（#17423）——较晚的 订阅者现在接管单个订阅者槽位，取代陈旧的订阅者，而不是被静默拒绝。这修复了在 Home Assistant 重启后可能出现的”已连接但无广告”状态（在约 150 秒的保活窗口内）。用户无需更改配置，但观察到的行为确实发生了变化。

Zephyr/nRF52 上的 OpenThread 与 MTD 轮询控制

Section titled “Zephyr/nRF52 上的 OpenThread 与 MTD 轮询控制”

基础 Zephyr/nRF52 支持（#16854）—— 由 @Ardumine 完成的 nRF52 Zephyr 平台上首次 openthread 支持。处理”加入网络”流程。

运行时轮询周期控制（#11766）——新的 set_poll_period 动作让最小线程设备（Sleepy End Device）临时切换到无线电常开以进行 OTA。http_request.ota 在 MTD 上速度提升约 10x，esphome.ota 也能开始正常工作。

ESP32 上的 RTC 支持偏好设置

Section titled “ESP32 上的 RTC 支持偏好设置”

@bootc 让 ESP32 偏好设置后端遵守 make_preference() 的 in_flash=false 标志 （#17073），以与 ESP8266 相同的方式添加了 RTC 内存支持的偏好设置。共享字缓冲区加校验和格式提取到 preferences_rtc.h 中。

新的配置界面：

  • safe_mode: storage: rtc 或 flash
  • wifi: fast_connect: 字典形式，带 enabled 和 storage 子选项
  • preferences: rtc_storage: true

ESP32-C2 和 ESP32-C61 没有 RTC RAM，会优雅回退。这是计划中的 DHCP 租约缓存的基础，已在 ESP32 PICO、S3、C3 和 C6 硬件上验证。

新显示屏、触摸控制器与外设

Section titled “新显示屏、触摸控制器与外设”

本次发布新增了对新显示和触摸硬件的广泛支持，主要集中在 M5Stack、Waveshare 和 Seeed reTerminal 系列。

触摸控制器——cst328 由 @latonita 提交（#8011）、 st7123 为 M5Stack Tab5 集成的显示屏触摸驱动，由 @miniskipper 提交（#12075）、 gsl3670 用于 Seeed reTerminal D1001，由 @clydebarrow 提交（#16285），以及 cst9220 覆盖 CST9220 和 CST9217，由 @clydebarrow 提交（#16888）。

电子墨水屏显示屏——epaper_spi 组件新增了多个面板： Waveshare 7.5” V2 BWR 800×480 由 @twisterss 提交 （#15719）、 Seeed reTerminal E1004 13.3” 6 色（T133A01，双 CS SPI）由 @limengdu 提交 （#16706）、 Waveshare 2.13” V4 BWR（SSD1683）由 @profplump 提交 （#16828）、 Soldered Inkplate 2 由 @arunderwood 提交 （#16856）， 以及 Seeed reTerminal-sticky 由 @clydebarrow 提交 （#16950）。it8951 电子墨水控制器，支持 M5Paper 和 Seeed reTerminal E1003/EE03（最高 1872×1404，16 级灰度），作为新组件由 @Passific 提交 （#15346）。

MIPI-SPI 显示屏——M5STACK ATOM3SR 由 @clydebarrow 提交 （#17344）和 Waveshare ESP32-S3-Touch-AMOLED-1.64（SH8601） 由 @crimike 提交（#17386）。

Divoom Pixoo 64——新的 pixoo 组件由 @jesserockz 提交（#16974），通过 SPI 驱动 64×64 RGB LED 矩阵，并为面板亮度暴露了灯光平台以及图像 API。

传感器与外设——ufm01 ScioSense UFM-01 超声波流量计由 @ljungqvist 提交（#16582），通过 UART 报告累积流量、流速、水温以及四个诊断二进制传感器。qmi8658 6 轴 IMU 由 @clydebarrow 提交（#16889），新增加速度计、陀螺仪和片上温度传感，带 motion 平台。waveshare_io_ch32v003 I/O 扩展器由 @latonita 提交（#10071），覆盖 Waveshare 较新 S3 板上的 CH32V003 扩展器，提供 EXIO GPIO、PWM 背光控制、ADC 电池电压传感器和 RTC 中断状态。

音频——pcm5122 组件新增模拟增益（0/-6 dB）、通道混音 （立体声/左/右/交换）、可配置音量范围、待机/断电开关和 XSMT 使能引脚，同时修复了一个时钟寄存器页 Bug，该 Bug 一直静默破坏时钟设置 （#17313），由 @remcom 提交。i2s_audio 扬声器现在接受更宽的流（例如 24 位输入到 16 位设备），并使用 esp-audio-libs 的 pcm_convert::copy_frames 就地收窄 （#16821）。

图像组件变为平台

Section titled “图像组件变为平台”

@jesserockz 将 image: 重构为平台组件 （#17416）。新形式使用 platform: file、 platform: animation 和 platform: online_image，其中 animation 成为新文件平台的正式子组件。旧版顶层 image:、animation: 和 online_image: 键在 2027.1.0 之前继续工作，验证时会显示复制粘贴迁移警告。

Zigbee：SDK 2.0.2 与端点合并

Section titled “Zigbee：SDK 2.0.2 与端点合并”

@luar123 将 ESP32 上的 zigbee 组件升级到了新的 esp-zigbee-sdk 2.0.2，以获得更好的 ESP-IDF 兼容性，并支持 ESP32-H4、H21 和 S31 变体 （#16869）。专用的 Zigbee 存储分区已退役，改为默认 NVS，报告配置也简化了：enabled/coordinator 区分已取消。

后续跟进（#17402）合并 ESP32 上组件的端点，允许用户手动组合它们。这使得单端点设备可以拥有多个传感器，符合 Zigbee 标准预期。两个 PR 都要求现有 Zigbee 设备在升级后重新加入、重新访谈和重新配置。

YAML 合并警告

Section titled “YAML 合并警告”

@clydebarrow 添加了一个警告，当 YAML 合并（<<:）静默丢弃键时触发 （#17246）。两个顶层 api: 块通过 <<: 合并以前会丢弃一个而不做任何指示；ESPHome 现在会打印源位置，解释正在进行合并，并建议使用 packages: 进行深度合并。可通过 esphome: merge_warnings: false 切换。

其他值得注意的功能

Section titled “其他值得注意的功能”
  • 旧版 Web 仪表盘已移除（#17124）——内置的 Tornado 仪表盘已移除，改为外部的 ESPHome 设备构建器。dashboard CLI 命令保留但隐藏，并打印迁移提示。Docker 和 Home Assistant 插件用户不受影响：他们已经路由到设备构建器。
  • 放弃 Python 3.11 支持（#17280）——最低 Python 版本现在为 3.12。Home Assistant 插件和 Docker 镜像已在 3.12 上。
  • BK7238 与 Tuya T1 板支持（#17288）—— LibreTiny 1.13.0 更新将 BK7238 板添加到 bk72xx 平台： generic-bk7238、generic-bk7238-tuya 和 Tuya T1 模块系列（t1-2s、t1-3s、t1-m、t1-u），在市场上设备中正变得常见。
  • ESP32-S31 和 H4 的 PSRAM（#17192）——两个新变体均获得 PSRAM 接线：S31 八线模式 40/100/200/250 MHz，H4 四线模式 32/64 MHz。值来自 ESP-IDF release/v6.1 上的 esp_psram Kconfig，八线模式验证现在由数据驱动，而非硬编码到 S3。
  • 主机平台偏好目录（#11160）——新的 ESPHOME_PREFDIR 环境变量覆盖 host 平台存储偏好的位置，在将 ESPHome 作为系统服务运行时（HOME 可能未设置）很有用。
  • Web 服务器 SSE 优化（#17400）——Logger 的已知消息长度现在通过 SSE 发送路径，避免了每次日志事件时的 strlen 和 strchr 重扫描。无线路变化。
  • Web 服务器 HTTP 摘要认证（#17541）—— web_server 的 auth: 新增 type: 选项以选择 basic 或 digest。摘要认证将密码留在网络之外（仅发送哈希），而不是 Basic 使用的可轻松逆推的 Base64；两者在浏览器中看起来相同。该方案在构建时固定，以便未使用的代码路径被编译掉。默认值暂为 basic 以避免破坏非浏览器 REST 客户端，将在 2027.1.0 改为 digest；之后如需保持当前行为请显式设置 type: basic。
  • WiFi 漫游扫描抑制（#17012）——新的内部 API 允许组件请求暂停连接后的漫游扫描。第一个用户是 sendspin，现在在播放时抑制漫游扫描以防止可听见的卡顿 （#17133）。
  • 运行时 UART 重新配置（#16990）——波特率、校验和其他 UART 设置现在可以在已打开的通道上运行时更改，而无需重新连接。已同时适用于标准 uart 和 usb_uart 组件。
  • 关闭时亮度保留（#17103）——将亮度设置为 0 不再静默钳位到 1.0。如果随后的开启没有显式亮度且当前亮度为 0，则在开启时将亮度设置为 1.0。
  • coex/sdkconfig 协调器（#17008）——单个协调器现在处理 ESP32 上的 WiFi/以太网/BLE 共存 sdkconfig 标志，消除冲突值（例如 ethernet 与 esp32_ble_tracker 在 CONFIG_SW_COEXIST_ENABLE 上）。行为保持不变，内部辅助函数获得语义名称如 request_wifi、request_ethernet 和 request_software_coexistence。
  • 可视化编辑器可见性提示（#17449）——构建系统和框架内部现在标记 cv.Visibility，以便设备构建器可视化编辑器可以将其从通过浏览器编辑 YAML 的用户中隐藏。

感谢贡献者

Section titled “感谢贡献者”

本版本包含了来自 30 多位贡献者的 217 个拉取请求。衷心感谢让 2026.7.0 成为可能的所有人：

  • @swoboda1337 - 45 个 PR，包括将 ESP-IDF 设为 esp32 默认工具链、树级单精度浮点运算扫描、ESP32-S31/H4/H21 支持、ccache 和共享工具链缓存、千兆以太网、ESP-NOW v2 负载，以及放弃 Python 3.11
  • @jesserockz - 45 个 PR，包括通用组件别名基础设施、跨越 21 批次的 final 类扫描、[pixoo] Divoom Pixoo 显示组件、[rp2] 平台重命名、[image] 平台重构，以及移除旧版 Web 仪表盘
  • @clydebarrow - 17 个 PR，包括 LVGL 动画、动态旋转、启动暂停和显示繁忙期间继续活动、新的 [gsl3670] 和 [cst9220] 触摸屏、[qmi8658] IMU motion 平台、[mipi_spi] M5STACK ATOM3SR、YAML 合并丢弃警告，以及关闭时亮度保留
  • @exciton - 9 个 PR，包括重大的 [modbus] 解析器重写和客户端/服务器中心拆分、无堆发送路径、带部分读取的寄存器范围修复，以及最终确定的 API 表面
  • @tomaszduda23 - 8 个 PR，构建原生 nRF52 构建：原生 SDK 支持、上传流程、配置输入重建触发器、非 nRF52840 板支持、libc 选择，以及 OTA 错误报告
  • @kahrendt - 6 个 PR，包括 WiFi 漫游扫描抑制、[sendspin] 播放集成、[i2s_audio] 流收窄，以及 microMP3 升级
  • @Ardumine - 5 个 PR，扩展 nRF52/Zephyr 网络：BSD 套接字支持、基础 OpenThread、mDNS、[api] 支持，以及更大的 Zephyr 网络缓冲区
  • @kbx81 - 4 个 PR，包括 ESP32 NVS 加密、OTA 降级保护、新的 [provisioning] 组件，以及 ESP32 网络/共存 sdkconfig 协调器
  • @p1ngb4ck - 4 个 PR，包括 [usb_uart] 每设备波特率上限、FTDI RX 稳定性修复，以及向量 pop_back 辅助函数
  • @luar123 - 3 个 PR，包括 [zigbee] SDK 2.0.2 升级和 esp32 上的端点合并
  • @frenck - 3 个 PR，延迟 aioesphomeapi 和 requests 导入以加快配置验证，以及精炼 ESP32-S3 PSRAM 引脚警告
  • @latonita - 2 个 PR，包括新的 [cst328] 触摸屏和 [waveshare_io_ch32v003] I/O 扩展器
  • @rwrozelle - 2 个 PR，包括 [openthread] 面向 MTD 的 set_poll_period 动作和 [socket] 唤醒请求门控修复
  • @anunayk - 2 个 PR，包括 Zephyr GPIO 中断和 [ble_nus] 原子日志帧
  • @remcom - 2 个 PR，包括 [pcm5122] 模拟增益、通道混音以及待机/断电工作，加上 [audio_file] MP3 检测修复
  • @miniskipper - 新的 [st7123] 触摸控制器组件，用于 M5Stack Tab5
  • @Passific - 新的 [it8951] 电子墨水控制器组件
  • @ljungqvist - 新的 [ufm01] 超声波流量计组件
  • @bootc - ESP32 上 RTC 支持的偏好设置，遵守 in_flash 标志

同时还要感谢 @bdraco、@haku、 @Eelviny、@twisterss、 @ddrown、@limengdu、 @profplump、@arunderwood、 @kyvaith、@jspiros、 @guillempages、@zeroflow、 @mikelawrence、@jclehner、 @berikv、@Bl00d-B0b、 以及 @crimike 的贡献，以及所有报告问题、测试预发布版本和在社区中提供帮助的每一个人。

破坏性变更

Section titled “破坏性变更”

平台变更

Section titled “平台变更”
  • ESP32：未显式设置 toolchain: 时，ESP-IDF 现为默认工具链。请在您的 esp32: 块中添加 toolchain: platformio 以继续使用 PlatformIO 构建 #16910
  • Python：最低支持的 Python 版本提升至 3.12。Home Assistant 插件和 Docker 不受影响；仅有 3.11 上的直接 pip 安装需要升级 #17280
  • nRF52：未显式设置 toolchain: 时，原生 nRF Connect SDK 工具链现为默认。请在您的 nrf52: 块中添加 toolchain: platformio 以继续使用 PlatformIO 构建 #17319
  • nRF52：Zephyr DCDC 设置不再由 ESPHome 强制，这会根据板设置略微改变生成代码，并允许为没有 DCDC 的板构建 #17373

仪表盘

Section titled “仪表盘”
  • 旧版仪表盘：内置的 Tornado Web 仪表盘已移除。通过 pip 安装的用户应安装并运行 esphome-device-builder 代替。Docker 和 Home Assistant 插件用户不受影响 #17124

组件变更

Section titled “组件变更”
  • Bluetooth Proxy：最新的广告订阅者现在接管单个订阅者槽位，取代陈旧的订阅者，而不是被拒绝。修复了 Home Assistant 重启后”已连接但无广告”的问题（在约 150 秒的保活窗口内） #17423
  • Hub75：已弃用的 scan_wiring 名称 FOUR_SCAN_16PX_HIGH、FOUR_SCAN_32PX_HIGH 和 FOUR_SCAN_64PX_HIGH 已移除。请改用 SCAN_1_4_16PX_HIGH、SCAN_1_8_32PX_HIGH 和 SCAN_1_8_64PX_HIGH #17118
  • Light：将亮度设置为 0 不再静默钳位到 1.0。如果随后的开启没有显式亮度且当前亮度为 0，则在开启时将亮度恢复为 1.0 #17103
  • LibreTiny（LN882H）：generic-ln882hki 板已移除；请根据出厂固件使用 generic-ln882h 或 generic-ln882h-tuya。LN882H 默认日志 UART 现为 UART1。LN882H 分区布局已变更（设备端 OTA 迁移由 LibreTiny 处理）。在 wb02a 板上，引脚别名已变更（D1 → GPIO6、D7 → GPIO5、D8 → GPIO9、D9 → GPIO24、新的 D10 → GPIO25），默认 I2C 引脚顺序已变更 #17288
  • Modbus：disable_crc 选项已移除，服务器模式中的 send_wait_time 和 turnaround_time 也已移除。客户端模式默认值已提升：send_wait_time 250ms → 2000ms，turnaround_time 100ms → 600ms #11969
  • Packages：单包 !include 形式已移除。请将 include 包装在列表中： packages: [!include mypackage.yaml] #17119
  • Web Server：已弃用的对象 ID URL 匹配回退已移除。URL 仅按实体名称匹配 #17113
  • Web Server：版本 1 已弃用。设置 version: 1 时会发出配置警告；计划在 2027.1.0 移除。请迁移到 v2（默认）或 v3 #17109
  • Web Server：携带 Origin 头的跨域浏览器请求现在会被拒绝，除非来源与请求 Host（同源）匹配或列在新的 allowed_origins: 选项中。没有 Origin 头的请求（curl、原生 API、其他非浏览器客户端）始终允许，因此这是针对浏览器混淆委托人/CSRF 情况的纵深防御，而非认证边界。私有网络访问现在默认关闭（以前为开启），启用时复用 allowed_origins: 授权预检；在没有允许来源的情况下启用 PNA 会在配置验证时拒绝 #17530
  • Zigbee：Zigbee SDK 升级到 2.0.2 改变了存储布局，因此 ESP32 设备在升级后必须重新加入和重新配置。reporting: 配置值 enabled 和 coordinator 不再有效 #16869
  • Zigbee：在 ESP32 上端点合并现在默认合并组件的端点，并允许用户手动组合。现有配置需要重新加入、重新访谈和重新配置 #17402
  • 显示组件：MIPI 系列显示驱动（mipi_spi、mipi_dsi 和 mipi_rgb）现在强制执行 PSRAM 和 I/O 扩展器等必需组件的配置。这仅适用于识别具有已知硬件分配的集成板的显示型号。 #17405

未记录的 API 变更

Section titled “未记录的 API 变更”

调用内部字符串格式化辅助函数的 lambda 用户应注意以下移除。两种方法都在 6 个月前被弃用，改用避免 std::string 分配的基于缓冲区的变体。

  • Core：value_accuracy_to_string() 已移除。请使用 value_accuracy_to_buf()，它写入调用者提供的 VALUE_ACCURACY_MAX_LEN 字节的缓冲区。 #17116

    Before:

    std::string s = value_accuracy_to_string(value, accuracy);

    After:

    char buf[VALUE_ACCURACY_MAX_LEN];
    value_accuracy_to_buf(buf, value, accuracy);

  • Remote Base（Midea）：MideaData::to_string() 已移除。请改用 to_str(buffer)，它将格式写入调用者提供的缓冲区。#17117

    Before:

    std::string s = data.to_string();

    After:

    char buf[32];
    data.to_str(buf);

  • Dashboard Import（ESP8266）：package_import_url 现在作为 PROGMEM 闪存字面量 （ProgmemStr）存储，而非 DRAM 中的普通 const char *。现有消费者已将其作为闪存指针读取（mDNS 通过 MDNS_STR_ARG，MQTT 通过 ArduinoJson 的 __FlashStringHelper 重载），因此在 ESP8266 上这是透明变更，在其他平台上无操作。在 ESP8266 上读取 package_import_url 的 lambda 不应将其作为普通 const char * 解引用。 #17127

开发者的破坏性变更

Section titled “开发者的破坏性变更”
  • Modbus API 拆分：Modbus 被拆分为 ModbusClientHub 和 ModbusServerHub； ModbusDevice::set_parent() 现在接受 ModbusClientHub *；Modbus::register_device() 已移除 （#11969、 #11987、 #12376）
  • Modbus API 命名：核心公开 API 表面在发布前重命名并稳定；下一版本计划进一步的客户端模式 API 清理 （#17378、 #17434）
  • Modbus 功能码比较：移除了 ModbusFunctionCode 和 uint8_t 之间的排序运算符（<、<=、>、>=）。请显式转换或使用 helpers::is_function_code_*() #11969
  • Select state 成员已移除：请改用 current_option() 或 active_index() #17027
  • Scheduler std::string 重载已移除：App.scheduler.set_timeout(std::string, ...) 及相关 std::string 名称重载已删除；请传递 const char * 名称 #17111
  • get_object_id() 和 get_compilation_time() 已移除：之前弃用的核心辅助函数已删除 #17112
  • 返回 std::string 的 GPIOPin::dump_summary() 已移除：重写必须通过缓冲区形式返回 #17115
  • UART load_settings(bool) 现在为纯虚函数：所有 UARTComponent 子类必须实现运行时设置更新 #16990
  • API 预-1.14 object_id 向后兼容已移除：旧客户端回退路径已删除 #17108
  • Preferences RTC 辅助函数已移动：字缓冲区 + 校验和格式提取到 preferences_rtc.h 并在 ESP32/ESP8266 之间共享 #17073
  • Network use_address 日志记录变更：运行时 MAC 后缀扩展移入网络组件 #17432
  • 可配置类标记为 final：约 20 批组件向其运行时实例化的具体类添加 final 以允许去虚拟化 （#16952-#16972、 #17129、 #17130、 #17147）
  • rp2040 组件重命名为 rp2：Python 导入 esphome.components.rp2040 和 rp2040: YAML 键 在 2027.7.0 之前通过新的别名基础设施继续作为弃用别名工作 （#17145、 #16826）
  • mipi_ 显示驱动程序模型配置变更：在模型定义中使用 swap_xy=cv.UNDEFINED 已弃用。 #17405

有关详细的迁移指南和 API 文档，请参见 ESPHome 开发者文档。

版本 2026.7.1 - 7月21日

Section titled “版本 2026.7.1 - 7月21日”

版本 2026.7.2 - 7月23日

Section titled “版本 2026.7.2 - 7月23日”

版本 2026.7.3 - 7月28日

Section titled “版本 2026.7.3 - 7月28日”

版本 2026.7.4 - 8月5日

Section titled “版本 2026.7.4 - 8月5日”

完整变更列表

Section titled “完整变更列表”

新功能

Section titled “新功能”

新组件

Section titled “新组件”
  • [ufm01] 添加 UFM-01 超声波流量计组件 esphome#16582 by @ljungqvist (new-component) (new-feature) (new-platform)
  • [waveshare_io_ch32v003] Waveshare I/O 扩展器组件 esphome#10071 by @latonita (new-component) (new-feature) (new-platform)
  • [it8951] 为 epaper_spi 添加 IT8951 电子墨水控制器支持 esphome#15346 by @Passific (new-component) (new-feature) (new-platform)
  • [qmi8658] QMI8658 IMU 的 motion 平台 esphome#16889 by @clydebarrow (new-component) (new-feature) (new-platform)
  • [cst9220] 添加 CST9220 和 CST9217 触摸屏支持 esphome#16888 by @clydebarrow (new-component) (new-feature) (new-platform)
  • [pixoo] 添加 Divoom Pixoo 显示组件 esphome#16974 by @jesserockz (new-component) (new-feature) (new-platform)
  • [st7123] 添加 ST7123 触摸控制器组件（M5Stack Tab5） esphome#12075 by @miniskipper (new-component) (new-feature) (new-platform)
  • [cst328] 触摸屏（Waveshare ESP32-S3-Touch-LCD-2.8） esphome#8011 by @latonita (new-component) (new-feature) (new-platform)
  • [provisioning] 添加配置窗口 esphome#17152 by @kbx81 (new-component) (new-feature)
  • [image] 重构为平台组件 esphome#17416 by @jesserockz (new-component) (new-feature)
  • [gsl3670] 添加新的触摸屏组件 esphome#16285 by @clydebarrow (new-component) (new-feature) (new-platform)

新平台

Section titled “新平台”
  • [ufm01] 添加 UFM-01 超声波流量计组件 esphome#16582 by @ljungqvist (new-component) (new-feature) (new-platform)
  • [waveshare_io_ch32v003] Waveshare I/O 扩展器组件 esphome#10071 by @latonita (new-component) (new-feature) (new-platform)
  • [it8951] 为 epaper_spi 添加 IT8951 电子墨水控制器支持 esphome#15346 by @Passific (new-component) (new-feature) (new-platform)
  • [qmi8658] QMI8658 IMU 的 motion 平台 esphome#16889 by @clydebarrow (new-component) (new-feature) (new-platform)
  • [cst9220] 添加 CST9220 和 CST9217 触摸屏支持 esphome#16888 by @clydebarrow (new-component) (new-feature) (new-platform)
  • [pixoo] 添加 Divoom Pixoo 显示组件 esphome#16974 by @jesserockz (new-component) (new-feature) (new-platform)
  • [st7123] 添加 ST7123 触摸控制器组件（M5Stack Tab5） esphome#12075 by @miniskipper (new-component) (new-feature) (new-platform)
  • [cst328] 触摸屏（Waveshare ESP32-S3-Touch-LCD-2.8） esphome#8011 by @latonita (new-component) (new-feature) (new-platform)
  • [pcm5122] 添加模拟增益、通道混音、音量范围、待机/断电开关和 XSMT 使能引脚支持 esphome#17313 by @remcom (new-feature) (new-platform)
  • [gsl3670] 添加新的触摸屏组件 esphome#16285 by @clydebarrow (new-component) (new-feature) (new-platform)

破坏性变更

Section titled “破坏性变更”

所有变更

Section titled “所有变更”