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

ESPHome 2026.3.0 - 2026年3月

Serial ​Proxy
Media ​Source ​Core
Audio ​File ​Media ​Source
Audio ​File
HDC3​0​2​x
温​度​与​湿​度​
SEN6​x
颗​粒​物​、​温​度​、​湿​度​、​VOC、​NOx ​与​ ​CO2​
RP2​0​4​0​ ​BLE
Dew ​Point

发布概述

Section titled “发布概述”

ESPHome 2026.3.0 是一个注重性能的发布版本，对整个技术栈进行了深度优化。主循环在 socket 轮询上速度提升高达 99 倍，light gamma 校正速度提升 8-10 倍，API protobuf 编码速度提升 6-12 倍，millis() 速度提升 2.5 倍，所有这些降低了 CPU 开销并提高了响应速度，特别是在单核芯片和蓝牙代理设备上。通过 printf 包装、scanf 移除、时区重构和激进的虚函数消除，节省了 11-20KB+ 的闪存。

除了性能优化工作外，重新设计的具有可插拔来源、播放列表和 Ogg Opus 支持的多媒体播放器架构与 RP2040/RP2350 达到一级平台支持同步发布——pico-sdk 2.0、143+ 板定义、BLE 基础、崩溃诊断和捕获门户。一个长期存在的 LWIP 使用-after-free 漏洞（导致 ESP8266 和 RP2040 堆损坏崩溃）已修复——两个平台现在都能通过压力测试。来自 @swoboda1337 的 86 项修复代码库正确性审查，解决了 100+ 组件中的缓冲区溢出、millis() 溢出错误、未初始化变量和逻辑错误。ESP32 获得了自动崩溃处理程序，可捕获重启间的回溯并通过 API 报告——无需串口线。ESP32-P4 和 ESP32-C5 获得了扩展的硬件支持，nRF52 获得了 BLE OTA，新组件包括 SEN6x、HDC302x、露点和串口代理。

升级清单

Section titled “升级清单”
  • 如果你使用 opentherm 并使用了 opentherm_version 配置键，请将其重命名为 opentherm_version_controller
  • 如果你使用 speaker 多媒体播放器并通过硬编码 URL 流式传输音频（而非通过 Home Assistant），请设置 codec_support_enabled: all 以保持所有编解码器可用
  • 如果你有 ESP32-P4 工程样品（pre-rev3），请在 esp32: 配置中添加 engineering_sample: true
  • 如果你使用 sgp30 传感器，请在更新后为多达 12 小时的重新校准做准备，因为存储的基线将因序列号修复而被失效
  • 如果你使用 nextion 并通过慢速网络上传 TFT，请将 tft_upload_http_timeout 设置为更高值（默认值从 15s 更改为 4.5s）
  • 如果你使用 time 组件且有 lambda 直接调用 ::mktime()、::strftime()、setenv("TZ", ...) 或 tzset()，请更新它们以使用 ESPHome 的 ESPTime API
  • 如果你在连接到 gpio binary_sensor 的物理按钮上使用 on_multi_click、on_click、on_double_click 或在 on_press / on_release 中计数边沿，且没有防抖过滤器，请在该传感器的 filters: 列表中添加 delayed_on_off: 20ms 过滤器（或 delayed_on / delayed_off）。大多数用户已经遵循了文档指南；这仅影响跳过了该指南的配置。即时 ISR 唤醒的更改（#14383）意味着机械开关抖动现在会到达下游自动化，而不是被缓慢的循环轮询节律吞没。请参阅防抖值。

主循环性能大修

Section titled “主循环性能大修”

本版本为核心事件循环带来了重大性能大修，降低了所有平台上的 CPU 开销并提高了响应速度。

Socket 轮询：ESP32 上快高达 99 倍

lwip_select() 系统调用已在 ESP32 上被直接 LwIP socket 读取和 FreeRTOS 任务通知取代（#14249）。旧的 select() 调用由于内部锁开销，每次循环迭代消耗约 133us。新的预睡眠扫描仅需约 1.3us（快 99 倍），活动轮询路径消耗约 7.5us（快 17 倍），唤醒机制从约 130us 降至约 1.8us（快 72 倍），释放了约 1.55% 的总 CPU 时间。在单核芯片（ESP32-C3、C6、H2）上，这通过消除与 WiFi/BLE 堆栈的互斥锁竞争，直接提高了 BLE 扫描响应速度。该优化也已扩展到所有 LibreTiny 平台（bk72xx、rtl87xx、ln882x）（#14254），实际测试显示 WiFi 连接时间从最长达 60 秒降至 30 秒以下。

即时 ISR 唤醒

GPIO 二进制传感器和触摸传感器现在从中断中立即唤醒主循环，而不是等待最长约 16ms 的 select 超时（#14383）。UART 接收唤醒也进行了重新设计——用直接 ISR 回调替换了 FreeRTOS 任务 + 事件队列（每个 UART 约 3.9KB 堆），成本几乎为零（#14382）。使用新的近零成本机制后，接收唤醒现在默认在所有 ESP32 UART 上启用（#14391），ESP8266 也为 GPIO 二进制传感器获得了 ISR 唤醒支持（#14392）。

原生 64 位时间和更快的 millis()

新的 millis_64() HAL 函数在所有平台上提供 64 位运行时间，替换了调度器的回绕跟踪（#14339）。在 ESP32 上，这直接读取 esp_timer_get_time()（26 字节，无锁）而非 193 字节的回绕重建路径。RP2040 使用硬件定时器的 time_us_64()（#14356），Host 使用 clock_gettime(CLOCK_MONOTONIC)（#14340）。ESP8266 和 LibreTiny 使用轻量级软件回绕跟踪器。uptime 和 web_server 等组件现在直接从 hal.h 调用 millis_64()，而非经过 App.scheduler。

millis() 函数本身——每个组件每次循环迭代调用一次——也通过使用 Euclidean 分解 优化，消除了 __udivdi3 软件 64 位除法例程，每次调用实现了 2-2.5 倍加速（#14409）。

循环调用开销

主循环现在直接调用 component->loop()，而不是经过 call() → call_loop_() → loop()，每次迭代每个组件消除了 2 个不必要的函数帧（#14451）。对于拥有 120 个循环组件的设备，每次循环周期减少了 240 个函数帧。平凡的组件状态访问器（get_component_state()、is_failed() 等）被移至内联头文件定义，消除了相当于单字节加载的函数调用开销（#14425）。每次循环迭代调用的 is_high_frequency() 检查也被内联了（#14423）。

缓存的连接检查

