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

ESPHome 2026.6.0 - 2026年6月

Motion ​(​IMU)​
BMI2​7​0​
Accelerometer ​&​ ​Gyroscope
LSM6​DS
Accelerometer ​&​ ​Gyroscope
Router ​Speaker
PCM5​1​2​2​
XDB4​0​1​
Pressure

发布概览

Section titled “发布概览”

ESPHome 2026.6.0 退役了旧版内置仪表盘，取而代之的是全新的 ESPHome 设备构建器（ESPHome Device Builder），本次版本达到了 1.0.0。此次发布还将 ESP8266 的默认 WiFi 安全模式提升至 WPA2，并终于使 WiFi 和以太网在 enable_on_boot: false 时能够真正回收它们本应释放的 15–30 KB 和 3–8 KB 内部 SRAM，同时 LVGL 配置验证速度最高可提升 4.5 倍。大规模音频栈现代化改造带来了零拷贝环形缓冲区、任意位深混音，以及新的 router 扬声器，而一系列 PR 则为代码库做好了 ESP-IDF 6 和原生 RISC-V clang-tidy 的准备。此外，新增 motion IMU 框架（含 BMI270 和 LSM6DS 驱动）、两个 USB 串口驱动、PCM5122 音频 DAC、YAML frontmatter，以及一个终于能在原生 IDF 上工作的顶层 build_flags 选项。

升级检查清单

Section titled “升级检查清单”
  • 如果您在仅支持 WPA（TKIP）的旧路由器上使用 ESP8266，请在 wifi: 下固定设置 min_auth_mode: WPA，否则设备将停止关联
  • 如果您使用 dsmr 的 electricity_switch_position 传感器，请将其从 sensor: 移至 text_sensor:
  • 如果您在 nextion 显示屏中使用 dump_device_info: true，请移除此选项（设备信息现在始终会记录日志）
  • 如果您仍从 custom_components/ 文件夹加载组件，请迁移到 external_components:
  • 如果您的 time: 组件使用 platform: homeassistant 并显式配置了 timezone:，请注意 Home Assistant 将不再覆盖您配置的时区
  • 如果您使用带有 provider: 选项的 dlms_meter 组件，请预期会出现弃用警告；该选项现已被忽略，将在 2026.11.0 中移除
  • 如果您维护调用 mark_failed("...") 或 status_set_error("...") 的外部组件，请切换到 mark_failed(LOG_STR("...")) / status_set_error(LOG_STR("..."))
  • 如果您维护使用 cv.only_with_esp_idf 或 CORE.using_esp_idf 的外部组件，请将其替换为 cv.only_on_esp32 / CORE.is_esp32
  • 如果您的 lambda 调用了 text_sensor->raw_state，请切换到 text_sensor->get_raw_state()
  • 如果您的 lambda 引用了 mipi_dsi::MIPI_DSI C++ 类型，请将其重命名为 mipi_dsi::MipiDsi

ESPHome 设备构建器替代旧版仪表盘

Section titled “ESPHome 设备构建器替代旧版仪表盘”

全新的 ESPHome 设备构建器于 2026.5.0 中以可选预览版发布，本次版本达到了 1.0.0，并替代了即将退役的旧版内置仪表盘。设备构建器位于两个仓库中： device-builder（Python 后端）和 device-builder-frontend（Web UI），从 2026.6.0 起它已成为官方 Home Assistant ESPHome 插件默认捆绑的仪表盘。

ESPHome 设备构建器设备列表

