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

ESPHome 2026.5.0 - 2026 年 5 月

Sendspin
Sendspin ​媒​体​源​
Sendspin ​组​
Sendspin ​传​感​器​
Sendspin ​文​本​传​感​器​
射​频​核​心​
音​频​ ​HTTP ​媒​体​源​
Modbus ​服​务​器​

版本概览

Section titled “版本概览”

ESPHome 2026.5.0 的核心变化是全新的 ESPHome 设备构建器 进入公开测试，这是一个从头重写的 Web 应用，取代了旧版内置仪表盘，提供了真正的配置编辑器、固件任务队列、多选批量操作、标签与区域、不同步检测、跨配置搜索、分布式构建以及完善的设置界面。在固件层面，主循环、调度器和任务看门狗进行了根本性重构，在每个平台上都恢复了可观的 CPU 和功耗，同时对 API、音频和辅助热点路径进行了广泛的实测优化。原生 ESP-IDF 工具链与 PlatformIO 并行发布，并完成了 ESP-IDF v6.0.1 的准备工作；音频解码管线基于新的 microMP3 / microWAV / microFLAC 流式库进行了现代化改造。OTA 获得了多年来最丰富的功能集，包括分区表更新、引导程序更新、Web 服务器 OTA 和软变砖恢复；此外，基于 ESP32 的 Zigbee、全新的 Sendspin 多房间音频组件系列、崭新的 radio_frequency 实体类型、扩展的 nRF52 / Zephyr 平台工作，以及大规模代码库正确性扫尾，共同构成了本次发布。

升级检查清单

Section titled “升级检查清单”
  • 如果您在服务器模式下使用 modbus_controller，请迁移到新的 modbus_server 组件，并将 server_registers 重命名为 registers，将 server_courtesy_response 重命名为 courtesy_response
  • 如果您在 esp32、bk72xx、rtl87xx 或 ln882x 上依赖超过 5 个并发 API 连接，请显式设置 api.max_connections（默认值已从 8 降至 5）
  • 如果您仅通过 YAML 操作向任意 URL 播放 WAV 文件（非嵌入、非设为首选管线格式），请添加 audio: codecs: wav: 以确保 WAV 解码仍被编译
  • 如果您在 speaker 媒体播放器上使用 codec_support_enabled，请弃用该项，改用管线 format: 设置（format: NONE 包含所有编解码器，format: WAV 对应旧版的 none/false 模式）
  • 如果您通过 files: 块将大于 5 MB 的音频文件嵌入 speaker 媒体播放器，请在升级前压缩它们或选择更高效的编解码器
  • 如果您有多个使用不同端口的 ota: - platform: esphome 条目，请合并为单个端口上的一个条目
  • 如果您使用 throttle_average 过滤器且 time_period 超过 24 小时，请降低该值（新模式上限为 24 小时）
  • 如果您的 lambda 在 FloatOutput 上调用 id(...).set_min_power(...)、set_max_power(...) 或 set_zero_means_zero(...)，请在某个 output: 条目中添加 min_power: 0%（或任一缩放键），以使运行时设置器保持编译
  • 如果您的外部组件实现了 ComponentIterator 且不处理媒体播放器，请添加由 #ifdef USE_MEDIA_PLAYER 保护的 bool on_media_player(media_player::MediaPlayer *obj) override { return true; }
  • 如果您的外部组件或 lambda 调用了 OneWireBus::skip()，请处理新的 bool 返回值（false 表示复位/存在脉冲失败；退出而非写入死总线）
  • 如果您的外部组件以无参数方式构造 PollingComponent() 且从不调用 set_update_interval()，请显式传入间隔；默认构造函数不再轮询
  • 如果您的外部组件使用来自 esphome/core/ring_buffer.h 的 esphome::RingBuffer，请切换到来自 esphome/components/ring_buffer/ring_buffer.h 的 esphome::ring_buffer::RingBuffer 并添加 AUTO_LOAD = ["ring_buffer"]
  • 如果您的外部组件使用分配堆内存的辅助函数（如 str_lower_case、format_hex、format_mac_address_pretty、value_accuracy_to_string 或 base64_encode），请直接包含 esphome/core/alloc_helpers.h（helpers.h 的重导出是临时的）
  • 如果您维护外部 climate 平台，请用 add_feature_flags() / has_feature_flags() 替换已弃用的 set_supports_* / get_supports_* 访问器（注意 two_point_target_temperature 映射为 CLIMATE_REQUIRES_TWO_POINT_TARGET_TEMPERATURE）
  • 如果您通过 ble_client 保持长生命周期 BLE 连接并注意到 WiFi 吞吐量下降，这是新的 esp32_ble_tracker 共存行为；如果它严重影响您的工作负载，请提交问题并附上您的配置
  • 如果您的 ektf2232 配置仍使用 rts_pin，请将其重命名为 reset_pin（友好的迁移错误已被移除）

介绍全新的 ESPHome 设备构建器（测试版）

Section titled “介绍全新的 ESPHome 设备构建器（测试版）”

全新的 ESPHome 设备构建器在 State of the Open Home 2026 上宣布 现已进入公开测试，它是旧版内置仪表盘的全新替代品。它托管在两个新仓库中：device-builder（Python 后端）和 device-builder-frontend（Web UI），通过稳定的公开接口调用 ESPHome，而非深入内部模块。这项工作由 Open Home Foundation 生态系统部门 驱动，该部门去年大幅扩展，使 OHF 能为社区提供更多支持，并与现有的维护者社区协同工作。大部分重写工作针对现有用户多年来一直受阻的仪表盘功能（任务队列、多选批量操作、标签/区域、不同步检测、跨配置搜索、分布式构建、真正的设置 UI）。可视化编辑以及与 Apollo Automation ESPHome 入门套件 (ESK-1) 等硬件的配对，也使该应用成为新用户的合理起点。

旧版仪表盘不具备的功能：

  • 配合 Monaco YAML 的可视化组件和自动化构建器，以及左侧边栏设备导航器。旧版仅是在 .yaml 文件上的 Ace 文本编辑器，没有一等组件或自动化对象。
  • 带有依赖解析的组件目录，以及每板引脚信息查看器，可映射 GPIO 能力并显示哪些组件正在使用每个引脚。
  • 带有进度、历史记录和取消的固件任务队列（编译/安装/清理）。旧版一次只运行一个操作，无并发或历史记录。
  • 远程构建器。 一个设备构建器实例可以通过同侪配对链接（mDNS 发现、SHA-256 指纹确认、身份轮换、每对同侪自动路由）将编译/安装任务卸载到另一个实例。
  • 标签（彩色、可搜索、可过滤）、作为一等字段的区域、作为独立可编辑字段的友好名称、设备克隆，以及多选批量操作（对任意设备子集进行更新/删除/归档）。旧版唯一的批量操作是全有或全无的“全部更新”。
  • 带有每设备徽标的不同步检测（版本、配置哈希、加密状态不匹配）。旧版只显示“有可用更新”。
  • YAML 差异视图、带上下文的跨配置 YAML 搜索，以及命令面板（⌘K / Ctrl-K）。
  • 带有可配置列和分面过滤器的卡片和表格视图（平台/状态/区域/标签）。旧版只有卡片视图。
  • 真正的设置 UI，支持亮色/暗色/系统主题、英语/法语/荷兰语本地化、编辑器布局和远程构建器控件。旧版几乎未在 UI 中暴露任何设置。
  • 首次运行 Wi-Fi 引导和USB 插入检测，当连接板卡时提示“设置此设备”。