WiFi is_connected() 现在将连接状态缓存为简单的 bool 字段，消除了每次调用昂贵的 SDK 调用（#14463）。network::is_connected() 和 EthernetComponent::is_connected() 函数被移至头文件作为内联（#14464）。OpenThread 连接状态现在通过回调更新，而非每次循环用互斥锁轮询（#14484）。API 服务器的 is_connected() 被拆分为常见无参数情况的内联快速路径和状态订阅检查的离线路径，对 BLE 代理热路径很重要（#14574）。

RP2040/RP2350：一级平台支持

Section titled “RP2040/RP2350：一级平台支持”

RP2040/RP2350 平台在本版本中向一级支持迈出了重大一步。arduino-pico 框架从 3.9.4 跃升至 5.5.0，带来了 pico-sdk 2.0 和 GCC 14 工具链（#14328）。RP2350（Pico 2 W）现已在真实硬件上验证，WiFi、调试传感器和 OTA 全部正常工作，该平台获得了 ESP32 用户所期望的相同可靠性、工具链和开发体验。

框架更新带来的功能：

  • RP2350 硬件已验证 - Pico 2 W 经过 WiFi、调试传感器和 OTA 测试，全部正常工作（429KB 空闲堆）
  • 143+ 板定义（从 3 个增加）从 arduino-pico 仓库自动生成，包括所有 RP2350 变体（#14528）
  • WiFi 可靠性修复 - 正确的 CYW43 链接状态检测、非阻塞 WiFi 连接和正确的断开清理

新能力：

  • BLE 基础 - 新的 rp2040_ble 组件在 Pico W/Pico 2 W 板上初始化 BTstack，为 BLE 扫描和蓝牙代理支持奠定基础，开销仅约 17KB（#14603）
  • 通过 picotool 的 BOOTSEL 上传 - esphome upload 现在检测处于 BOOTSEL 模式的 RP2040 设备，以实时进度上传，并在重启后自动开始日志输出（#14483）
  • HardFault 崩溃处理程序 - 详见下面的崩溃处理程序（无需串口线）部分（#14685, #14716）
  • 单引脚硬件 UART - RP2040 现在支持仅配置 TX 或仅 RX 的硬件 UART，适用于单向串行协议（#14725）
  • RP2350 ADC 修复 - 使用 ADC 组件时，修复了 RP2350 板上的 PICO_VSYS_PIN 编译错误（#14724）
  • Socket 唤醒支持 - 快速 select 优化已移植到 RP2040，实现了无需 lwip_select() 开销的高效 socket 轮询（#14498）
  • WiFi AP 和捕获门户 - WiFi AP 模式和 AP+STA 回退现在在 RP2040/RP2350 上可靠工作，arduino-pico 5.5.1 中有 7 个 WiFi 修复（#14500）。捕获门户组件也已为该平台启用（#14505）

可靠性：

  • LWIP PCB 使用-after-free 已修复 - 一个长期存在的 bug，tcp_close() 在 TCP 关闭握手期间让 PCB 保持活动状态，允许 LWIP recv/err 回调在 socket 对象销毁后以悬空指针触发，现已修复（#14706）。这导致了困扰 ESP8266 可靠性多年的 umm_malloc_core 堆损坏崩溃，也影响了 RP2040。两个平台现在都通过了 4 个并发客户端的 500 次快速连接/断开压力测试。
  • TCP 竞态条件已修复 - Pico W 上 lwip IRQ 回调与主循环之间的关键竞态已被识别并修复，防止并发 API 连接下的堆损坏（#14679）
  • IRQ 中接受堆损坏已修复 - RP2040 上的 socket accept 回调不再在 IRQ 上下文中分配内存，消除了快速连接/断开压力测试下的崩溃（#14687）
  • OTA 超时已修复 - ESP8266 和 RP2040 上的 OTA 更新在高负载下不再超时；从轮询切换到 SO_RCVTIMEO 以实现可靠的 socket 读取（#14675）
  • WiFi 重连后 mDNS 重启 - RP2040 上的 mDNS 现在在 WiFi 重连后正确重启，修复了服务发现失败（#14737）
  • I2C 总线选择 - 修复 RP2040 I2C 总线选择，根据引脚分配正确选择硬件 I2C 外设（#14745）
  • 调试重置原因 - debug 组件现在在 RP2040/RP2350 上正确报告重置原因（#14740）

闪存与性能：

  • 9.2KB 闪存节省，来自 printf 存根优化（#14622）
  • 原生 millis_64() 使用硬件定时器，消除软件回绕跟踪（#14356）
  • 更快的 millis() 通过优化的 64 位除法，每次调用快 2-2.5 倍（#14409）

注意：框架更新是对使用旧 pico-sdk API 的外部组件的破坏性变更（例如，padsbank0_hw 重命名为 pads_bank0_hw，SerialPIO::NOPIN 现在仅为 NOPIN）。

LibreTiny 平台改进

Section titled “LibreTiny 平台改进”

LibreTiny 平台（BK72xx、RTL87xx、LN882x）在本版本中进行了显著的可靠性和性能大修。

lwIP 内存调优（BK72xx 上释放约 26KB）：

SDK 默认的 lwIP 缓冲区大小是针对 WiFi Alliance 吞吐量认证设计的，而非 IoT 设备。TCP_SND_BUF 在 10xMSS（每块 14.6KB）时导致 BK7231N 在 ESPAsyncWebServer 分配响应缓冲区时出现 OOM。切换到系统堆分配（MEM_LIBC_MALLOC=1、MEMP_MEM_MALLOC=1）并调整缓冲区大小后，BK7231N 释放了约 26.5KB，RTL87xx 释放了约 20.2KB（#14186）。这也修复了 BK72xx 上由于 MSS 大小 pbuf 分配期间的专用堆碎片化导致的 OTA 缓慢问题。Socket 计数现在从组件注册自动计算，而非硬编码。

BK72xx 循环卡顿已修复：

BK72xx 主任务运行在 FreeRTOS 优先级 3，低于所有 WiFi（4-5）和 LwIP（4）任务，每当 WiFi 后台处理运行时都会导致约 100ms 的循环卡顿。将优先级提高到 6（与 RTL87xx 的有效优先级匹配），循环时间从约 110ms 降至约 14ms（#14420）。

其他改进：

  • BK72xx -Os 优化 - ESPHome 源代码现在在 BK72xx 上以 -Os 编译，而 SDK 保持在 -O1，在不触发 SDK bug 的情况下改善了闪存使用（#14322）
  • 快速 select 优化 - ESP32 socket 轮询优化已移植到所有 LibreTiny 平台，实际 WiFi 连接时间从最长达 60 秒降至 30 秒以下（#14254）
  • 直接 SDK SSID 获取 - WiFi SSID 查询现在直接调用厂商 SDK 函数，而非经过 Arduino 的 String 分配式 WiFi.SSID()（#14349）

nRF52 平台改进

Section titled “nRF52 平台改进”