相较于旧版仪表盘，它带来了：

  • 可视化的组件与自动化构建器，配合 CodeMirror YAML 编辑器以及左侧边栏设备导航器。旧版仪表盘只是一个 .yaml 文件的纯文本编辑器。
  • 带依赖解析的组件目录以及逐引脚信息查看器，可映射 GPIO 能力并显示哪个组件正在使用每个引脚。
  • 固件任务队列，支持编译 / 安装 / 清理的进度、历史记录和取消操作，替代了旧版一次只能执行一个操作的模式。
  • **远程构建器：**一个设备构建器实例可以通过配对链接将 OTA 构建任务卸载到另一台设备上（mDNS 发现、带外指纹确认、身份轮换、逐对自动路由）。
  • 标签、区域、可编辑的友好名称、设备克隆以及多选批量操作（在任意一组设备上执行更新、删除、归档和打标签）。
  • **不同步检测：**每个设备上的加密状态不匹配标记，以及设备抽屉中的版本和配置哈希同步诊断。
  • YAML 差异视图、跨配置 YAML 搜索（含上下文），以及命令面板（⌘K / Ctrl-K）。
  • 卡片和表格视图，支持可配置列和分面筛选器（平台 / 状态 / 区域 / 标签）。
  • 真实设置界面，支持浅色 / 深色 / 系统主题，并正在进行多语言本地化。
  • 首次运行时 WiFi 引导以及扩展的安装方式对话框：Web 串口刷机、服务端 USB（作为插件运行时重命名为 Home Assistant 主机）、web.esphome.io 下载，以及手动 .bin 下载。

2026.5.0 中的 使用新设备构建器预览 选项已移除；设备构建器就是现在的仪表盘。

ESP8266 默认 WiFi 安全提升至 WPA2

Section titled “ESP8266 默认 WiFi 安全提升至 WPA2”

ESP8266 现在的默认 min_auth_mode 为 WPA2，与多年来一直采用的 ESP32 默认设置一致。ESPHome 自 2026.1 起就在每个未显式设置 min_auth_mode 的 ESP8266 配置中打印弃用警告，明确指出了此次变更。考虑到约 40% 的 ESPHome 安装运行在 ESP8266 硬件上，这是本次发布中影响范围最广的平台级变更（由 @swoboda1337 提交的 #16682）。

连接到现代 WPA2/WPA3 接入点的配置无需更改。在仅支持 WPA（TKIP）的旧路由器上的设备必须显式固定旧行为：

wifi:
  min_auth_mode: WPA

WiFi 和以太网在启动时禁用时真正释放内存

Section titled “WiFi 和以太网在启动时禁用时真正释放内存”

wifi: 和 ethernet: 上的 enable_on_boot: false 以前仅跳过 start() 调用，导致整个驱动仍然驻留在支持 DMA 的内部 SRAM 中。由 @kbx81 提交的两个 PR 将重型分配工作拆分为仅在接口实际启用时运行的延迟初始化路径，因此休眠接口现在不再占用任何内部 RAM。

ESP32 上回收的内存：

  • WiFi：enable_on_boot: false 时释放约 15–30 KB 支持 DMA 的内部 SRAM （#16606）。在 ESP32-S3 上配合 W5500 SPI 以太网 + I2S 音频 + bluetooth_proxy 进行了实地测试：峰值负载下空闲内部 SRAM 从约 14 KB 提升至约 32 KB，最小空闲测量值在某些配置下达到 78 KB。
  • 以太网：enable_on_boot: false 时释放约 3–8 KB，与 WiFi 生命周期保持一致 （#16607）。引入了 ethernet.enable / ethernet.disable 动作和 ethernet.connected / ethernet.enabled 条件，与 WiFi 自动化接口对称。

这为在单一配置中同时运行 WiFi 和以太网奠定了基础：每个接口现在都可以按需启动，而无需为未使用的接口付出代价。

W5500 SPI 驱动还在 #16596 中获得了 CPU 性能提升，由 @kahrendt 提交：大帧传输现在通过中断驱动的 DMA 路径进行，而不是让 CPU 忙等。测量显示在 W5500 上流式传输 48 kHz 24 位 FLAC 时，以太网任务 CPU 使用率从约 5% 降至约 3.8%，降低了约四分之一。

LVGL 配置验证速度最高可提升 4.5 倍

Section titled “LVGL 配置验证速度最高可提升 4.5 倍”