Web Serial 烧录和 Take Control / Adopt 等现有功能也得以保留，并在新安装方式对话框中更加突出地呈现，该对话框新增了服务器端 USB、Home Assistant 主机 USB 自动检测以及 web.esphome.io 下载作为传输方式。

2026.5.0 中落地的 ESPHome 侧支撑基础设施包括：稳定的后端 API 接口（#16206），以及像 write_file（#16290）这样的文档化辅助合约；稳定的 WiFi 能力辅助函数（#16300）和新的 esphome.upload_targets 模块（#16346）；config-hash CLI 命令（#15548）加上 mDNS config_hash TXT 记录（#16145），使设备构建器在运行配置匹配时可以跳过重新烧录；面向可视化编辑器的 schema 可见性提示（#16267、#16276）；收紧的 esphome rename（#16296）；在 --dashboard 模式下恢复的 ProgressBar（#16357）；针对 PR Python 代码的下游 CI（#16214）；以及对贡献者 PR 的旧版仪表盘防护栏（#16378）。

在 2026.5.0 中，旧版仪表盘仍然是默认选项。Home Assistant 用户可以通过安装 ESPHome（测试版） 应用（原附加组件）来尝试设备构建器，其中它默认启用。稳定版和测试版应用可以并行运行，或者稳定版应用用户可以通过附加组件配置选项卡中的 Use new Device Builder Preview 开关选择加入：

在 Home Assistant 的 ESPHome 设备构建器配置选项卡下切换 "Use new Device Builder Preview"

测试版用户的反馈将塑造下一个版本，我们很兴奋已经看到首批社区拉取请求合入 device-builder 和 device-builder-frontend 仓库。

主循环和看门狗架构重构

Section titled “主循环和看门狗架构重构”

本次发布落地了 ESPHome 运行时多年来最具影响力的变化之一：对主循环、调度器和任务看门狗之间交互方式的根本性重构。由 @bdraco 主导，@rwrozelle 贡献了可配置的 ESP32 看门狗超时（#15908）——新的自动缩放喂狗间隔依赖于此——以及产生 2.0 mA → 1.1 mA 节电测量的 OpenThread 概念验证。这些变化在每个受支持的平台上都恢复了可观的 CPU 资源，并最终使 App.set_loop_interval() 按照文档一直描述的方式工作。

主循环节奏与调度器解耦（#15792）：

  • 每个组件的 loop() 现在真正以配置的 loop_interval_ 节奏（默认约 62 Hz）运行，而不会被无关的调度器活动无声地提前到约 128 Hz。
  • 后台驱动的事件（MQTT RX、USB RX、BLE、mWW、espnow、lwIP 套接字等）仍然通过 wake_loop_threadsafe() 在单个时钟周期内唤醒其组件，即使对于深度省电配置的数秒级 loop_interval_ 值也是如此。
  • App.set_loop_interval() 现在真正实现了省电。在 OpenThread 概念验证上的独立测试测得平均电流从 2.0 mA 降至 1.1 mA，这是在此工作早期版本的基础上实现的。

看门狗喂狗速率在 1000 倍成本回归后得到修正（#15846、#15984）：

  • 3 ms 的喂狗节流可追溯到 ESPHome 2019 年的 C++ 移植，当时喂看门狗只需一百纳秒。2021 年切换到 ESP-IDF 使每次喂狗成本升至约 10-12 µs，但该常量未被重新审视。该问题仅在提高 loop_interval_ 时暴露，当时 26% 的 CPU 被消耗在 arch_feed_wdt() 内部。
  • 空闲时钟喂狗间隔现在是每平台独立设置，而非通用的 3 ms：ESP32 默认 1000 ms（配置看门狗超时的 1/5，随 #15908 中新的 esp32.watchdog_timeout 旋钮自动缩放）、ESP8266 为 100 ms、LibreTiny BK72xx 为 2000 ms，其余平台为 300 ms。实际 ESP32+BT 代理测量显示 wdt 桶从 每 60 秒窗口 46.5 ms 降至 21.6 ms，安全裕度无损失。

在合适处全面启用空闲时循环门控（#15636、#15642、#15884 及更多）：esphome OTA 组件、status_led、bl0906 等现在在空闲时禁用自身的 loop()，并依赖唤醒钩子（套接字事件回调、ISR 安全唤醒标志等），仅在确实有实际工作时才恢复运行。OTA 尤其每次时钟周期都运行，只为检查是否有客户端连接；在 Xtensa 上，每个空闲时钟周期都要拉取一次 memw 加上一次易失性加载，这笔开销由每个 ESPHome 设备在其整个生命周期中承担。

调度器自键控定时器 API（#16127）允许小型操作和过滤器类完全放弃 Component 继承。后续跨 #16129、#16131、#16132 和 #16191 的 PR 迁移了 DelayAction 和 binary_sensor / sensor 过滤器族（DelayedOnFilter、DelayedOffFilter、DebounceFilter、HeartbeatFilter、SettleFilter、AutorepeatFilter 等），每实例基线节省约 8 字节（启用 runtime_stats: 时再多节省约 32 字节）。

性能优化

Section titled “性能优化”

除了上述结构性变化，本次发布在代码库中包含了异常集中的实测微观优化，特别是在 API 和音频路径上。由 @bdraco 和 @kahrendt 主导，@swoboda1337 贡献了 CallbackManager 复制减少（#16093）以及 performance-unnecessary-copy-initialization 修复扫尾（#16101）。

跨平台 millis() 重构。 一次协调的重写覆盖了每个受支持的运行时。ESP8266（#15662）从每次调用 3348 ns 降至 1077 ns（2.7 倍），通过在链接时用 32 位累加器包装 Arduino 的 millis()，替换了通过 LX106 的软件 __umulsidi3 辅助路由的四个 64 位乘法。ESP32（#15661）在 FreeRTOS 时钟频率为 1 kHz 时直接切换到 xTaskGetTickCount()；LibreTiny（#15918）内联了相同的 xTaskGetTickCount() 快速路径；主机平台（#15994）用整数算术替换了浮点运算；Millis64Impl::compute() 在单线程平台上被强制内联（#15684）。在典型的 10 组件 ESP8266 设备上，运行时统计显示 main_loop active_total 每分钟 CPU 时间下降 41 ms，约占调度器+开销预算的 7% 被回收用于实际工作。