nRF52 平台获得了关键的 OTA 和调试能力，感谢 @tomaszduda23。

BLE 和串口 OTA：

  • 新的 zephyr_mcumgr 组件通过 MCUmgr 协议启用通过 BLE 或串口的空中更新（#11932）。这对 nRF52 设备是重大进步，之前缺乏无线更新支持。

崩溃调试：

  • nRF52 上现在可用的早期启动调试消息，包括启动原因日志记录和在无初始化缓冲区中存储的上次崩溃 PC/LR 值（#11685）。logger 等待最多 10 秒供 CDC 端口打开，确保没有早期日志丢失。

BLE NUS UART：

  • ble_nus 组件现在支持通过蓝牙进行双向 UART 通信，与 ble-serial 等工具兼容（#14320）。

调度器性能

Section titled “调度器性能”

调度器在每个设备上驱动所有计时器、间隔和延迟回调。本版本包含 7 项针对性优化：

  • 延迟队列锁减半 - 锁获取从 2N+1 减少到 N+1（N 个延迟项），当队列为空时（常见情况）完全跳过锁（#14107）
  • 放宽内存排序 - 调度器锁下的原子读取现在使用 relaxed ordering，因为锁已经提供了必要的内存屏障（#14140）
  • 原子 bool 修复 - GCC 在 Xtensa 上为 std::atomic<bool>::load() 生成了间接函数调用而非内联。切换到 std::atomic<uint8_t> 消除了热路径上的 5 个间接调用，节省 30 字节（#14626）
  • 原始指针生命周期管理 - 用显式生命周期管理替换了 unique_ptr<SchedulerItem>，消除了 608 字节的 STL 模板实例化（__adjust_heap、_M_realloc_append 等），并添加了调试泄漏检测（#14620）
  • 取消模板化辅助函数 - 合并调度器辅助函数以减少代码重复（#14164）
  • 右值 std::function - 调度器回调现在通过右值引用传递，避免不必要的复制（#14260）
  • millis_64 提取 - 32 位回绕跟踪代码已从调度器中移出到其自己的模块，移除了对 App.scheduler 初始化的依赖，并允许 defer() 项完全跳过 millis_64() 调用（#14360）

API 与 Protobuf 性能

Section titled “API 与 Protobuf 性能”

原生 API 通信层在本版本中收到了 20 多项针对性优化，特别是对 protobuf 编码占主导 CPU 成本的蓝牙代理设备受益明显。

编码管线：

  • 直接缓冲区写入 - Protobuf 编码现在通过原始指针写入预尺寸缓冲区，而非 push_back()，基准测试中编码速度快 6-12 倍（#14018）
  • Protobuf 虚函数消除 - encode() 和 calculate_size() 在编译时解析，而非通过虚拟分发，传感器状态消息的 calculate_size() 快 2 倍，API 组件 CPU 时间减少 2.5 倍（#14449）
  • 单次遍历 BLE 广告编码 - 消除每次 BLE 代理刷新时 24 次冗余的 calculate_size() 调用，编码时间减少 28%（#14575）
  • 零填充消除 - 自定义 APIBuffer 替换 std::vector<uint8_t> 作为 protobuf 缓冲区，跳过每次消息编码前的不必要零初始化，BLE 代理设备上的 API 组件 CPU 时间减少 43%（#14593）
  • 强制 proto 字段 - 已知非默认的 BLE 广告字段跳过零检查，BLE 批次的 calculate_size() 节省 13%（#14610）

解析与分发：

  • Varint 32/64 位分离 - Varint 解析对常见情况（1-4 字节值）使用快速 32 位算术，仅当 BLE 字段需要时使用 64 位，常见路径快 25-50%（#14039）
  • Varint 快速路径内联 - Protobuf varint 解析和编码热路径被内联，在紧循环中实现零函数调用开销（#14607, #14638）
  • 帧辅助函数虚函数消除 - 当仅配置一种 API 协议时（纯明文或纯 noise），所有帧操作的虚拟分发被消除（#14468）
  • Noise 数据路径优化 - 消除 noise 协议路径中每个数据包读/写的冗余状态机检查（#14629）
  • Keepalive ping 抽出 - keepalive/断开的冷路径已从 APIConnection::loop() 中抽出，热循环体减少 30%（Xtensa 上从 374 降至 263 字节），因为此代码每分钟仅触发一次（#14374）

加密：

  • ChaCha20-Poly1305 嵌入式优化 - ESPHome 维护的 libsodium 补丁将 poly1305 和 chacha20 实现中的非对齐字节加载替换为对齐的 32 位加载（#14632）。在 Xtensa 上，每个非对齐的 LOAD32_LE 分解为 4 条字节加载指令加移位；补丁后的路径使用直接对齐加载。每个加密的 API 数据包都受益：所有平台快 8-32%（ESP32 上 32%，ESP32-S3 上 24%，ESP32-C3 上 21%，RTL87xx 上 12%，ESP8266/BK72xx 上 10%，RP2040 上 8%，使用 1KB 数据包测量）。

网络层：

  • Socket 层大修 - 整个 socket 抽象被消除虚函数，将虚拟基类转换为具体的每平台类型（BSDSocketImpl、LwIPSocketImpl、LWIPRawImpl），零虚方法（#14398）。编译器现在将热路径 socket 方法（read、write、writev、ready）完全内联到 API 帧辅助函数和 OTA 块处理程序中，消除了每个数据包的 vtable 加载。ESP32 上节省约 3KB 闪存。Socket 指针缓存（#14408）进一步将整个 ready() 链内联到约 30 字节，零函数调用。
  • 握手超时 - 15 秒超时用于完成 API 握手，防止陈旧半开连接耗尽连接槽（#14050）
  • 内联发送缓冲区快速路径 - 每次 send_buffer() 调用的 try_to_clear_buffer() 检查现在内联，当 TX 缓冲区已为空时避免函数调用（#14630）
  • TCP_NODELAY 快速路径 - 设置 TCP_NODELAY 现在直接写入 PCB 标志，绕过昂贵的 lwip_setsockopt 开销（#14693）

BLE 事件处理：

  • BLE 事件热路径优化 - 消除 ESP32 BLE 事件处理循环中的冗余操作，包括对丢包计数检查的短路（常见情况 4 条指令而非约 25 条）和移除冗余的事件释放调用（#14627）

Light 优化

Section titled “Light 优化”

Light gamma 校正中的运行时 powf() 调用已被编译时生成的预计算 PROGMEM 查找表取代（#14123）。ESP32 上 5 通道 RGBWW light 过渡帧从 349us 降至 36us（快 8-10 倍），ESP8266 上从 456us 降至 58us。可寻址灯每个实例还节省 512 字节堆——RAM gamma 表完全消除。powf 数学库（约 2.3KB 闪存）不再被引入 light 二进制文件。