新设备构建器 UI 在每次保存时都会重新验证配置，这使得 esphome config 的延迟成为直接的 UX 成本。LVGL 配置是最严重的问题。由 @bdraco 提交的一系列五个 PR 针对 LVGL 模式构建中的热点路径进行了优化：

  • 记忆化并延迟构建 container_schema（#16567）——在代表性 LVGL 配置上，重复验证的中位时间从 210 ms 降至 17 ms。
  • 延迟构建 widget 更新动作模式（#16569）——在 lvgl 导入时节省约 200 ms。
  • 合并字典扩展链（#16614）——在 read_config 上 2.81× 加速（在 lvtest host.yaml 上从 0.246 s 降至 0.087 s）。
  • 按 widget 类型记忆化 obj_schema（#16615）——在此基础上 2.14× 加速。
  • 延迟构建 automation_schema 事件验证器（#16633）——每次调用的成本 降低 4.5 倍（在 29 种 widget 类型的微基准测试中从 281 ms 降至 63 ms）。

用户可见的效果是：在设备构建器中的每次保存都明显更加流畅，尤其是带有大型 LVGL 屏幕的配置。

音频栈现代化

Section titled “音频栈现代化”

@kahrendt 在本轮中主导了全面的音频改造，用零拷贝的 RingBufferAudioSource 替换了临界音频路径中的分配与拷贝式 AudioSourceTransferBuffer 模式。

零拷贝环形缓冲区推广消除了每块音频处理中的一次分配和一次额外拷贝：

  • resampler（#16560）
  • 扬声器媒体播放器的 AudioDecoder（#16564）
  • micro_wake_word（#16595）
  • voice_assistant（#16597）——同时取消了两个 1024 字节的发送缓冲区，改为直接从环形缓冲区读取

混音器支持任意位深（#16524）。混音器扬声器现在接受每样本 8、16、24 或 32 位，消除了音频栈中最后一个剩余的仅支持 16 位的限制。由 esp-audio-libs v3.1.0 / v3.2.0 支持，上游库使用模板特化使新代码路径与旧版仅支持 16 位的版本一样快。

重采样器位深直通（#16892）。既然混音器可以处理任意位深，重采样器默认直接传递输入音频的位深而不再自动转换以匹配输出扬声器。这避免了在下游混音器会进行更快转换时，在重采样器中浪费 CPU 周期。

新的 router 扬声器组件（#16592）可通过 router.speaker.switch_output 动作在运行时切换输出扬声器。典型用例是通过 select 实体在 SPDIF 和模拟 I2S 输出之间实时切换，切换后音频保持同步。详情请见 router。

micro_wake_word 任务栈可放入 PSRAM（#16632），在 ESP32-S3 上节省约 3 KB 内部 SRAM，且无可测量的性能影响。设置 task_stack_in_psram: true。

PSRAM 任务栈处理已统一（#16628），使 audio_file、audio_http、mixer、resampler、sendspin 和 speaker.media_player 共享相同的验证模式，并修复了扬声器媒体播放器上 task_stack_in_psram: false 的 Bug。

ESP-IDF 6 与原生 RISC-V clang-tidy

Section titled “ESP-IDF 6 与原生 RISC-V clang-tidy”

由 @swoboda1337 发起的一系列 PR 使静态分析在捕获真实固件 Bug 方面有了显著提升：

  • script/clang-tidy 现原生支持 RISC-V 目标（#16809）
    • clang 上游的 RISC-V 后端现在可以直接分析 ESP32-C3/C6/H2/P4 构建，而无需回退到以前用于 Xtensa 路径的 32 位 x86 替代方案。
  • 原生 ESP-IDF clang-tidy 现成为全面检查（#16823）。Arduino 工具有链存在一个盲点：其头文件将 std:: 浮点数学重载引入全局命名空间，隐藏了 performance-type-promotion-in-math-fn 的发现。IDF 工具链可以捕获它们。
  • 整个代码库中修复了浮点到双精度提升问题 （#16812）——display、daikin_arc、nau7802、sgp4x、thermopro_ble、tuya 全部从 C <math.h> 切换到浮点类型的 std:: 重载，在 32 位 MCU 上保持使用 float 进行数学运算，而不是无谓地提升为 double。
  • ESP-IDF 6 上通过 clang-tidy（#16850）——sdkconfig 固定为 newlib，清除仅适用于 GCC 的标志，在静态分析下添加了 ledc HAL 守卫。这是即将推出的 ESP-IDF 6 支持的基础。
  • arduino-esp32 存根用于托管 IDF 组件（#16695）
    • 在 PlatformIO 上，像 FastLED 这样声明了 REQUIRES arduino-esp32 的组件现在解析为一个通过 CMake INTERFACE 重新导出的框架存根，而不是 IDF 组件管理器试图下载重复项。
  • 100% 补丁覆盖率门禁（#16827，由 @jesserockz 提交）——新 PR 必须覆盖每一行变更代码。项目级覆盖率保持仅做信息参考，以免贡献者因先前存在的未测试代码而受到惩罚。