BLE 广播编码快 20-33%（#15988）。新的 (mac_address) proto 字段选项将 48 位 MAC 地址的 varint 编码器展开为 7 字节快速路径。CodSpeed 测得 CalculateSize_BLERawAdvs12 基准提升 33%，完整的 CalcAndEncode_BLERawAdvs12 基准提升 22.5%。在实际 ESP32 硬件上，12 条广播批次的编码下降 27.6%（11647 ns/op 降至 8430 ns/op）。

API 套接字快速路径收紧（#15996、#15888、#15889）。每个套接字就绪检查中的 Xtensa memw 指令现在被提升到每次主循环迭代一次；api_is_connected() 被内联并缩减为单次字节加载；代理消息族（Z-Wave、IR/RF、串口）现在标记为 speed_optimized 并具有 CodSpeed 覆盖（#16157、#16159）。

调度器快速路径强制内联（#15683、#15685、#15686、#15947）。cleanup_()、process_to_add() 和 process_defer_queue_() 在调用点内联；多线程无原子路径现在使用无锁 __atomic 内置函数。

延迟队列：非空时不睡眠（#15968）。调度器现在在延迟队列仍有待处理项时跳过其 select/睡眠，消除了跨步延迟操作链（script.execute、delay 等）的每时钟周期延迟尖峰。延迟敏感型自动化不再为每个延迟步骤支付额外的 select 往返。

HAL 平凡分发内联（#15977、#16111-#16116、#16183）。HAL 拆分将函数体移入每平台的 hal.cpp 文件，并在调用点内联平凡包装器（millis()、micros()、feed_wdt() 等），消除了跨每个组件主循环工作累积的每次调用函数调用开销。

zwave_proxy 和 bluetooth_proxy 的 loop() 快速路径内联。 在 zwave_proxy 上（#15887），response_handler_ 和 process_uart_ 热点分支现在在 loop() 调用点内联。在 bluetooth_proxy 上，对早期 loop()→set_interval 迁移的部分回滚（#15992）恢复了代理流量的更紧密调度，连接处理程序中多余的 remote_bda_ 写入（#16000）也被移除。蓝牙代理是最广泛部署的 ESPHome 配置之一，因此这些优化在数千台设备上累积生效。

ESP8266 和 RP2040 上的 mDNS 更新轮询改为事件驱动（#15961）。MDNS.update() 现在在 ESP8266 和 RP2040 上由 IP 状态事件驱动，而非每个主循环节拍轮询。空闲设备完全不再触碰 mDNS 状态机。

i2s_audio 软件音量控制便宜 45%（#16278）。新的 Q31 缩放因子使用 Xtensa 的 mulsh 指令（30 位精度）和仅在音量变化时生成的预计算标量。48 kHz 立体声下的扬声器任务 CPU 使用率从 7.8% 降至 4.3%。

value_accuracy_to_buf 获得非 snprintf 快速路径（#15596）。传感器值格式化现在对常见情况（精度 0-3 且有限、在范围内的值）使用直接的整数到十进制转换，snprintf 保留为 NaN、无穷大、更大精度和越界值的回退。这对 web_server 是重大胜利，它在每次 SSE 推送和每个 REST 请求时将每个传感器状态格式化为 JSON；高更新率仪表板和拥有许多传感器的设备在每次推送时看到明显更低的 CPU 消耗，ESP8266 上收益最大，因为那里的 snprintf 开销最大。

灯光、回调和辅助函数热点路径均有改进：LightCall 标志访问器被强制内联（#15729），format_hex_internal 被重写以避免 snprintf（#15594），CallbackManager 调用路径减少复制（#16093）。

内存占用缩减

Section titled “内存占用缩减”

由 @bdraco 和 @kahrendt 主导的并行努力，@schdro 贡献了静态循环任务分配，专注于缩小常见组件的每实例和静态 RAM 成本。

APIServer 客户端列表移至编译时数组（#15889）消除了通过倍增重新分配增长的持久堆驻留向量。实测 ESP32-S3 上 flash 减少 92 B、ESP8266 上 flash 减少 152 B，零堆碎片。在单客户端连接时（典型的 Home Assistant 部署），净 RAM 为 -4 B。新的编译时 MAX_API_CONNECTIONS 常量使数组大小和接受时上限源自同一出处。

FloatOutput 功率缩放门控（#15998）每个输出实例节省 12 字节加约 248 字节 flash，应用于每个 PWM 通道、DAC 通道、LEDC 输出和调光芯片通道。在 5 通道 H801 RGBWW LED 控制器上，实测为 -64 B 静态 RAM 和 -248 B flash。

每实例操作字段折叠为无状态 lambda：每个调用 light.control / light.toggle / light.dim_relative（#16037、#16038、#16039、#16118）、climate.control（#16044）、cover.control / cover.template.publish（#16046）、fan.turn_on（#16122）或 valve.control（#16123）操作的 YAML 自动化，此前将每个可选参数（过渡时长、RGB/亮度目标、模式、位置、方向等）作为 Action 实例上的字段存储，根据操作类型消耗 60-120 字节 RAM/操作实例。这些现在被打包到编译时捕获的单个无状态 lambda 中，因此未使用的参数对每个操作实例不产生任何成本，每个操作降至 每实例 20 字节或更少。一个包含 20 个 light.* 自动化的配置可回收远超 1 KB 的 RAM，拥有大量此类自动化的配置收益最大。

ThrottleAverageFilter 压缩（#16169）每实例从 28 B 降至 24 B，通过将 have_nan_ 标志与 31 位 n_ 字段打包到单个 32 位字中实现。

LD24xx 传感器和模板恢复器内联（#15676、#15883）消除了小型专用对象的堆分配。

循环任务使用静态分配（#15659）：通过将 ESP32 循环任务 TCB 和栈移入 .bss 而非在启动时从堆分配，回收了约 152 字节堆元数据。

环形缓冲区可定位内部内存（#16187）。RingBuffer::create() 上的新内存偏好参数允许音频路径在小型缓冲区受益于更快内部 SRAM 时跳过缓慢的 ESP32 PSRAM 缓存。

调度器池替换为侵入式空闲列表（#16172）。之前的 std::vector 支持的 SchedulerItem 池通过倍增重新分配增长，并在设备整个生命周期内保持其峰值容量。替代品是无界侵入式空闲列表，在 O(1) 时间内回收已释放项，永不调整大小或碎片化外部容器。调度器密集型配置不再将水位线向量容量作为死 RAM 携带。