Light 颜色插值现在使用轻量级 lerp_fast 而非 std::lerp（#14238），静态效果名称在代码生成时解析为整数索引，而非运行时字符串匹配，ESP8266 上节省 632 字节（#14265）。

powf 消除扩展到 light 之外——新的 pow10_int() 辅助函数替换传感器过滤器和精度规范化中的 powf(10, exp)，ESP8266 上计算快达 22 倍，节省 3.1KB 闪存（#14114）。

Logger 优化

Section titled “Logger 优化”

Logger 收到了 7 项针对性优化，恢复了浪费的 RAM 并降低了每次日志调用开销：

  • UART 堆浪费已消除 - 从 ESP32 的 uart_driver_install() 中移除了未使用的 FreeRTOS 事件队列和过大的 RX 缓冲区，恢复约 595 字节堆（#14168）
  • TX 缓冲区编译时定大小 - 发送缓冲区现在是内联数组而非单独的堆分配，将两次分配合并为一次（#14205）
  • 循环禁用修复 - logger 的空操作 loop() 因预处理宏错误（USE_LOGGER_USB_CDC 而非 USE_LOGGER_UART_SELECTION_USB_CDC）在所有 ESP32-S2/S3/C3/C5/C6/H2/P4 变体上以约 114 次/秒运行（#14158）
  • LogListener 虚函数消除 - 用轻量级 LogCallback 结构体（函数指针 + 实例指针）替换 LogListener 抽象类，消除了实现它的每个类的 vtable 开销（#14084）
  • Logger 和 trigger 标记为 final - 使编译器能够消除对 loop()、dump_config() 和 get_setup_priority() 的虚函数调用（#14291）
  • 更快的行号格式化 - 用减法循环替换基于除法的格式化，ESP8266 上快 1.8 倍（无硬件除法器），ESP32-C3 上快 1.44 倍（#14219）
  • 热路径优化 - 消除每次日志调用的空检查和调用帧间接，在调试构建中实现早期日志检测（#14538）

内存与闪存优化

Section titled “内存与闪存优化”

几项重大优化降低了所有平台上的固件大小和 RAM 使用。

时区大修（ESP32 上约 9.5KB 闪存，ESP8266 上约 2% RAM）：

整个 libc 时区基础设施已被轻量级 32 字节结构体解析器替换（#13635）。以前，ESPHome 引入 libc 的 scanf 系列（约 9.8KB）、环境变量基础设施和双重存储的时区数据，只为解析一个它已知的字符串。新实现还提供了跨平台一致的时区行为，包含 126 个单元测试，消除了不同芯片上 newlib 版本之间的差异。直接使用 ::mktime() 或 setenv("TZ", ...) 的 lambda 可能需要更新。

平台闪存节省RAM 节省
ESP32-IDF~9.5KB136 字节
ESP8266~4.1KB~850 字节
LibreTiny~4.7KB148 字节
RP2040~3.7KB148 字节

printf/scanf 包装：

  • ESP32 printf 包装节省约 11KB 闪存 - printf()、vprintf() 和 fprintf() 用轻量级存根包装，通过 vsnprintf() 重定向，消除 newlib 的 _vfprintf_r 死代码（#14362）
  • ESP8266 scanf 移除节省约 8KB 闪存 - 强制的 -u _scanf_float 链接器标志已移除，垃圾收集整个未使用的 scanf 系列（#13678）
  • ESP8266 printf 存根节省约 1.6KB 闪存（#14621）
  • RP2040 printf 存根节省约 9.2KB 闪存（#14622）

无需堆分配的 JSON 序列化：

web_server、MQTT 和 API 响应的 JSON 序列化现在使用堆栈优先的 SerializationBuffer，处理 99.9% 的载荷（最高 640 字节）而无需任何堆分配（#13625）。以前，每个 JSON 响应都在堆上构建 std::string。新缓冲区仅在异常大的载荷（40+ select 选项、极端气候预设）时回退到堆。用户服务字符串参数也从 std::string 切换到了 StringRef（#13974）。

Preferences 堆抖动消除：

大多数 preference 保存（开关、风扇、窗帘、数字、旋转编码器）现在使用小的内联缓冲区，而非每次保存操作进行堆分配（#13259）。基于 union 的 SmallInlineBuffer<8> 在 8 字节或更小时内联存储数据，消除了长期运行设备上重复 preference 写入导致的堆碎片化。

实体字符串打包：

实体字符串属性（device_class、unit_of_measurement、icon）被打包到 PROGMEM 索引的 uint8_t 字段中，存储在结构体填充字节中，替换了每个实体的 const char* 指针（#14171）。这每个实体节省 8-12 字节，零额外内存成本，因为索引适合对齐填充。测量：ESP32-S3（大型配置）上空闲堆 +3,084 字节，ESP8266 上 +369 字节。应用 name 和 friendly_name 也从 std::string 转换为 StringRef，节省 416-2,508 字节闪存，ESP8266 上空闲堆 +308 字节（#14532）。

ESP8266 PROGMEM 优化：

  • 图标字符串移至闪存 - 每个唯一图标节省约 27 字节（40 个图标的配置约 1KB）（#14437）
  • 设备类字符串移至闪存 - 同样处理了设备类字符串，在 MQTT 和 API 中进行了去重处理（#14443）
  • 静态字符串通过 TemplatableValue 自动包装在 PROGMEM 中（#13885）
  • 实体设置调用合并 - set_name + set_entity_strings 合并为单个 configure_entity_() 调用，约 30 个实体的配置上节省 124 字节闪存（#14444）
  • IRAM 释放 - 从 yield()、delay()、feed_wdt() 和 arch_feed_wdt() 中移除了不必要的 IRAM_ATTR，ESP8266 上释放约 22 字节 IRAM（#14063）

ESP-IDF 5.5.3：

ESP-IDF 已升级到 5.5.3（#14122），修复了 5.5.1 和 5.5.2 中长期的 BLE bug，其中蓝牙在 ESP32 设备上停止工作。遇到 BLE 连接断开或蓝牙代理失败的用户应该会看到这些已解决。后续升级到 5.5.3.1（#14147）修复了 Bluedroid 编译错误，允许回退无条件启用 GATTS 的变通方法。