新组件与硬件支持

Section titled “新组件与硬件支持”

@clydebarrow 完成了协调一致的 IMU 栈：一个通用的 motion 中心组件，提供加速度、角速度和衍生俯仰/滚转角值，以及用于自动俯仰/滚转角校准的动作（#16226）。两个具体驱动建立在其上：

  • Bosch BMI270（#16202）——用于 M5Stack Tab5 和 Espressif 的 EchoEar
  • STMicro LSM6DS3TR-C（#16232）——用于 Seeed ReTerminal D1001

新传感器与 DAC：

  • PCM5122 音频 DAC，由 @remcom 提交 （#15709）——在 Raspberry Pi HAT 上流行的 Texas Instruments 立体声 I2S DAC，通过标准引脚模式暴露静音、数字音量和四个可配置 GPIO 引脚。
  • XDB401 压力传感器，由 @RT530 提交 （#15108）——来自 XIDIBEI XDB401 的 I2C 压力和温度测量。

USB 串口驱动，由 @p1ngb4ck 提交：

  • FTDI FT23XX 系列（#14587）——覆盖 FT232R、FT2232C、FT2232H、FT4232H、FT232H、FT230X 及 AM/BM 变体；芯片类型从 USB 描述符中自动检测；多通道芯片支持为独立通道。
  • Prolific PL2303 系列（#16885）——覆盖从旧版 PL2303H/HX 到现代 G 系列；波特率编码按芯片类型选择。

新显示屏： WAVESHARE-ESP32-S3-TOUCH-AMOLED-2.16 已添加到 mipi_spi 驱动中 （由 @clydebarrow 提交的 #16887）。

DLMS 智能电表组件全面改造

Section titled “DLMS 智能电表组件全面改造”

@Tomer27cz 重构了 dlms_meter 组件以使用外部 dlms_parser 库 （#15458），大幅扩展了智能电表支持：

  • 动态 OBIS 代码模式——通过 OBIS 代码（例如 "1-0:99.99.9"）自定义传感器、文本传感器或二进制传感器，而不受硬编码属性列表的限制。
  • 新增二进制传感器支持。
  • 解密密钥现在为可选——直接支持广播明文的电表。
  • 灵活的 UART 波特率——不再要求 2400 波特；将 UART 配置为电表所使用的任何速率。
  • 新配置变量——auth_key、custom_patterns、skip_crc 和 receive_timeout，用于具有非标准行为的电表。

旧版模式继续可用，provider 键现在被忽略并伴有弃用警告，计划在 2026.11.0 中移除。现有配置应仍能验证通过而无需更改。

配套的 DSMR 组件也经历了一次修复和功能升级 （由 @PolarGoose 提交的 #16561）， 包括支持 EON Hungary 电表、自定义认证密钥以及设备 ID 字段中的自动十六进制字符串检测。请注意 electricity_switch_position 已从 sensor 移至 text_sensor，可能需要更新 YAML。

网络、Zephyr 与平台底层改造

Section titled “网络、Zephyr 与平台底层改造”