safe_mode 和 rtttl 回调存储门控（#16002、#16003）。on_safe_mode 回调现在使用 StaticCallbackManager，rtttl 的 on_finished_playback 回调存储在仅在 YAML 实际订阅时才激活的 #define 后面。两者都是微小的每实例收益，但 safe_mode 几乎存在于每台设备上，rtttl 存在于每个使用 RTTDL 播放的扬声器设置上。

light 的 validate_ 钳位缩减（#15728）。每个灯光组件使用的单位范围钳位辅助函数减少了分支数和代码大小，速度提升体现在 PWM、RGB、RGBW、RGBWW、单色和可寻址灯光平台上。

dsmr 解析时不再分配（#15875）。DSMR 重写完全消除了解析路径中的动态分配，并就地解密，每条电报节省约 1500 字节运行时分配。同 PR 的安全修复和 OBIS 传感器方面见其他值得注意的功能。

原生 ESP-IDF 工具链支持

Section titled “原生 ESP-IDF 工具链支持”

@diorcety 在 #14678 中交付了一条重要的新构建路径：ESPHome 现在可以通过 idf.py 直接使用原生 ESP-IDF 工具链构建固件，与现有的 PlatformIO 构建路径并存。这独立于 framework.type（仍选择运行时框架 arduino vs esp-idf）；新的 toolchain 键选择用于编译的构建系统。

通过在 esp32: 块下设置 toolchain 来选择加入：

esp32:
  board: esp32dev
  toolchain: esp-idf  # 或 'platformio'（默认）
  framework:
    type: esp-idf

相同的选项也可在命令行中使用，并为一时性构建覆盖 YAML 值：

Terminal window
esphome --toolchain esp-idf compile my-device.yaml

优先级为 --toolchain（CLI）、esp32.toolchain（YAML）、platformio（默认工具链）。

主要优势：

  • 首次运行时自动安装 ESP-IDF（使用 toolchain: esp-idf），安装到 <data_dir>/idf/（设置 $ESPHOME_ESP_IDF_PREFIX 时为该路径）。ESPHome 下载匹配的 ESP-IDF 版本及其 Python 环境，然后通过 idf.py 直接构建。
  • PlatformIO 库条目的自动转换为 ESP-IDF 组件（包括所需的补丁），因此依赖 PlatformIO 生态系统 lib_deps 的项目在原生工具链下继续工作。
  • 新增 CI 工作流，在每个 PR 上针对原生工具链编译组件，使该路径随着代码库的演进而保持可构建。

2026.5.0 中默认工具链仍为 platformio，因此现有项目保持与以前完全相同的构建方式。原生路径供希望针对未经修改的上游 IDF 进行工作的进阶用户和贡献者选择加入。

ESP-IDF v6.0.1 准备 通过一系列支持 PR 落地，主要由 @swoboda1337 贡献，@diorcety 和 @luar123 贡献依赖升级：新的 ESP-IDF 6.0.1 平台条目（#16146）、esp_wireguard 升级至 0.4.5 以兼容 v6（#15804）、IDF 6 上 Zigbee SDK 的 newlib 兼容性（#16174）以及原生 ESP-IDF 上的初始化顺序和缺失字段警告修复（#16389）、IDF 6 下构建的托管组件放宽 -Werror=reorder 和 -Werror=maybe-uninitialized（#16392），以及原生 ESP-IDF 构建后打印 PlatformIO 风格的 RAM/Flash 摘要以与现有流程保持对等（#16394）。

音频栈现代化

Section titled “音频栈现代化”

@kahrendt 主导了跨十多个 PR 的音频解码管线全面重写，使 ESPHome 与 esphome-libs 组织发布的全新流式编解码器库族保持一致。

新的 microDecoder 库族：

  • microMP3（#16236）、microWAV（#16251）、microFLAC（#16279）取代了较旧的 Helix/esp-audio-libs 解码器。每个编解码器现在要么从源流式传输，要么在内部缓冲，消除了传输缓冲区上的 memmove 操作——对于 MP3，该操作的 CPU 消耗甚至超过了解码本身。
  • 统一的 microDecoder 库（#15679、#16237）在内部处理 HTTP 源读取、解码和线程。audio_file 和新的 audio_http 媒体源（#15741）都构建于其上。
  • esp-audio-libs 升级至 v3.0.0（#16263），保留了重采样器和优化增益辅助函数，但移除了编解码器解码器以减少编译时间。

新的 audio_http 媒体源（#15741）从任意 HTTP URL 播放音频，作为先前变通方案的替代。得益于消除的暂存缓冲区和 memmove，48 kHz 立体声 MP3 现在在 ESP32-S3 上以 约 40% 更少的 CPU 解码。

高级编解码器配置（#16166）在 audio.codecs.* 下暴露每编解码器选项，使用户可以选择内存位置（内部 vs PSRAM）、累加式启用特定编解码器，并调整 Opus 的伪栈大小等选项。较慢的 ESP32（无快速 PSRAM）用户现在可以将解码器缓冲区配置为驻留于内部内存，减少播放开始时的卡顿。

RingBuffer 成为一等组件（#16298），将核心环形缓冲区移入专用的 ring_buffer 辅助组件。外部组件作者现在可以通过 external_components 对其进行迭代；旧的 esphome/core/ring_buffer.h 位置的弃用期为 6 个月。新的 RingBufferAudioSource（#16314、#16315、#16316）统一了扬声器和混音器的音频源管道。

仅通过 YAML 操作引用音频文件的用户（而非嵌入或设为首选格式），可能需要添加 audio.codecs.wav: 以保持 WAV 解码被编译；迁移详情请参见破坏性变更部分。

OTA 平台增强

Section titled “OTA 平台增强”

OTA 获得了任何单次发布中最广泛的能力集，由 @Mat931 主导。

分区表更新（#15780）使通过空中将其他固件（如 Tasmota）的设备转换为 ESPHome 成为可能。更新器验证新分区表，运行完整性检查，仅在能证明设备将启动时才提交。在 ota: platform: esphome 下设置 allow_partition_access: true 即可启用该工作流；文档逐步介绍了 Tasmota 转换过程。

引导程序更新（#16238）构建于新的扩展 OTA 协议（#16164）之上，允许 esphome upload --bootloader 推送新的引导程序镜像。

通过工厂分区恢复软变砖（#16339）。当 OTA 因备用应用分区类型错误但包含有效应用（例如 Tasmota safeboot 镜像）而无法进行时，safe_mode 现在可以引导到工厂分区，使设备可以重新烧录，而无需 USB 线缆。