框架与核心优化：

  • 组件虚函数消除 - call_loop()、mark_failed() 和 call_dump_config() 现在是非虚拟的，从 vtable 消除中节省约 800+ 字节闪存（#14083, #14355）
  • 编译时循环检测 - 不覆盖 loop() 的组件现在在编译时检测到并从循环列表中排除，消除运行时 vtable 探测（#14405）
  • 条件过滤编译 - 传感器、文本传感器和二进制传感器过滤器基础设施现在在没有配置过滤器时完全编译掉，节省闪存和 RAM（#14213, #14214, #14215）
  • FLAC CRC 验证禁用 - 跳过 FLAC 解码期间的内部 CRC 检查，吞吐量提高 15-20%（#14108）
  • 整个代码库的 constexpr 迁移 - 超过 20 个 PR 将核心、API、BLE、NFC、MQTT 和显示组件中的 static const 转换为 constexpr，将常量移至闪存并启用编译器优化（#14071, #14127, #14129 等）
  • esphome::optional 替换为 std::optional - 用 C++17 标准替换自定义实现（#14368）

崩溃处理程序（无需串口线）

Section titled “崩溃处理程序（无需串口线）”

ESP32：

ESP32 使用 ESP-IDF 框架的设备有了新的崩溃处理程序，自动在崩溃发生时捕获回溯，存储在 .noinit 内存中（在软件重置后存活），并在下次启动时记录数据（#14709）。崩溃数据出现在通过 API 的 esphome logs 中——无需串口线——并在启用”订阅日志”时的 Home Assistant 日志查看器中。CLI 自动使用 addr2line 内联解码地址。

该处理程序在 Xtensa（ESP32、S2、S3）和 RISC-V（C3、C6、H2、C2）架构上均可工作，最多捕获 16 个回溯帧，具有人类可读的异常原因。在 RISC-V 上，栈扫描条目经过验证和标记，以区分注册表来源的帧。内存成本极低：+92 字节 RAM，+1,092 字节闪存。无需配置——它自动为所有 ESP-IDF 设备启用。

RP2040/RP2350：

HardFault 崩溃处理程序在崩溃发生时捕获寄存器状态和栈回溯，通过看门狗 scratch 寄存器存储在重启间，并在下次启动时记录（#14685）。后续修复（#14716）改进了回溯存储和 logger 集成。CLI 的串口日志查看器使用 addr2line 自动解码地址。在 RP2040 和 RP2350 上均可工作。

ESP32-P4 与 ESP32-C5 改进

Section titled “ESP32-P4 与 ESP32-C5 改进”

ESP32-P4：

  • 触摸板支持 - esp32_touch 组件已迁移到 ESP-IDF v5.5 的统一触摸传感器驱动程序，新增 ESP32-P4 作为支持变体，拥有 14 个触摸通道（GPIO 2-15）（#14033）
  • 生产芯片默认 - 默认板现在针对 rev3+ 生产芯片，而非工程样品。使用 pre-rev3 开发套件的用户应设置 engineering_sample: true（#14139）
  • 从 PSRAM 执行 - P4 现在启用了从 PSRAM 执行代码，扩展了可用的指令内存（#14329）
  • LDO 通道 1 & 2 - esp_ldo 组件现在支持内部 LDO 通道，带有显式的 allow_internal_channel 保护，对 Waveshare ESP32-P4 等板有用，其中这些通道为外部外设供电（#14177）

ESP32-C5：

  • 双频 WiFi 配置 - 新的 band_mode 选项用于选择 ESP32-C5 双频无线电上的 2.4GHz、5GHz 或自动频段选择，感谢 @swoboda1337（#14148）

新传感器组件

Section titled “新传感器组件”

本版本新增了对几个新传感器系列的支持。

SEN6x 环境传感器节点：

新的 sen6x 组件支持 Sensirion 的整个 SEN6x 产品系列（SEN62、SEN63C、SEN65、SEN66、SEN68、SEN69C），多达 7 个测量通道：PM1.0/2.5/4.0/10、温度、湿度、NOx、VOC、CO2 和甲醛（#12553）。每个传感器变体自动仅暴露其可用通道。

HDC302x 温度与湿度：

新的 hdc302x 组件增加了对 Texas Instruments 高精度 HDC3020/3021/3022 传感器的支持，包括具有永久 PTFE 防尘和防水保护的 IP67 级 HDC3022（#10160）。

露点计算器：

新的 dew_point 组件从任何现有的温度和湿度传感器计算露点，无需额外硬件（#14441）。

串口代理（实验性）

Section titled “串口代理（实验性）”

新的 serial_proxy 组件将 UART 通信代理到网络上的 Home Assistant API 客户端（#13944）。这个实验性组件实现对连接到 ESPHome 节点的串行设备的远程访问，类似于 zwave_proxy 桥接 Z-Wave 调制解调器的方式。配置一个 UART 总线并将其作为命名串口暴露，指定类型（TTL、RS232、RS485）。

显示屏支持扩展

Section titled “显示屏支持扩展”

几个新显示屏型号现在开箱即用支持：

  • Waveshare DSI 触摸面板 - 5 款新的 MIPI DSI 型号，从 3.4 英寸到 10.1 英寸，支持触摸（#14023）
  • Waveshare 7.5 英寸 4 色电子纸（H） - 800x480 显示屏，支持黑/白/黄/红色（#13991）
  • WeAct 3 色电子纸 - 2.13 英寸、2.9 英寸和 4.2 英寸基于 SSD1683 的显示屏，支持红/黑/白（#13894）
  • Waveshare 1.83 英寸 v2 - 具有 Rev2 PCB 更新初始化序列的 MIPI SPI 面板（#13680）
  • 无 JPEG 的摄像头传感器 - esp32_camera 组件现在支持像 GC0308（m5stack AtomS3R-CAM）这样输出 RGB565 而非 JPEG 的传感器，具有自动软件 JPEG 转换（#9496）
  • 8 位 BMP 支持 - runtime_image 组件现在支持解码 8 位 BMP 图像，此外还有现有格式（#10733）

代码库正确性审查

Section titled “代码库正确性审查”

@swoboda1337 在本版本中贡献了 86 个 bugfix PR，系统地审查了代码库，修复了 100+ 组件中静默积累的问题。修复涵盖多个类别：

  • 缓冲区溢出和边界检查（16 个 PR） - 修复了 ld2410、ld2420、remote_receiver、fingerprint_grow、pn532、NFC、shelly_dimmer 和多个显示驱动器等组件中的越界读写（#14297, #14458, #14459, #14493, #14511 等）
  • millis() 溢出 bug（11 个 PR） - 修复了运行约 49 天后会失效的超时和持续时间检查，涉及 bl0942、shelly_dimmer、lcd_base、light 过渡、BLE presence、pn532、mcp2515、nextion 等（#14285, #14292, #14474 等）
  • 未初始化变量（5 个 PR） - 为 deep_sleep、remote_transmitter、sim800l、sen5x 和许多其他组件的成员变量添加了默认初始化器（#14556, #14636, #14659）
  • 逻辑和复制粘贴 bug（9 个 PR） - 修复了 dfplayer、ads1115、alpha3、mpu6886、sht4x 等组件中的错误运算符、掩码和重复代码（#14491, #14492, #14644）
  • 无符号整数下溢（多个 PR） - 修复了 esp32_improv、rf_bridge、display、pipsolar 和可寻址灯效果中的环绕 bug（#14466, #14546）
  • 除零保护 - 在 tsl2561、bl0942、graph、组合传感器等中添加了检查（#14634）
  • 格式错误的外部输入加固 - 为 BLE 广告、Nextion 响应、Modbus 帧和基于 UART 的传感器添加边界检查，防止因意外数据而崩溃（#14643, #14651）