nRF52 上的 Zephyr IPv6 网络（由 @Ardumine 提交的 #16336）是通过 Zephyr 在 nRF52840 上支持 OpenThread 的第一步。新增了一个由 struct in6_addr 支持的 Zephyr 专用 IPAddress 类、网络 Kconfig 以及三个新的 nRF52 网络测试夹具。nRF52 上 IPv6 默认启用。

RP2350 / RP2040 变体配置（由 @jesserockz 提交的 #16602）将 ESP32 风格的 variant 选项引入 rp2040 平台块，使同一平台可以针对 RP2040 或 RP2350，并生成匹配的 USE_RP2040_VARIANT_<VARIANT> 构建标志。变体从板载 MCU 自动推导；如果同时指定则必须匹配。

esp32_hosted PSRAM 传输缓冲区 （由 @swoboda1337 提交的 #16627）—— 新增 use_psram: true 选项将 esp_hosted 传输内存池从支持 DMA 的内部 RAM 移至 PSRAM，修复了内存紧张的 ESP32-P4 + LVGL UI 配置中启动时的 sdio_mempool_create 断言问题。

配置与工具改进

Section titled “配置与工具改进”

YAML frontmatter（由 @jesserockz 提交的 #16552）——前导的 --- 分隔 YAML 文档现在被视为不透明元数据，在验证前剥离，并在 CORE.frontmatter 上按文件捕获。未来的工具（包括设备构建器）可以消费作者、版本、标签等任意用户元数据：

author: Jesse Hills
version: 1.0.0
labels: [office, climate]
---
esphome:
  name: my-node

IDF + PlatformIO 的 esphome.build_flags （由 @swoboda1337 提交的 #16629）—— 顶层 esphome.build_flags 列表现在在两个后端上应用编译器标志。现有的 platformio_options.build_flags 仅适用于 PlatformIO；使用原生 IDF（ESP32-P4、ESP32-H2）的用户需要此功能。

esphome config --no-defaults（由 @jesserockz 提交的 #16718）在替换和包解析后仅输出用户提供的配置，不包含数百个注入的模式默认值。适用于配置比对、在 Issue 中分享最小复现，以及检查实际输入的内容。

Codeberg 简写 Git URL（由 @Eelviny 提交的 #16501）——codeberg://owner/repo/path/file.yaml 现在作为 dashboard_import 和简写 packages 的受支持源，与 github:// 和 gitlab:// 并存。

github:// 框架源（由 @swoboda1337 提交的 #16639）——esp32.framework.source 现在接受 github://owner/repo@ref 和 https://github.com/owner/repo.git@ref，执行 git clone --depth=1 --recurse-submodules 而不是下载归档。这是因为 GitHub 归档 URL 会剥离子模块，而 ESP-IDF 严重依赖子模块（mbedtls、openthread、tinyusb 等）。主要用途是在任何标记版本发布新芯片之前，测试预发布的 ESP-IDF。

敏感值脱敏（由 @bdraco 提交的 #16690）现在由模式中的 cv.sensitive() 标记驱动，而不是事后转储的正则表达式。WiFi SSID 现在被标记为敏感，与密码一起受保护。使用新标记的外部组件可自动获得脱敏；正则回退在 2026.12.0 之前作为弃用桥梁保留。

状态报告 CLI 控制（由 @clydebarrow 提交的 #16746）——logs 命令新增了 --states / --no-states 标志和环境变量默认值，恢复了对日志流中是否显示状态变化的控制。

灯光组件增强

Section titled “灯光组件增强”

@jesserockz 添加了两个灯光改进：

  • light.effect.next 和 light.effect.previous 动作 （#16491）在灯光的已配置效果之间循环，无需硬编码效果名称。include_none: true 选项允许循环经过无效果状态。目标灯光必须至少有一个效果，在配置验证时检查。
  • Lambda 灯光效果将灯光作为 it 接收 （#16815）——与可寻址 lambda 效果的现有行为一致，因此简单 lambda 可以直接引用灯光，而无需 id(my_light)。

@clydebarrow 还为 LVGL 仪表弧添加了 rounded 属性 （#16669）。