Web 服务器 OTA 平台（#16207）。esphome upload 和 esphome run 上的新 --ota-platform {esphome,web_server} 标志允许用户强制使用基于 HTTP 的 web_server OTA 路径，当仅配置 platform: web_server 时自动选择。原生 API 路径仍然是默认值，因为它使用带哈希非ces 的挑战-响应认证（OTA 密码永远不会出现在网络上），而 web_server 使用 HTTP 基本认证。

主机平台 OTA 后端（#16304）通过 execv 为主机目标实现了工作的 OTA，解锁了 ESPHome 中最高风险回归面之一的集成测试覆盖。测试现在可以在每次 CI 运行中演练完整的原生 OTA 线协议（握手、MD5、分块传输、自动化触发器、重启），而无需真实硬件。

更好的 OTA 错误消息（#16327）以及在 ESP32 OTA 写入期间使用 WatchdogManager（#16138）完善了该功能包。

更快的配置验证和 CLI 启动

Section titled “更快的配置验证和 CLI 启动”

@bdraco 的四项相关变更使 esphome compile、esphome upload，尤其是 esphome logs 在具有远程依赖的项目上明显更快，并为每次 CLI 调用削减了挂钟时间。

延迟的重模块级导入（#15955）。esphome.__main__、esphome.loader 和 esphome.config 不再在导入时拉取 voluptuous、codegen 和组件注册表；这些重型导入在真正需要它们的代码路径中延迟发生。每次 esphome CLI 调用（包括 esphome version、esphome config 和仪表盘的每个请求 shell）都启动更快，仪表盘的导入时间回归现在由 CI 守护。

在 esphome logs 上跳过外部文件刷新（#16016）。skip_external_update 标志统一为单一的 CORE.skip_external_update 事实来源，external_files.download_content() 现在遵守它。对于 Home Assistant Voice PE 配置（16+ 远程音频文件、多个 micro_wake_word 模型），验证阶段不再在日志开始流式传输之前花费约 20 个顺序 HTTP HEAD 请求。

并行 external_files 下载（#16021）将每文件检查扩展到 8 个工作线程的线程池。当缓存预热时，挂钟时间从 sum(latency) 降至约 max(latency)。

已缓存的已验证配置（#16381）。esphome compile 现在将完全验证的配置写入磁盘；upload 和 logs 重新加载它，而不是从头重新运行 read_config()。缓存由每次 compile 重新生成，因此对新编译的二进制文件后续的 upload 会跳过整个验证管道。无需标志，无需选择加入。

Sendspin 同步多房间音频

Section titled “Sendspin 同步多房间音频”

@kahrendt 为 Sendspin（一种多房间同步音频协议）构建了一套完整的组件族，跨一系列 PR：

  • Hub 组件（#15924）提供基本连接和组状态分发。
  • 控制器角色和开关操作（#15929）允许设备在活跃组之间切换。
  • 组媒体播放器平台（#15948）控制整个组的播放（音量、传输、重复、随机播放），自身不产生音频。
  • 媒体源平台（#15950）播放同步音频，带有固定和运行时可调的延迟补偿，用于下游 DAC/放大器延迟。
  • 元数据文本和数值传感器（#15969、#15971）报告标题/艺术家/专辑，以及专为驱动显示而设计的轮询曲目进度传感器。
  • 通过 sendspin-cpp v0.4.0 减少卡顿（#16178）标记解码器路径为热点，允许播放器缓冲区驻留于内部内存，并将播放器任务优先级提高到 websocket 服务器之上。结合新的音频编解码器配置，这使得在普通 ESP32 上实现实时立体声 Opus 播放成为可能。

射频实体类型

Section titled “射频实体类型”

@kbx81 引入了一种新的顶级 radio_frequency 实体类型（#15556），用于在 Home Assistant 中表示 RF 收发器，同时 ir_rf_proxy 平台（#15744）将现有红外代理扩展为 RF 能力广播（可调频率范围、支持的调制方式）。

一种与驱动无关的 on_control 触发器（#16368）允许任何 RF 前端芯片（CC1101、RFM69、SX127x、自定义外部组件）仅通过 YAML 触发器与 radio_frequency 实体集成，无需自定义 C++ 接线。收发状态切换通过 remote_transmitter 现有的 on_transmit / on_complete 触发器处理，使 radio_frequency 本身保持与驱动无关。该实现与 IR 代理共享线消息以节省 protobuf 消息 ID。

LVGL 改进

Section titled “LVGL 改进”

@clydebarrow 在整个发布周期中持续合入 LVGL 优化：

  • 灵活的网格布局（#16041）接受 3x（3 行，列自动推导）和 x4（4 列，行由组件数量推导）等新简写。grid_rows 或 grid_columns 现在可以是一个整数，展开为相同数量的等 FR(1) 单元格。
  • 已选中状态二进制传感器（#16073）直接报告切换组件状态，而不仅是按下状态。
  • 百分比线点（#16209）使分辨率无关的线组件变得简单。
  • 事件 lambda 中的触摸坐标（#16272）。on_pressed、on_pressing 和 on_release 现在接收额外的 point 参数，包含对象相对坐标。
  • on_update 触发器和 trigger: 选项（#16312）区分数字和传感器的程序化值变化与用户交互。

独立的 mapping 组件也获得了默认值和元数据，用于跨组件验证（#15861）。

Zigbee 扩展至 ESP32 H2 和 C6

Section titled “Zigbee 扩展至 ESP32 H2 和 C6”

@luar123 在 #11553 中将基于 ESP32 的 Zigbee 支持带入 ESPHome，将独立的 zigbee_esphome 外部组件移植到核心。该实现在配备无线电的 ESP32-C6 和 ESP32-H2 变体上运行，将 ESPHome binary_sensor 实体作为 Zigbee binary_input 集群发布，被 ZHA 和 zigbee2mqtt 自动识别。支持 Zigbee 路由器和终端设备。

本次发布的后续 PR 扩展了功能集：

  • Zigbee 传感器（#16026）通过模拟 Zigbee 数据模型暴露 ESPHome sensor 实体。
  • on_join 触发器（#16060）在设备加入或重新加入 Zigbee 网络时触发，带布尔值指示哪种情况。
  • power_source 选项（#16062）允许设备广播其电源类型（电池 vs 市电）。

nRF52 和 Zephyr 平台改进

Section titled “nRF52 和 Zephyr 平台改进”