新多媒体播放器架构（speaker_source）

Section titled “新多媒体播放器架构（speaker_source）”

多媒体播放器已围绕模块化的基于来源的架构重新设计，以支持即将推出的 Sendspin 多房间音频协议，感谢 @kahrendt。新的 speaker_source 多媒体播放器用灵活的编排器替换了单体 speaker 多媒体播放器，从可插拔的 media_source 组件路由音频。

关键功能：

  • 可插拔媒体源 - 音频源是插入播放器的独立组件。本版本包括用于嵌入式固件文件的 audio_file 媒体源，HTTP 流和 Sendspin 源计划在 future releases 中推出
  • 双管线支持 - 独立的媒体和公告管线，带有独立的扬声器、格式和来源，允许公告与音乐同时播放
  • 完整的播放列表管理 - 入队、上一/下一曲目导航、重复（关闭/单曲/全部）和使用 Fisher-Yates 算法的随机播放
  • 音量持久化 - 音量和平静状态在重启间保存，可配置最小/最大/增量
  • 扩展的多媒体播放器命令 - 新的 next、previous、repeat_all、shuffle、unshuffle、group_join 和 clear_playlist 操作（#12258）

audio_file 组件允许你将音频文件（本地或来自 URL）直接嵌入固件，无需网络访问即可即时播放。文件直接从闪存解码，与之前的方法相比节省两次缓冲区复制。

音频播放改进

Section titled “音频播放改进”
  • Ogg Opus 编解码器支持 - 新的 microOpus 库支持解码 Ogg Opus 文件，与 FLAC 和 MP3 一起完成编解码器阵容（#13967）
  • 更智能的编解码器构建 - 仅构建配置实际需要的编解码器。speaker_source 多媒体播放器会自动执行此操作，而 speaker 多媒体播放器的 codec_support_enabled 选项现在默认为 needed（流式传输任意 URL 的用户应设置 codec_support_enabled: all）
  • Speaker 多媒体播放器开关 - Speaker 多媒体播放器现在支持显式的开关控制（#9295）

其他值得注意的功能

Section titled “其他值得注意的功能”
  • !extend/!remove 适用于所有列表组件 - 期待已久的功能：!extend 和 !remove 现在适用于任何基于列表的配置条目（如 external_components），即使组件模式未声明 id 字段，感谢 @swoboda1337（#14682）
  • BLE 连接参数 API - 蓝牙代理现在可以调整连接的 BLE 设备的连接间隔，使 yalexs-ble 等集成在连接后从快速间隔（约 7.5ms）切换到慢速间隔（约 1000ms），显著减少 Yale/August 锁等”始终连接”设备的电池消耗（#14577）
  • 安全模式显式启动成功 - 新的 safe_mode.mark_boot_ok 操作允许你显式通知安全模式启动成功，解决了深度休眠设备在安全模式超时窗口内启动并休眠的问题（#14306）
  • CC1101 运行时配置 - 新的操作可在运行时更改频率、调制类型、符号速率、滤波带宽和其他 CC1101 无线电设置（#14141）
  • ESP32 BLE 身份验证 - 可配置的 min_key_size、max_key_size 和 auth_req_mode 用于 BLE 安全（#7138）
  • 集成传感器 set 操作 - 新的 set 方法用于发布和保存特定值到集成传感器（#13316）
  • LPS22DF 压力传感器 - 支持 LPS22 压力传感器系列的 DF 变体（#14397）
  • OpenThread 发送功率 - OpenThread 无线电的可配置发送功率（#14200）
  • HTTP 请求 TLS 缓冲区 - ESP8266 上可配置的 TLS 缓冲区大小，现代 Web 服务器发送 16KB TLS 记录时需要（#14009）
  • UART 调试前缀 - 新的 debug_prefix 选项用于在日志输出中区分多个 UART（#14525）
  • UART flush 结果 - flush() 方法现在返回指示成功/超时的结果，可通过 YAML 配置超时（#14608）
  • 版本文本传感器 hide_hash - 选项恢复不包含 git 哈希的 2026.1 前版本字符串格式（#14251）
  • GT911 通过 IO 扩展器中断 - 触摸中断线现在可以通过 IO 扩展器路由（#14358）
  • ESP32 托管 SDIO 时钟 - esp32_hosted WiFi 的可配置 SDIO 时钟频率（#14319）
  • Nextion 可配置 HTTP 参数 - TFT 上传超时、跟随重定向和 useragent 的新选项（#14234）
  • UART 模拟集成测试 - 新的集成测试基础设施实现了串行协议组件的自动化测试。LD24xx 系列（LD2410、LD2412、LD2420、LD2450）和 Modbus 收到了全面的测试以及 bug 修复（#14377, #14448, #14471, #14611, #14395）

感谢贡献者

Section titled “感谢贡献者”

本版本包含来自 50+ 贡献者的 480 个 pull requests。非常感谢所有使 2026.3.0 成为可能的人：

  • @swoboda1337 - 101 个 PR，包括横跨 100+ 组件的 86 项修复正确性审查、ESP32-C5 双频 WiFi，以及 !extend/!remove 配置增强
  • @kahrendt - 20 个 PR，构建新的多媒体播放器架构、Ogg Opus 编解码器支持、audio file 组件和 speaker 管线基础设施
  • @tomaszduda23 - 11 个 PR，推进 nRF52 平台，包括 BLE OTA（zephyr_mcumgr）、崩溃调试和 USB CDC 支持
  • @schdro - 8 个 PR，改进 OpenThread 堆栈，包括 TX 功率配置、连接缓存和构建优化
  • @kbx81 - 8 个 PR，包括新的串口代理组件、mixer speaker 去抖动和 UART flush 改进
  • @ximex - 7 个 PR，在 rtttl、ESP32 引脚验证和时间处理方面改进代码质量
  • @clydebarrow - 6 个 PR，包括 ESP32-P4 PSRAM 执行、const 清理和 USB UART 修复
  • @rwrozelle - 4 个 PR，改进 OpenThread，包括连接状态缓存和代码质量
  • @p1ngb4ck - 3 个 PR，添加 UART 调试前缀、ESP LDO 通道支持和 USB UART 芯片检测
  • @diorcety - 3 个 PR，交叉编译器兼容性和 ESP-IDF 构建修复
  • @exciton - 2 个 PR，创建 Modbus 集成测试基础设施并修复定时 bug
  • @pgolawsk - 2 个 PR，添加 WeAct 3 色电子纸支持和安全模式改进
  • @edwardtfn - 2 个 PR，改进 Nextion TFT 上传错误处理和可配置 HTTP 参数
  • @AndreKR - 2 个 PR，改进 ESP8266 TLS 日志记录和可配置缓冲区大小
  • @mikelawrence - 2 个 PR，重构 Sensirion 传感器库共享代码
  • @CFlix - 2 个 PR，包括新的露点传感器组件
  • @Rapsssito - 2 个 PR，MQTT 精度和 BLE server 测试
  • @mebner86 - 新的 SEN6x 传感器组件
  • @joshuasing - 新的 HDC302x 传感器组件
  • @mcassaniti - 安全模式的显式启动成功标记
  • @rwagoner - web server 的气候预设、风扇模式和湿度支持