其他值得注意的功能

Section titled “其他值得注意的功能”
  • LVGL 验证的显示元数据（#16702）—— 显示驱动现在注册 byte_order、rotation、draw_rounding、has_writer 和 has_hardware_rotation 元数据，使 LVGL 可以自动选择 byte_order、拒绝混合字节序， 并合并来自已连接显示的 draw_rounding 要求。
  • Mitsubishi CN105 摆风模式（由 @crnjan 提交的 #15653）—— Mitsubishi CN105 气候组件支持垂直 / 水平 / 双向摆风，跟踪最后非摆风叶片位置并在禁用摆风时恢复。
  • SDL 显示屏幕选择（由 @clydebarrow 提交的 #16363）——主机平台 SDL 显示现在可以在连接多个显示器时居中于特定显示器。
  • homeassistant.time 遵守显式时区（由 @clydebarrow 提交的 #16583）——本地配置的 timezone: 不再被 Home Assistant 的时区静默覆盖。
  • I2C 主机平台支持（由 @jesserockz 提交的 #14489）——在 Linux 主机平台上运行 ESPHome 时的基本 I2C 总线支持，适用于测试和主机端集成。

值得注意的 Bug 修复

Section titled “值得注意的 Bug 修复”
  • Nextion 设备信息存储重写（由 @edwardtfn 提交的 #16059）——connect_info 解析器被固定大小字段提取替代，消除了 comok 响应中的所有堆分配。设备信息现在始终在 dump_config() 中记录日志；旧的 dump_device_info YAML 选项已移除。

感谢贡献者

Section titled “感谢贡献者”

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

  • @swoboda1337 - 57 个 PR，包括 ESP-IDF 6 / 原生 RISC-V clang-tidy 基础设施、ESP8266 WPA2 默认设置变更、移除长期弃用的核心 API，以及 广泛的 ESP32 平台底层改造
  • @kahrendt - 19 个 PR，包括音频栈现代化 （RingBufferAudioSource 推广、任意位深混音器、重采样器直通、新的 router 扬声器） 以及 W5500 以太网 SPI 卸载
  • @clydebarrow - 16 个 PR，包括新的 motion IMU 中心，带 BMI270 和 LSM6DS 驱动、LVGL 显示元数据验证，以及 Home Assistant 时区修复
  • @jesserockz - 9 个 PR，包括 YAML frontmatter 支持、 light.effect.next / light.effect.previous 动作、RP2040/RP2350 变体选项、 esphome config --no-defaults 以及 100% 补丁覆盖率强制执行
  • @kbx81 - 4 个 PR，包括 WiFi 和以太网延迟初始化 RAM 回收工作
  • @p1ngb4ck - 2 个 PR，新增 FTDI FT23XX 和 Prolific PL2303 USB 串口驱动
  • @PolarGoose - 2 个 PR，涉及 DSMR，包括 EON Hungary 电表支持 和 dsmr_parser 库更新
  • @tomaszduda23 - 2 个 PR，涉及 nRF52 原生构建和网络 IPv6 强制执行
  • @rtyle - 2 个 PR，修复 QMP6988 传感器 I2C 错误处理
  • @Tomer27cz - 使用外部 dlms_parser 库对 DLMS 电表组件进行全面改造
  • @Ardumine - nRF52 的 Zephyr IPv6 网络支持
  • @remcom - 新的 PCM5122 音频 DAC 组件
  • @RT530 - 新的 XDB401 压力传感器组件
  • @crnjan - Mitsubishi CN105 气候组件的摆风支持
  • @edwardtfn - Nextion connect_info 堆分配重写

同时还要感谢 @bdraco、@Rapsssito、 @burundiocibu、@leodrivera、 @SoCuul、 @david-collett、@chemelli74、 @Eelviny、@gnumpi、 @GuzTech、@rwrozelle、 @exciton、@i-am-no-magic 以及 @kpfleming 的贡献，以及所有报告问题、测试预发布版本和在社区中提供帮助的每一个人。