@tomaszduda23 持续合入将 nRF52/Zephyr 转变为一等 ESPHome 目标的工作，在深度睡眠、Zigbee、OTA 和原生构建方面有大量后续 PR：

  • 带 Zigbee 唤醒的深度睡眠（#13950）允许电池供电的 nRF52 Zigbee 设备在事件之间休眠，同时仍能被无线电唤醒。
  • nRF52 Zigbee 路由器（#16034）将现有 Zigbee 终端设备支持扩展到路由器设备。
  • 循环唤醒原语实现（#16032）：wake_loop_threadsafe() 和 wakeable_delay() 现在具有真实的 nRF52 实现，因此依赖这些原语的组件（套接字、BLE 等）与在 ESP32 上的工作方式相同。
  • DFU 的可选复位引脚（#11684）使 nRESET 引脚在 DFU 进入时变为可选；可靠性较低，但在未引出该引脚的板卡上可行。
  • zephyr_ble_server 数值比较配对（#14400）添加 on_numeric_comparison_request 触发器，用于安全的 BLE 配对流程。
  • 引导程序预留区域（#16204）划分专用 flash 区域，使引导程序更新不与应用 flash 冲突。
  • Zephyr 上的崩溃日志（#16203、#16330）让日志记录器在复位前有机会打印，并单独修复了 Zephyr 上一个长期的日志记录器崩溃问题。
  • OTA 安全的看门狗喂狗（#16218）在 OTA 期间提前喂看门狗，防止设备在更新中途回滚。
  • west update 进度消息（#16321）在 Zephyr 获取模块时提供清晰的进度，而非显示挂起。
  • 原生构建准备（#16193）和外部组件的 run_compile 钩子（#16179）为 nRF52/Zephyr 工具链遵循与上述新的 ESP-IDF 路径相同的原生构建模型铺平道路。
  • CI 覆盖（#16188）添加 nRF52 组件测试，使仅 Zephyr 的变更实际上在 CI 中得到演练，Zephyr 主循环移除冗余的 yield()（#15694）。

@rwrozelle 合入了两个沿同一平台路径的 OpenThread 修复：一个带优先级的协程 COMMUNICATION 配置（#16318）以及移除一个导致较新工具链构建失败的过期 freertos/portmacro.h 包含（#16338）。

新硬件和显示器支持

Section titled “新硬件和显示器支持”
  • ESP32-P4 USB 高速（#14584）由 @p1ngb4ck 贡献：usb_host 上的新 max_packet_size 选项使 ESP32-P4 使用 512 字节 USB 传输，而非被分片为 64 字节全速数据包。
  • 可配置的 ESP32 看门狗超时（#15908）由 @rwrozelle 贡献：esp32.watchdog_timeout 接受 5-60 秒，用于电源管理配置。
  • esp32_ble PSRAM 分配（#15644）由 @edwardtfn 贡献：use_psram: true 选项使 Bluedroid 从 SPIRAM 分配，在配备 PSRAM 的 ESP32 板卡上释放约 40 kB 内部 RAM。
  • SPDIF 扬声器输出（#8065）由 @johnboiles 贡献：基于 I2S 的新 SPDIF 扬声器平台通过任意 GPIO 引脚向光纤接收器发送数字音频。
  • modbus_server 拆分（#15509）由 @exciton 贡献：新的专用 modbus_server 组件，相比旧版嵌入的服务器模式 flash 节省约 60%（1.8 KB vs 4.5 KB），客户端模式 modbus_controller 节省 40%（3.9 KB vs 6.4 KB）。
  • 新显示变体：epaper SSD1683 + Goodisplay GDEY042T81（#13910）、Waveshare 3.97” 电子纸（#15466）、Waveshare ESP32-C6 LCD 1.47（#15776）、Sunton ESP32-2424S012（#15812）、Sunton 5”/7” mipi_rgb 显示器（#15858）、Seeed reTerminal D1001 DSI 显示器（#15867）。
  • ESP8266 的 WiFi phy_mode（#16055）允许用户从 YAML 将无线电固定到 11B、11G 或 11N，以绕过与 ESP8266 802.11n 关联行为异常的无线路由器。

蓝牙代理的 BLE 可靠性修复

Section titled “蓝牙代理的 BLE 可靠性修复”

@plazarre 在 #16036 中追踪了一个长期的 status=0x85（133）错误类别，该问题在持续 WiFi 流量下影响 bluetooth_proxy 用户，尤以 Yale/August 锁用户最为明显。该修复跟踪 CONNECTED 和 ESTABLISHED 客户端（不仅是短暂连接状态），并在任何活动连接的生命周期内保持 ESP_COEX_PREFER_BT。同一把锁、同一固件，补丁前后对比：

  • 重 WiFi 流量： 19 秒后 status=133 超时 变为 228 ms 内 status=0 成功。
  • 针对禁用主机 BlueZ 的 Yale BETA211123 锁的生产验证：通过补丁后的代理成功解锁。

其他值得注意的功能

Section titled “其他值得注意的功能”
  • 语音助手第二音频通道（#16265）由 @synesthesiam 贡献：MULTI_CHANNEL_AUDIO 功能标志和第二个麦克风源使语音管线各阶段接收分别优化的音频。
  • config-hash CLI 命令（#15548）由 @ccutrer 贡献：通过比较配置哈希与设备上当前的配置来确定是否需要重新烧录。
  • round_to_significant_digits 过滤器（#11157）由 @gapple 贡献：适用于跨越六个数量级的环境光类传感器。
  • AC 调光器过零中断类型（#15862）由 @aselafernando 贡献：用户可配置的过零检测中断边沿。
  • lock 开启状态（#15120）由 @egormanga 贡献：lock 实体获得了 OPENING 和 OPEN 状态。
  • SX126x 冷睡眠（#16144）由 @swoboda1337 贡献：睡眠操作上的新 cold: 选项可达到约 0.6 µA（比温睡眠低约 1000 倍），适用于与 ESP32 深度睡眠配对使用的场景。
  • DSMR 重写（#15875）由 @PolarGoose 贡献，移除了 Crypto-no-arduino 依赖，消除了解析期间的动态分配，就地解密（节省约 1500 字节），修复了潜在的事件循环挂起，修复了缺失的 GCM 标签验证（一个安全漏洞），并添加了几个缺失的 OBIS 传感器。
  • 气候/热水器温度单位 API（#15815）由 @jhenkens 贡献：protobuf 级别的原生华氏度操作支持；C++ 实现已排期为后续版本。
  • Mitsubishi CN105 远程温度 API（#15558）由 @crnjan 贡献：用外部传感器的值覆盖空调单元的内部传感器。
  • nRF52 可选复位引脚（#11684）由 @tomaszduda23 贡献：无需 nRESET 引脚即可进入 DFU（可靠性较低但可行）。

代码库正确性和开发者工具

Section titled “代码库正确性和开发者工具”