同时感谢 @ademuri、@anunayk、@bharvey88、@ccutrer、@corneliusludmann、@deirdreobyrne、@edenhaus、@Gnuspice、@gtjoseph、@jamesmyatt、@jesserockz、@JiriPrchal、@jpeletier、@LinoSchmidt、@lwratten、@lyubomirtraykov、@mahumpula、@mback2k、@melak、@nagyrobi、@netixx、@oarcher、@PedanticAvenger、@puddly、@RAR、@rsre、@sredman、@sxtfov、@Szpadel、@tuct、@tvogel 和 @whitty 的贡献，以及所有报告问题、测试预发布版本并在社区中提供帮助的人。

破坏性变更

Section titled “破坏性变更”

大多数用户可以在不进行任何配置更改的情况下更新。以下项目按你是否需要采取行动进行了分组。

需要操作（如果你使用了这些组件）

Section titled “需要操作（如果你使用了这些组件）”
  • OpenTherm：已弃用的 opentherm_version 配置选项已移除。请改用 opentherm_version_controller #14103
  • ESP32-P4：默认板现在针对生产 rev3+ 芯片，而非工程样品。如果你有 pre-rev3 的 ESP32-P4 开发套件，请在 esp32: 配置中添加 engineering_sample: true #14139
  • Speaker 多媒体播放器：codec_support_enabled 选项现在默认为 needed，而非构建所有编解码器。如果你通过硬编码 URL（而非通过 Home Assistant）流式传输音频，请设置 codec_support_enabled: all 以恢复之前的行为 #13967
  • SGP30：修复序列号从 48 位截断为 24 位。这更改了 preference 哈希，因此现有的存储基线将不再被找到。请为多达 12 小时的重新校准做准备 #14478
  • Time：如果你有 lambda 直接调用 ::mktime()、::strftime()、setenv("TZ", ...) 或 tzset()，请更新它们以使用 ESPHome 的 ESPTime API。大多数用户不受影响，::localtime() 继续正常工作 #13635
  • GPIO 二进制传感器隐式防抖消失：主循环现在在 GPIO ISR 内部立即唤醒（#14383），而非等待 select() 超时。已经遵循防抖值指南并在物理按钮上有过滤器的配置不受影响。跳过了此指南的配置之前从缓慢的循环轮询节律中获得了意外的防抖效果；机械开关抖动现在会到达下游自动化，因此原始物理按钮上的基于时间的触发器（on_multi_click、on_click、on_double_click、on_press / on_release 中的边沿计数器）可能需要在其 gpio binary_sensor 的 filters: 列表中显式添加 delayed_on_off: 20ms 过滤器（或 delayed_on / delayed_off）。匹配器逻辑本身未更改。esphome#15323

大多数用户不受影响

Section titled “大多数用户不受影响”
  • RP2040：arduino-pico 框架已从 3.9.4 更新到 5.5.0（pico-sdk 2.0，GCC 14）。大多数用户配置不受影响，但针对 RP2040 的外部组件可能需要更新 #14328
  • ESP8266/RP2040：printf/vprintf/fprintf 现在用轻量级存根包装以节省闪存。需要完整 FILE*-based printf 的外部组件可以在其平台配置下设置 enable_full_printf: true #14621、#14622
  • Nextion：TFT 上传 HTTP 超时默认值从 15s 更改为 4.5s，以防止看门狗重置。使用慢速连接的用户可以通过新的 tft_upload_http_timeout 选项增加它 #14234
  • OpenThread：日志级别现在根据 esp32.framework.log_level 设置静态设置，而非动态 #14456
  • Micronova：为读写请求添加了命令队列。写入请求现在优先，读取请求已去重。这修复了静默忽略的写入请求和不完整的传感器更新 #12268
  • Time：libc 时区基础设施已被轻量级自定义解析器替换，ESP32 上节省约 9.5KB 闪存，ESP8266 上节省约 2% RAM。dump_config() 输出现在显示人类可读的时区信息（如 UTC-6:00 (DST UTC-5:00)）而非原始 POSIX 字符串 #13635
  • 图标（ESP8266）：图标字符串现在存储在 PROGMEM（闪存）中，最大长度为 63 个字符。所有标准的 mdi:* 图标都远低于此限制 #14437
  • 设备类（ESP8266）：设备类字符串同样移至 PROGMEM #14443
  • Light：通过整数索引调用 set_effect(0) 以禁用效果的 lambda 将获得歧义重载错误。请改用 set_effect(uint32_t{0}) 或 set_effect("None") #14732

未记录的 API 变更

Section titled “未记录的 API 变更”