破坏性变更

Section titled “破坏性变更”

平台变更

Section titled “平台变更”
  • WiFi（ESP8266）：默认 min_auth_mode 从 WPA 切换为 WPA2，与 ESP32 默认设置一致。 自 2026.1 以来的弃用警告一直在每次配置验证时提醒这一点。仅支持 WPA（TKIP）的旧路由器上的设备必须在 wifi: 下显式固定 min_auth_mode: WPA #16682

组件变更

Section titled “组件变更”
  • DSMR：electricity_switch_position 从 sensor: 移至 text_sensor:，因为匈牙利电表将其作为字符串（例如 ON）而非数字发出。请更新现有配置，在 text_sensor: 下声明该实体 #16561
  • DLMS 电表：重构为使用外部 dlms_parser 库，新增动态 OBIS 代码模式、二进制传感器支持、可选解密密钥以及可配置 UART 波特率（不再要求 2400 波特）。旧版硬编码属性模式继续可用；provider: 选项现已被忽略并伴有弃用警告，将在 2026.11.0 中移除 #15458
  • Nextion：dump_device_info YAML 选项已移除。设备信息现在始终存储并在 dump_config() 中记录日志。请从任何 display: Nextion 配置中移除 dump_device_info: true #16059
  • Home Assistant 时间：当在 platform: homeassistant 的 time: 组件上显式配置了 timezone: 时，Home Assistant 报告的时区不再覆盖它。依赖 HA 静默覆盖过时本地时区的配置应移除本地 timezone: 条目 #16583

核心变更

Section titled “核心变更”
  • custom_components/ 文件夹已移除：已弃用的 custom_components/ 目录自动加载器已被移除。请改用 external_components。自 2025.6 以来一直有弃用警告 #16679
  • 敏感值脱敏：cv.sensitive() 现在通过 YAML representer 直接驱动运行时脱敏，而不是事后转储的正则表达式。WiFi SSID 现在被标记为敏感，将在 esphome config 输出中与密码一起脱敏。无需更改 YAML；传递 --show-secrets 以绕过脱敏 #16690

未记录的 API 变更

Section titled “未记录的 API 变更”

引用内部 C++ 类型的 Lambda 用户和外部组件作者应注意以下变更。该类型在运行时行为不变，但其名称已更新以符合项目的标识符命名约定：

  • MIPI DSI 显示类已重命名：mipi_dsi::MIPI_DSI 现为 mipi_dsi::MipiDsi。任何引用旧类型名称的 lambda 或外部组件必须使用新拼写。行为无变化 #16837

    // Before
    auto *display = static_cast<mipi_dsi::MIPI_DSI *>(...);
    

    // After
    auto *display = static_cast<mipi_dsi::MipiDsi *>(...);

开发者的破坏性变更

Section titled “开发者的破坏性变更”
  • Component::mark_failed / status_set_error 的 const char * 重载已移除：请使用 LOG_STR("...") 中的 const LogString * 重载 #16680
  • cv.only_with_esp_idf 和 CORE.using_esp_idf 已移除：迁移到 cv.only_on_esp32 和 CORE.is_esp32；仅在极少数的实际工具链检查中使用 CORE.using_toolchain_esp_idf #16681
  • text_sensor::TextSensor::raw_state 公共成员已移除：请改用 get_raw_state() #16683
  • nfc::format_uid(span) / nfc::format_bytes(span) 堆辅助函数已移除：请切换到栈缓冲区 变体 nfc::format_uid_to(buf, span) / nfc::format_bytes_to(buf, span)，配合 FORMAT_UID_BUFFER_SIZE / FORMAT_BYTES_BUFFER_SIZE #16684
  • seq<> 和 gens<> 元组解包模板已从 core/automation.h 中移除：请使用 std::index_sequence / std::index_sequence_for #16685
  • audio::scale_audio_samples 已弃用：请切换到来自捆绑 esp-audio-libs 的 esp_audio_libs::gain::apply（Q31 缩放因子、字节缓冲区、显式 bytes_per_sample）。计划在 2026.12.0 中移除 #16831
  • cv.sensitive() 模式标记：外部组件模式现在应使用 cv.sensitive(...) 包装敏感字段，以便在 esphome config 输出中脱敏。旧的正则表达式回退在 2026.12.0 之前作为弃用桥梁保留 #16690

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