伴随功能交付的是一轮大规模的正确性扫尾工作，由 @swoboda1337（本版本 59 个 PR）主导，@bdraco 在 HAL 拆分和 CodSpeed 覆盖方面、@jpeletier 在替换错误消息方面、@Komzpa 在可重现构建方面提供了帮助。

  • clang-tidy 22.1（#16078）替换了多年前的 18.1.8，暴露了跨组件的潜在问题。

  • 嵌套命名空间拼接（#16294-#16307）遍历整个组件树（a→c、d→h、i→m、n→r、s、t→z 及测试），将 namespace foo { namespace bar { ... } } 折叠为现代的 namespace foo::bar { ... }，并启用检查以防止回归。

  • bugprone-unchecked-optional-access 修复（#16102、#16103、#16107、#16121、#16124）消除了 sprinkler、pn532、feedback、time（CronTrigger）、tormatic 和 haier 中一类未检查的 std::optional 访问 bug。

  • CodSpeed 覆盖扩展（#15593、#15688、#15696、#15995、#16157、#16402）为热点辅助函数、SubscribeLogsResponse 编码、Z-Wave/IR/RF/串口代理消息和编译配置缓存快速路径添加了基准测试。基准测试目标现在与固件优化级别（-Os）匹配。

  • 每平台 HAL 拆分（#15977、#15978、#16111-#16116、#16183）将 HAL 函数体移入 components/<platform>/hal.cpp 下的每平台文件，并内联平凡分发。

  • 替换错误消息改进（#15874）由 @jpeletier 贡献：未定义变量错误现在显示完整的包含堆栈跟踪（Included from packages[3] in my_project.yaml 11:2），而非平坦的 packages->3->packages->net->wifi->ssid 路径。

  • 可重现的 ESP-IDF 构建（#16008、#16053）使 ESPHome 构建逐位可重现。

致谢贡献者

Section titled “致谢贡献者”

本次发布包含来自 50 多位贡献者的 395 个拉取请求。衷心感谢所有让 2026.5.0 成为可能的人：

  • @swoboda1337 - 59 个 PR，包括跨整个组件树的七部分嵌套命名空间 clang-tidy 扫尾、带相应正确性修复的 clang-tidy 22 升级、SX126x 冷睡眠选项，以及大量原生 ESP-IDF 构建打磨
  • @kahrendt - 37 个 PR，包括基于新的 microMP3、microWAV、microFLAC 和 microDecoder 库的音频栈重写、ring_buffer 辅助组件、新的 audio_http 媒体源，以及全新的 Sendspin 多房间同步音频组件族
  • @clydebarrow - 17 个 PR，包括 LVGL 布局、渐变、百分比线点、触摸点和 on_update 触发器改进、新的 mipi_spi 和 mipi_dsi 显示型号，以及 ESPNOW 方法可见性清理
  • @jesserockz - 16 个 PR，包括最小权限工作流令牌、CI 工具收紧，以及各种构建/发布基础设施改进
  • @tomaszduda23 - 13 个 PR，包括 nRF52 + Zephyr 原生构建准备、带 Zigbee 唤醒的深度睡眠、nRF52 Zigbee 路由器，以及 Zephyr OTA/看门狗/日志修复
  • @Mat931 - 10 个 PR，包括 OTA 分区表和引导程序更新、扩展 OTA 协议、通过工厂分区实现 safe_mode 软变砖恢复，以及 WatchdogManager 修复
  • @kbx81 - 7 个 PR，包括新的实验性 radio_frequency 实体类型、ir_rf_proxy RF 扩展和与驱动无关的 on_control 触发器，以及 i2s_audio 重构
  • @luar123 - 5 个 PR，扩展基于 ESP32 的 Zigbee 支持，包括二进制传感器、传感器、on_join 触发器和 power_source 选项
  • @crnjan - 5 个 PR，包括 mitsubishi_cn105 远程温度 API、半度设定点、统一超时处理，以及导风叶片/广角导风叶片支持
  • @diorcety - 4 个 PR，包括原生 ESP-IDF 工具链支持和 ESP-IDF v6 准备工作
  • @rwrozelle - 3 个 PR，包括可配置的 ESP32 watchdog_timeout 和 OpenThread 改进
  • @Komzpa - 3 个 PR，使 ESP-IDF 和 Arduino 构建逐位可重现
  • @egormanga - 2 个 PR，为 lock 组件及其 API 协议添加 OPENING 和 OPEN 状态
  • @guillempages - 2 个 PR，包括 tm1637 亮度设置器和 Sunton mipi_rgb 显示定义
  • @edwardtfn - 2 个 PR，包括 esp32_ble 的 use_psram 选项和 nextion TFT 上传修复
  • @jpeletier - 2 个 PR，包括包含堆栈跟踪的替换错误消息和远程包 vars 替换修复
  • @PolarGoose - 2 个 PR，重写 dsmr 以提升性能，移除 Crypto-no-arduino 依赖，并添加缺失传感器和 GCM 标签验证修复
  • @johnboiles - 新的 SPDIF 扬声器输出平台
  • @exciton - 从 modbus_controller 拆分出的新 modbus_server 组件
  • @plazarre - esp32_ble_tracker 共存修复，解决了 bluetooth_proxy 设置上长期的 status=133 GATT 失败问题
  • @synesthesiam - voice_assistant 的第二音频通道

同时感谢 @bdraco、@gapple、@lboue、@balloob、@Eelviny、@CircuitSetup、@ximex、@p1ngb4ck、@mikeytdisco、@angelnu、@puddly、@rwalker777、@TimoPtr、@Farmer-shin、@ccutrer、@SaVi456、@DidierA、@schdro、@rishabmehta7、@yvesf、@Bl00d-B0b、@jhenkens、@ruimarinho、@aselafernando、@dbl-0、@GelidusResearch、@oarcher、@RubenKelevra、@dmik、@ssieb 和 @ggalt 的贡献，以及所有报告问题、测试预发布版本并在社区中提供帮助的人。

破坏性变更

Section titled “破坏性变更”

组件变更

Section titled “组件变更”
  • Modbus：服务器模式已从 modbus_controller 中拆分为新的 modbus_server 组件。在顶层 modbus_server: 块下将 server_registers 移至 registers，将 server_courtesy_response 移至 courtesy_response #15509
  • API：esp32、bk72xx、rtl87xx 和 ln882x 上默认 max_connections 从 8 降至 5。如果需要超过 5 个并发 API 连接，请显式设置 api.max_connections #15889
  • OTA（esphome 平台）：使用不同 port: 值的多个 ota: - platform: esphome 条目现在在配置时被拒绝。请使用一个端口上的单个条目 #15636
  • 输出：FloatOutput 运行时功率缩放（min_power、max_power、zero_means_zero、output.set_min_power / output.set_max_power 操作）现在由构建标志门控。仅当您在 lambda 中调用 id(...).set_min_power(...) / set_max_power(...) / set_zero_means_zero(...) 且从未使用 YAML 键或操作时才会受影响。在单个 output: 条目中添加 min_power: 0%（或任何其他键）以重新启用运行时设置器；当适用时，构建将发出带有修复方案的清晰 static_assert 错误 #15998
  • 传感器：throttle_average 过滤器现在拒绝超过 24 小时的 time_period 值 #16169