这些是对 不稳定、未记录的 C++ API 的变更，可能影响编写 lambda 或维护外部组件的用户。这些 API 未在 esphome.io 上记录，且 不属于公共 API——它们可能随时变更而不另行通知。仅 esphome.io 上记录的 API 被视为稳定。如果你依赖这些内部 API，请自行承担风险。我们列出这些作为参考。

  • EntityBase：set_name()、set_icon()、set_device_class()、set_unit_of_measurement()、set_internal()、set_disabled_by_default() 和 set_entity_category() 已被移除并打包到现有的 configure_entity_() 调用中。set_device() 重命名为 set_device_() 并设为 protected。这些是代码生成专用的 setter——在运行时调用它们是不安全的，可能静默损坏状态或导致设备崩溃（未定义行为）。#14564、#14171、#14437、#14443
  • Time：libc 函数 localtime() 和 localtime_r() 在嵌入式平台上被覆盖，以使用 ESPHome 的自定义时区实现。setenv("TZ", ...)/tzset() 路径不再在内部使用。请参阅上面的破坏性变更部分以获取 lambda 迁移指南。#13635
  • API ProtoMessage：encode() 和 calculate_size() 不再虚拟。ProtoSize 类从累加器对象 API 转换为纯静态方法。调用 calculate_size() 的 lambda 现在应直接在消息上调用它（返回 uint32_t 而非填充 ProtoSize 对象）。#14449 
    // Before
    ProtoSize s;
    msg.calculate_size(s);
    uint32_t size = s.get_size();
    

    // After
    uint32_t size = msg.calculate_size();
  • APIServer：is_connected(bool state_subscription_only) 重载已移除。常见路径请使用 is_connected()（无参数，内联），罕见的仅状态订阅检查请使用 is_connected_with_state_subscription()。#14574
  • OTA：OTABackend 抽象基类已移除。局部变量使用 auto（来自 make_ota_backend()），成员变量使用 ota::OTABackendPtr。包含 ota_backend_factory.h 而非 ota_backend.h。#14473
  • OpenThread：OT 控制台（CONFIG_OPENTHREAD_CONSOLE_ENABLE）和 OT 诊断（CONFIG_OPENTHREAD_DIAG）现在默认禁用，最多节省约 22KB 闪存。使用 OT 控制台或诊断 C API 的自定义 lambda 需要通过 sdkconfig 重新启用这些。#14390、#14399
  • ByteBuffer：put_uint24(value, offset) 之前写入 4 字节而非 3 字节，损坏了相邻字节。依赖旧（有 bug 的）行为的 lambda 可能看到不同的结果。#14555

开发者的破坏性变更

Section titled “开发者的破坏性变更”

虚函数消除

Section titled “虚函数消除”

几个核心虚拟接口已被编译时分发替换以提升性能。覆盖或依赖虚拟分发的外部组件可能需要更新：

  • Component：call_loop()、mark_failed() 和 call_dump_config() 虚函数消除 #14083、#14355
  • Logger：LogListener 虚拟接口替换为 LogCallback 结构体 #14084
  • Socket：Socket 抽象层虚函数消除 #14398
  • OTA 后端：OTABackend 抽象基类已移除。使用 ota::OTABackendPtr 类型别名和 auto 用于 make_ota_backend() 返回值 #14473
  • Protobuf API：encode() 和 calculate_size() 在 ProtoMessage 上现在是 非虚拟的。ProtoSize 转换为静态方法。send_message() 现在是模板化的并推导出 MESSAGE_TYPE #14449

实体 API 变更

Section titled “实体 API 变更”
  • 实体图标/设备类 API：get_icon_ref()、get_icon()、get_device_class_ref() 和 get_device_class() 在非 ESP8266 上已弃用，ESP8266 上为 static_assert 错误。请改用 get_icon_to(std::span<char, MAX_ICON_LENGTH>) 和 get_device_class_to(std::span<char, MAX_DEVICE_CLASS_LENGTH>) #14437、#14443
  • EntityBase setter：set_name()、set_icon()、set_device_class()、set_unit_of_measurement()、set_internal()、set_disabled_by_default()、set_entity_category() 已移除（现在打包到 configure_entity_() 中）。set_device() 重命名为 set_device_() 并设为 protected #14564、#14171、#14437、#14443
  • 实体字符串属性：打包到 PROGMEM 索引的 uint8_t 字段中 #14171

类型和容器变更

Section titled “类型和容器变更”
  • esphome::optional：替换为 std::optional #14368
  • Application name/friendly_name：从 std::string 更改为 StringRef #14532
  • http_request headers：std::map 和 std::list 替换为 std::vector #14024、#14027
  • SerializationBuffer：新的堆栈优先 JSON 序列化缓冲区 #13625

已移除的弃用 API

Section titled “已移除的弃用 API”
  • i2c：已弃用的 stop 参数重载和 readv/writev 方法已移除 #14106
  • ESP32 IDF 组件：已弃用的 add_idf_component() 参数已移除 #14105

平台和组件变更

Section titled “平台和组件变更”
  • RP2040 框架：arduino-pico 3.9.4 → 5.5.0，使用 pico-sdk 2.0。关键 API 重命名：padsbank0_hw → pads_bank0_hw，SerialPIO::NOPIN → NOPIN #14328
  • UART flush()：返回类型从 void 更改为 FlushResult。覆盖 flush() 的外部组件必须更新其签名 #14608
  • runtime_image：ImageFormat 枚举从 esphome::online_image 移至 esphome::runtime_image。OnlineImage 构造函数签名已更改 #10212
  • Modbus：rx_full_threshold 哨兵添加到 UARTComponent；非硬件 UART 的超时计算已更改。外部 modbus 组件可能需要更新 #14614

注册和构建变更

Section titled “注册和构建变更”
  • register_component：现在为 protected，运行时检查已移除 #14371
  • register_action：现在需要显式的 synchronous= 参数 #14606
  • build_info_data.h：从 application.h 中移出以修复增量重建 #14230
  • get_loop_priority：使用 USE_LOOP_PRIORITY 条件编译 #14210

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

Release 2026.3.1 - 3月23日

Section titled “Release 2026.3.1 - 3月23日”

Release 2026.3.2 - 4月1日

Section titled “Release 2026.3.2 - 4月1日”

Release 2026.3.3 - 4月7日

Section titled “Release 2026.3.3 - 4月7日”

变更完整列表

Section titled “变更完整列表”

以下列表按标签分组，各部分之间可能包含重复项。

新功能

Section titled “新功能”

新组件

Section titled “新组件”
  • [runtime_image, online_image] Create runtime_image component to decode images esphome#10212 by @kahrendt (new-component)
  • [hdc302x] Add new component esphome#10160 by @joshuasing (new-component) (new-feature) (new-platform)
  • [sen6x] Add SEN6x sensor support esphome#12553 by @mebner86 (new-component) (new-feature) (new-platform)
  • [media_source] Add new Media Source platform component esphome#14417 by @kahrendt (new-component) (new-feature)
  • [audio_file] New component for embedding files into firmware esphome#14434 by @kahrendt (new-component) (new-feature)
  • [nrf52, ota] ble and serial OTA based on mcumgr esphome#11932 by @tomaszduda23 (new-component) (new-feature) (new-platform)
  • [serial_proxy] New component esphome#13944 by @kbx81 (new-component) (new-feature)
  • [rp2040_ble] Add BLE component for RP2040/RP2350 esphome#14603 by @bdraco (new-component) (new-feature)
  • [speaker_source] Add new media player esphome#14649 by @kahrendt (new-component) (new-feature) (new-platform)
  • [dew_point] Add dew_point sensor component esphome#14441 by @CFlix (new-component) (new-feature) (new-platform)

新平台

Section titled “新平台”

破坏性变更

Section titled “破坏性变更”

所有变更

Section titled “所有变更”