版本 2026.6.1 - 6月19日

Section titled “版本 2026.6.1 - 6月19日”

版本 2026.6.2 - 6月20日

Section titled “版本 2026.6.2 - 6月20日”

版本 2026.6.3 - 6月26日

Section titled “版本 2026.6.3 - 6月26日”

版本 2026.6.4 - 7月1日

Section titled “版本 2026.6.4 - 7月1日”

版本 2026.6.5 - 7月9日

Section titled “版本 2026.6.5 - 7月9日”

完整变更列表

Section titled “完整变更列表”

新功能

Section titled “新功能”

新组件

Section titled “新组件”
  • [router] 添加路由器扬声器组件，在运行时选择输出扬声器 esphome#16592 by @kahrendt (new-component) (new-feature) (new-platform)
  • [motion] 为 IMU 实现中心组件 esphome#16226 by @clydebarrow (new-component) (new-feature) (new-platform)
  • [pcm5122] 添加 PCM5122 音频 DAC 组件 esphome#15709 by @remcom (new-component) (new-feature) (new-platform)
  • [xdb401] XDB401 压力传感器 esphome#15108 by @RT530 (new-component) (new-feature) (new-platform)
  • [bmi270] 支持 Bosch BMI270 IMU esphome#16202 by @clydebarrow (new-component) (new-feature) (new-platform)
  • [lsm6ds] 为 STMicro LSM6DS IMU 添加 motion 平台 esphome#16232 by @clydebarrow (new-component) (new-feature) (new-platform)

新平台

Section titled “新平台”
  • [router] 添加路由器扬声器组件，在运行时选择输出扬声器 esphome#16592 by @kahrendt (new-component) (new-feature) (new-platform)
  • [motion] 为 IMU 实现中心组件 esphome#16226 by @clydebarrow (new-component) (new-feature) (new-platform)
  • [pcm5122] 添加 PCM5122 音频 DAC 组件 esphome#15709 by @remcom (new-component) (new-feature) (new-platform)
  • [dlms_meter] dlms_parser 库 esphome#15458 by @Tomer27cz (new-feature) (breaking-change) (new-platform)
  • [xdb401] XDB401 压力传感器 esphome#15108 by @RT530 (new-component) (new-feature) (new-platform)
  • [bmi270] 支持 Bosch BMI270 IMU esphome#16202 by @clydebarrow (new-component) (new-feature) (new-platform)
  • [lsm6ds] 为 STMicro LSM6DS IMU 添加 motion 平台 esphome#16232 by @clydebarrow (new-component) (new-feature) (new-platform)

破坏性变更

Section titled “破坏性变更”
  • [nextion] 用固定大小字段解析器替换 connect_info 向量，始终记录设备信息 esphome#16059 by @edwardtfn (breaking-change)
  • [time][homeassistant] 修复时区处理 esphome#16583 by @clydebarrow (breaking-change)
  • [core] 移除已弃用的 custom_components 文件夹加载 esphome#16679 by @swoboda1337 (breaking-change)
  • [wifi] 默认 ESP8266 min_auth_mode 为 WPA2 esphome#16682 by @swoboda1337 (breaking-change)
  • [core] 通过 yaml_util representer 进行敏感脱敏 esphome#16690 by @bdraco (breaking-change)
  • [dmsr] [breaking] 修复使用自定义认证密钥的解密。为电报传感器添加 CRC。在 equipment_id 字段中自动检测十六进制字符串。支持 EON Hungary 智能电表 esphome#16561 by @PolarGoose (breaking-change)
  • [dlms_meter] dlms_parser 库 esphome#15458 by @Tomer27cz (new-feature) (breaking-change) (new-platform)

所有变更

Section titled “所有变更”