音频栈

Section titled “音频栈”
  • 音频 / 媒体播放器 / 扬声器：WAV 解码不再总是编译。当您嵌入 WAV 文件、将 format: WAV 设为首选管线格式，或使用带 format: NONE 的 speaker 媒体播放器时，WAV 仍会自动启用。如果您仅通过 YAML 操作从任意 URL 播放 WAV，请在配置中添加 audio: codecs: wav: #16244
  • 媒体播放器 / 扬声器 / 扬声器源：speaker 媒体播放器上的 codec_support_enabled 现在无效且已弃用。编解码器包含由管线 format: 设置决定（使用 format: NONE 包含所有编解码器，等效于旧版的 all 模式；format: WAV 最接近旧版的 none/false 模式）#14771
  • 扬声器媒体播放器：通过 files: 块内置到固件中的文件现在每个文件有 5 MB 的大小限制。在升级前压缩超大文件（或切换到更高效的编解码器）#16266

行为变更

Section titled “行为变更”
  • 核心（主循环）：每个组件的 loop() 现在真正以配置的 loop_interval_ 节奏（默认约 62 Hz）运行，而非被无关调度器活动提前到约 128 Hz。后台事件（MQTT RX、USB RX、BLE 等）仍在单个时钟周期内唤醒其组件。如果您的 YAML 隐式依赖于 loop() 被其他调度工作提前，组件现在运行频率更低；请使用 HighFrequencyLoopRequester 实现快速唤醒 #15792
  • ESP32 BLE 跟踪器：ESP_COEX_PREFER_BT 现在在任何活动 BLE 连接的生命周期内保持，而非在握手稳定后立即恢复为平衡共存。这修复了在重 WiFi 负载下（尤其是 Yale/August 锁）bluetooth_proxy 设置上的 status=0x85 / 133 GATT 失败。持有长生命周期 BLE 连接（例如 ble_client 持久传感器）的配置可能会在连接期间看到较低的 WiFi 吞吐量 #16036
  • One Wire：OneWireBus::skip() 现在在执行 SKIP ROM 命令前执行总线复位，修复了一个长期的 1-Wire 协议违规，可能导致不可靠的读数（如 DS18B20 上电时的 25 °C / 85 °C 值）。调用 skip() 的外部组件或 lambda 必须处理新的 bool 返回值（复位/存在脉冲失败时为 false）#14669

未记录的 API 变更

Section titled “未记录的 API 变更”

面向开发者的破坏性变更

Section titled “面向开发者的破坏性变更”
  • OneWireBus::skip() 签名：现在返回 bool（存在脉冲成功时为 true，复位/无设备时为 false）；还在 SKIP ROM 命令前执行总线复位。调用者必须处理返回值 #14669
  • ComponentIterator::on_media_player 现在为纯虚函数：不处理媒体播放器的子类必须添加由 #ifdef USE_MEDIA_PLAYER 保护的 override { return true; } 存根 #15618
  • 分配堆内存的辅助函数移至 alloc_helpers.h/alloc_helpers.cpp：str_lower_case、str_snprintf、format_hex、format_hex_pretty、format_mac_address_pretty、value_accuracy_to_string、base64_encode、base64_decode（vector 重载）、get_mac_address、get_mac_address_pretty 等函数已移动。helpers.h 为向后兼容重导出 alloc_helpers.h，直至 2026.11.0；请在此之前更新您的包含 #15623
  • PollingComponent() 默认构造函数：现在初始化为 SCHEDULER_DONT_RUN（UINT32_MAX），而非 1。绕过 codegen、以无参数方式调用 PollingComponent() 且从不调用 set_update_interval() 的外部组件将停止轮询。向构造函数传入间隔或显式调用 set_update_interval() #15832
  • API clients_ 存储：APIServer::clients_ 从 std::vector 改为编译时 std::array；set_max_connections() 运行时设置器已移除，上限现在是编译时 MAX_API_CONNECTIONS 定义，从 YAML 填充 #15889
  • FloatOutput 功率缩放成员门控：min_power_、max_power_、zero_means_zero_ 及相应设置器现在由 USE_OUTPUT_FLOAT_POWER_SCALING 门控。调用这些设置器的 lambda 需要 YAML 选择加入（参见用户破坏性变更部分）；编译时 static_assert 在调用点记录修复方案 #15998
  • ESPNOW 方法可见性和命名：play() 现在正确设为受保护（原为 public）；一些方法/属性为与 YAML 触发器保持一致而重命名（例如 broadcasted → broadcast）。扩展 ESPNOW 类的外部组件需要更新方法名和可见性预期 #16109
  • Climate ClimateTraits 访问器移除：10 个已弃用的 get/set_supports_* 访问器（current_temperature、current_humidity、two_point_target_temperature、target_humidity、action）在 6 个月窗口后已移除。使用 add_feature_flags() / has_feature_flags() 及匹配的 CLIMATE_* 标志；注意 two_point_target_temperature 映射为 CLIMATE_REQUIRES_TWO_POINT_TARGET_TEMPERATURE #16289
  • EKTF2232 rts_pin 迁移辅助移除：schema 级的 rts_pin → reset_pin 重命名辅助已移除；仍使用 rts_pin 的配置将收到通用 schema 拒绝，而非友好的重命名错误 #16289
  • 核心环形缓冲区移至 ring_buffer 辅助组件：从 esphome/components/ring_buffer/ring_buffer.h 包含并使用 esphome::ring_buffer::RingBuffer 命名空间，而非 esphome::RingBuffer。旧的 esphome/core/ring_buffer.h 位置已弃用，移除窗口为 6 个月；在组件的 codegen 中添加 AUTO_LOAD = ["ring_buffer"] #16298

详细迁移指南和 API 文档，请参阅 ESPHome 开发者文档。

Release 2026.5.1 - May 25

Section titled “Release 2026.5.1 - May 25”

Release 2026.5.2 - June 2

Section titled “Release 2026.5.2 - June 2”

Release 2026.5.3 - June 5

Section titled “Release 2026.5.3 - June 5”

全部变更列表

Section titled “全部变更列表”

新增功能

Section titled “新增功能”

（完整变更列表请参见原文）

新组件

Section titled “新组件”

（完整变更列表请参见原文）

新平台

Section titled “新平台”

（完整变更列表请参见原文）

破坏性变更

Section titled “破坏性变更”

（完整变更列表请参见原文）

所有变更

Section titled “所有变更”

（完整变更列表请参见原文）

（完整变更列表请参见原文）