From fb6072f213b4d768a8e763e4455efe396b191738 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Wed, 10 Dec 2025 04:53:54 +0100 Subject: [PATCH 1/5] Generate 2025.12.0 Release Notes --- content/changelog/2025.12.0.md | 279 +++++++++++++++++++++++++++++++++ 1 file changed, 279 insertions(+) diff --git a/content/changelog/2025.12.0.md b/content/changelog/2025.12.0.md index 89e2c48391..d931b53a8e 100644 --- a/content/changelog/2025.12.0.md +++ b/content/changelog/2025.12.0.md @@ -20,6 +20,285 @@ params: ## Release Overview + +ESPHome 2025.12.0 introduces API action responses for bidirectional communication with Home Assistant, conditional package inclusion for dynamic configurations, and HUB75 LED matrix display support. This release delivers significant memory optimizations saving up to 10KB of IRAM on ESP32 devices, eliminates socket latency on ESP8266, and adds 8 new components including the CC1101 sub-GHz transceiver and USB CDC-ACM support. LVGL receives multiple usability improvements, and the WiFi component has been refactored for instant callback-based updates across all platforms. + + + +## API Action Responses + +ESPHome actions can now send structured responses back to clients like Home Assistant, enabling true bidirectional communication where actions return success/error status and JSON data payloads ([#12136](https://github.com/esphome/esphome/pull/12136)). + +**Key Features:** + +- **Status responses** - Report success or failure with optional error messages +- **Data responses** - Return structured JSON data from actions using ArduinoJson +- **Auto-detection** - Response mode automatically detected based on `api.respond` usage +- **Three modes** - `none` (fire and forget), `status` (success/error only), or `optional`/`only` (with data) + +This unlocks new use cases like query-type actions that return device configuration, sensor readings, or diagnostic information directly to Home Assistant. + +```yaml +api: + actions: + - action: get_sensor_reading + variables: + sensor_name: string + then: + - api.respond: + data: !lambda |- + root["sensor"] = sensor_name; + root["value"] = 42.5; + root["unit"] = "°C"; +``` + +## Conditional Package Inclusion + +The configuration system now supports conditional package inclusion, a long-awaited feature that enables dynamic configuration based on substitution variables ([#11605](https://github.com/esphome/esphome/pull/11605)). + +**Key Features:** + +- **Conditional imports** - Include packages based on boolean conditions using Jinja2 expressions +- **Package merging after substitutions** - Packages are now merged after substitution resolution, enabling generated components to merge correctly with manually defined ones +- **LVGL extend support** - The `!extend` and `!remove` directives now work with LVGL-style configurations ([#11534](https://github.com/esphome/esphome/pull/11534)) + +```yaml +substitutions: + network_package: !include network.yaml + network_enabled: true + +packages: + - ${ network_enabled and network_package or {} } +``` + +This enables creating reusable configuration templates that adapt to different hardware variants or deployment scenarios. + +## HUB75 LED Matrix Display Support + +The new [hub75](/components/hub75) component brings native support for HUB75 LED matrix panels, enabling large-format LED displays for information dashboards, signage, and creative projects ([#11153](https://github.com/esphome/esphome/pull/11153)). + +**Key Features:** + +- **Multiple ESP32 variants** - Supports ESP32 (I2S), ESP32-S3 (LCD CAM + GDMA), and ESP32-P4 (PARLIO) +- **Flexible configuration** - Configurable panel dimensions, clock speed, and pin assignments +- **LVGL compatible** - Works seamlessly with LVGL for rich graphical interfaces +- **Board presets** - Pre-configured settings for popular boards like Apollo Automation M1 + +```yaml +display: + - platform: hub75 + id: matrix + panel_width: 64 + panel_height: 64 + clock_speed: 20MHz + r1_pin: 1 + g1_pin: 5 + # ... additional pins +``` + +## CC1101 Sub-1GHz Transceiver + +The new [cc1101](/components/cc1101) component adds support for the Texas Instruments CC1101 Sub-1GHz transceiver, enabling 433MHz remote control integration and other sub-GHz wireless applications ([#11849](https://github.com/esphome/esphome/pull/11849)). + +**Key Features:** + +- **433.92MHz support** - Perfect for integrating 433MHz remotes and sensors +- **ASK/OOK modulation** - Works with common remote control protocols +- **Core integration** - Designed to work with `remote_receiver` and `remote_transmitter` components +- **Robust initialization** - Non-blocking state machine with proper chip reset handling + +```yaml +cc1101: + id: cc1101_transceiver + cs_pin: GPIO5 + gdo0_pin: GPIO4 + tuner: + frequency: 433.92MHz + modulation: ASK/OOK + bandwidth: 203kHz + symbol_rate: 5000 +``` + +## USB CDC-ACM Support + +The new [usb_cdc_acm](/components/usb_cdc_acm) component enables USB virtual serial port functionality on ESP32-S2 and ESP32-S3 devices ([#11687](https://github.com/esphome/esphome/pull/11687)). + +**Key Features:** + +- **Multi-interface support** - Up to 2 independent CDC-ACM interfaces per device +- **Configurable buffers** - Adjustable RX/TX ring buffer sizes +- **Line state callbacks** - Notifications for DTR, RTS, baud rate, and other line coding changes +- **Bridge-ready** - Designed to connect USB serial interfaces to UART or other serial interfaces + +## WiFi Info Callback Architecture + +The WiFi component has been refactored from polling-based updates to event-driven callbacks, significantly improving responsiveness ([#10748](https://github.com/esphome/esphome/pull/10748)). + +**Key Features:** + +- **Immediate updates** - WiFi info sensors now update instantly when state changes instead of waiting for poll intervals +- **Reduced overhead** - Eliminates continuous polling in wifi_info sensors +- **Platform consistency** - All platforms (ESP8266, ESP32, LibreTiny, Pico W) now use the same callback infrastructure +- **New power save mode sensor** - Reports current WiFi power save mode ([#11480](https://github.com/esphome/esphome/pull/11480)) +- **AP active condition** - New `wifi.ap_active` condition for automation triggers ([#11852](https://github.com/esphome/esphome/pull/11852)) + +## ESP8266 Socket Latency Elimination + +ESP8266 devices now respond to network requests with the same speed as ESP32 devices ([#12397](https://github.com/esphome/esphome/pull/12397)). + +**The Problem:** + +ESP8266 used polling for socket data, sleeping up to 16ms before discovering incoming data. This affected every API request and Home Assistant command. + +**The Solution:** + +The loop now wakes within microseconds of data arriving using ESP8266's `esp_schedule()` mechanism, matching ESP32 and LibreTiny behavior. This is automatic for all ESP8266 devices with no configuration needed. + +## Memory and IRAM Optimizations + +This release includes substantial memory optimizations, particularly for ESP32 devices using ESP-IDF: + +**FreeRTOS and Ring Buffer Flash Placement:** + +- **~8KB IRAM savings** - FreeRTOS functions moved to flash by default ([#12182](https://github.com/esphome/esphome/pull/12182)) +- **~1.5KB additional IRAM savings** - Ring buffer functions moved to flash ([#12184](https://github.com/esphome/esphome/pull/12184)) +- **Escape hatches** - Use `freertos_in_iram: true` or `ringbuf_in_iram: true` if issues occur + +These changes prepare ESPHome for ESP-IDF 6.0 where flash placement becomes the default. + +**BLE Client Memory Reduction:** + +- **24-40 bytes per BLE client** - Replaced `std::string` with fixed `char[18]` for MAC address storage ([#12070](https://github.com/esphome/esphome/pull/12070)) + +**Text Sensor Optimization:** + +- **24-32 bytes per text sensor** - Eliminated duplicate string storage when no filters configured ([#12205](https://github.com/esphome/esphome/pull/12205)) + +## New Hardware Support + +This release adds support for 8 new components and numerous display models: + +**New Sensor Components:** + +- [hlw8032](/components/sensor/hlw8032) - Single-phase power metering IC ([#7241](https://github.com/esphome/esphome/pull/7241)) +- [stts22h](/components/sensor/stts22h) - High-accuracy temperature sensor ([#11778](https://github.com/esphome/esphome/pull/11778)) +- [thermopro_ble](/components/sensor/thermopro_ble) - ThermoPro BLE temperature/humidity sensors ([#11835](https://github.com/esphome/esphome/pull/11835)) +- [hc8](/components/sensor/hc8) - HC8 CO2 sensor ([#11872](https://github.com/esphome/esphome/pull/11872)) + +**New Time Component:** + +- [bm8563](/components/time/bm8563) - BM8563 I2C RTC ([#11616](https://github.com/esphome/esphome/pull/11616)) + +**New Display Models:** + +- Waveshare 4.26" e-paper with SSD1677 controller ([#11887](https://github.com/esphome/esphome/pull/11887)) +- Waveshare S3 LCD 3.16" ([#12309](https://github.com/esphome/esphome/pull/12309)) +- 7.3" Spectra E6 e-paper ([#12001](https://github.com/esphome/esphome/pull/12001)) +- Guition JC4827W543 480x272 display ([#12034](https://github.com/esphome/esphome/pull/12034)) +- Guition JC4880P443 480x800 MIPI DSI display ([#12068](https://github.com/esphome/esphome/pull/12068)) +- M5Stack Core2 display ([#12301](https://github.com/esphome/esphome/pull/12301)) + +**Platform Enhancements:** + +- ESP32-C5 PSRAM support with quad mode and speeds up to 120MHz ([#12215](https://github.com/esphome/esphome/pull/12215)) +- Seeed XIAO ESP32-C6 board definition ([#12307](https://github.com/esphome/esphome/pull/12307)) +- Remote transmitter/receiver support for RP2040 ([#12048](https://github.com/esphome/esphome/pull/12048)) +- nRF52 DC-DC converter settings ([#11841](https://github.com/esphome/esphome/pull/11841)) + +## LVGL Improvements + +Multiple enhancements improve the LVGL experience: + +- **Direct button text** - Set `text:` directly on buttons without nested label widgets ([#11964](https://github.com/esphome/esphome/pull/11964)) +- **Auto row/column padding** - `pad_all` now applies to inter-row/column spacing in flex layouts ([#11879](https://github.com/esphome/esphome/pull/11879)) +- **Display sync option** - New `update_when_display_idle` option syncs LVGL updates with display refresh ([#11896](https://github.com/esphome/esphome/pull/11896)) +- **Enhanced arc widget** - More arc parameters available in update actions ([#12066](https://github.com/esphome/esphome/pull/12066)) +- **Multiple widgets per grid cell** - New `multiple_widgets_per_cell` option for grid layouts ([#12091](https://github.com/esphome/esphome/pull/12091)) +- **Scroll properties** - Added missing scroll-related configuration options ([#11901](https://github.com/esphome/esphome/pull/11901)) + +## Climate and Component Enhancements + +**Gree Climate:** + +- New `turbo`, `light`, `health`, and `xfan` switches for supported models ([#12160](https://github.com/esphome/esphome/pull/12160)) + +**Climate IR:** + +- Optional humidity sensor support ([#9805](https://github.com/esphome/esphome/pull/9805)) + +**SPS30 Particulate Sensor:** + +- Idle mode functionality to extend sensor life and reduce power consumption ([#12255](https://github.com/esphome/esphome/pull/12255)) + +**PCA9685 PWM:** + +- Phase balancer option to fix LED flickering during animations ([#9792](https://github.com/esphome/esphome/pull/9792)) + +**Prometheus:** + +- Event and text component metrics support ([#10240](https://github.com/esphome/esphome/pull/10240)) + +**MCP3204 ADC:** + +- Differential mode measurement support ([#7436](https://github.com/esphome/esphome/pull/7436)) + +## Developer Features + +**Environment Variables:** + +- New `environment_variables` option in esphome config for proxy settings and PlatformIO configuration ([#11953](https://github.com/esphome/esphome/pull/11953)) + +**IDF Component Improvements:** + +- Shorthand syntax for ESP-IDF components like `espressif/esp_hosted^2.6.6` ([#12127](https://github.com/esphome/esphome/pull/12127)) +- YAML can now override component versions defined in code + +**API Enhancements:** + +- `state_subscription_only` flag for reliable API connection detection without logger false positives ([#11906](https://github.com/esphome/esphome/pull/11906)) +- New `measurement_angle` state class for angle sensors ([#12085](https://github.com/esphome/esphome/pull/12085)) + + +## Breaking Changes + + +### Component Changes + +- **Micronova**: The `update_interval` configuration has moved from the hub to individual entities, allowing different update intervals per sensor. Remove `update_interval` from the `micronova:` hub section and add it to each sensor/text_sensor entity instead. [#12226](https://github.com/esphome/esphome/pull/12226) + +- **Micronova**: The `memory_location` configuration is now restricted to read memory locations (0x00-0x79). If you have values above 0x79, subtract 0x80 (e.g., 0x80 becomes 0x00, 0xA0 becomes 0x20). The `memory_write_location` option on number entities has been removed as it's now calculated automatically. [#12318](https://github.com/esphome/esphome/pull/12318) + +- **Micronova**: Custom button and sensor entities now require explicit `memory_location` and `address` configuration - the misleading default values have been removed. [#12371](https://github.com/esphome/esphome/pull/12371) + +- **Prometheus**: Light color metrics (`light_color_*`) are now only generated if the light component supports those color modes. This reduces memory usage on ESP8266 but may affect monitoring setups that expected all metrics regardless of light capabilities. [#9530](https://github.com/esphome/esphome/pull/9530) + +- **Text Sensor**: The public `raw_state` member has been removed. If you access `.raw_state` directly in a lambda, update to use `.get_raw_state()` instead. [#12205](https://github.com/esphome/esphome/pull/12205) + +### Platform Changes + +- **I2C on ESP32-C5/C6/P4**: Fixed I2C port logic for chips with Low Power (LP) I2C ports. Users with multiple I2C buses on these chips may need to verify their port assignments. [#12063](https://github.com/esphome/esphome/pull/12063) + +### Behavior Changes + +- **WiFi Info**: Text sensors now use callback-based updates instead of polling. Updates happen immediately when WiFi state changes rather than on fixed intervals. This improves responsiveness but may change timing behavior if your automations depended on the polling interval. [#10748](https://github.com/esphome/esphome/pull/10748) + + +### Breaking Changes for Developers + + +- **Component::mark_failed() and status_set_error()**: The `const char*` overloads are deprecated and will be removed in 2026.6.0. Use `LOG_STR()` instead: `this->mark_failed(LOG_STR("Error message"))`. This fixes dangling pointer bugs when passing temporary strings. [#12021](https://github.com/esphome/esphome/pull/12021) + +- **BLEClientBase::address_str()**: Return type changed from `const std::string&` to `const char*`. Remove `.c_str()` calls: `client->address_str()` instead of `client->address_str().c_str()`. [#12070](https://github.com/esphome/esphome/pull/12070) + +- **TextSensor::raw_state**: Changed from public member to protected `raw_state_`. Use `get_raw_state()` method instead of direct member access. [#12205](https://github.com/esphome/esphome/pull/12205) + +- **WiFi component callbacks**: New callback architecture with `wifi_connect_state_callback_`, `ip_state_callback_`, and `wifi_scan_state_callback_`. Automation triggers moved to `automation.h`. [#10748](https://github.com/esphome/esphome/pull/10748) + +- **Micronova**: `MicroNovaFunctions` enum removed - value interpretation now determined at compile time. The `get_set_fan_speed_offset()` public method removed from sensor entity. [#12363](https://github.com/esphome/esphome/pull/12363) + +For detailed migration guides and API documentation, see the [ESPHome Developers Documentation](https://developers.esphome.io/). + + ## Full list of changes From d39154770bb3ae64fc982ac7b15ff26385526a9c Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Wed, 10 Dec 2025 04:57:49 +0100 Subject: [PATCH 2/5] Generate 2025.12.0 Release Notes --- content/changelog/2025.12.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/changelog/2025.12.0.md b/content/changelog/2025.12.0.md index d931b53a8e..4d9b4283ef 100644 --- a/content/changelog/2025.12.0.md +++ b/content/changelog/2025.12.0.md @@ -75,7 +75,7 @@ This enables creating reusable configuration templates that adapt to different h ## HUB75 LED Matrix Display Support -The new [hub75](/components/hub75) component brings native support for HUB75 LED matrix panels, enabling large-format LED displays for information dashboards, signage, and creative projects ([#11153](https://github.com/esphome/esphome/pull/11153)). +The new [hub75](/components/display/hub75) component brings native support for HUB75 LED matrix panels, enabling large-format LED displays for information dashboards, signage, and creative projects ([#11153](https://github.com/esphome/esphome/pull/11153)). **Key Features:** From 336c7aa684f1f0c5ab2eff6cf204676c7af3915b Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Wed, 10 Dec 2025 05:11:26 +0100 Subject: [PATCH 3/5] fix --- content/changelog/2025.12.0.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/content/changelog/2025.12.0.md b/content/changelog/2025.12.0.md index 4d9b4283ef..f529727942 100644 --- a/content/changelog/2025.12.0.md +++ b/content/changelog/2025.12.0.md @@ -142,6 +142,16 @@ The WiFi component has been refactored from polling-based updates to event-drive - **New power save mode sensor** - Reports current WiFi power save mode ([#11480](https://github.com/esphome/esphome/pull/11480)) - **AP active condition** - New `wifi.ap_active` condition for automation triggers ([#11852](https://github.com/esphome/esphome/pull/11852)) +## Low Latency UART Processing + +The UART component now supports a `wake_loop_on_rx` flag that wakes the main loop immediately when data arrives, enabling near-real-time serial processing ([#12172](https://github.com/esphome/esphome/pull/12172)). + +**Key Benefits:** + +- **Z-Wave Proxy performance** - Reduces latency by ~10ms, bringing wired Ethernet performance within milliseconds of direct USB/serial connection ([#12135](https://github.com/esphome/esphome/pull/12135)) +- **Real-time serial applications** - Any component requiring fast response to incoming serial data can now achieve sub-millisecond wake times +- **Automatic infrastructure** - The socket wake infrastructure is automatically enabled when any UART requests RX wake + ## ESP8266 Socket Latency Elimination ESP8266 devices now respond to network requests with the same speed as ESP32 devices ([#12397](https://github.com/esphome/esphome/pull/12397)). @@ -174,6 +184,10 @@ These changes prepare ESPHome for ESP-IDF 6.0 where flash placement becomes the - **24-32 bytes per text sensor** - Eliminated duplicate string storage when no filters configured ([#12205](https://github.com/esphome/esphome/pull/12205)) +**Dashboard Import Optimization:** + +- **~20 bytes per device** - Package import URL now stored as pointer to flash instead of heap-allocated string ([#11951](https://github.com/esphome/esphome/pull/11951)) + ## New Hardware Support This release adds support for 8 new components and numerous display models: @@ -244,10 +258,6 @@ Multiple enhancements improve the LVGL experience: ## Developer Features -**Environment Variables:** - -- New `environment_variables` option in esphome config for proxy settings and PlatformIO configuration ([#11953](https://github.com/esphome/esphome/pull/11953)) - **IDF Component Improvements:** - Shorthand syntax for ESP-IDF components like `espressif/esp_hosted^2.6.6` ([#12127](https://github.com/esphome/esphome/pull/12127)) From 2a7bebd7f8d80ad388eae6981c5a641ab9cdd089 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Wed, 10 Dec 2025 05:31:34 +0100 Subject: [PATCH 4/5] remove prs not actually in 2025.12.0 --- content/changelog/2025.12.0.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/content/changelog/2025.12.0.md b/content/changelog/2025.12.0.md index f529727942..7b23a300e5 100644 --- a/content/changelog/2025.12.0.md +++ b/content/changelog/2025.12.0.md @@ -207,7 +207,6 @@ This release adds support for 8 new components and numerous display models: - Waveshare 4.26" e-paper with SSD1677 controller ([#11887](https://github.com/esphome/esphome/pull/11887)) - Waveshare S3 LCD 3.16" ([#12309](https://github.com/esphome/esphome/pull/12309)) -- 7.3" Spectra E6 e-paper ([#12001](https://github.com/esphome/esphome/pull/12001)) - Guition JC4827W543 480x272 display ([#12034](https://github.com/esphome/esphome/pull/12034)) - Guition JC4880P443 480x800 MIPI DSI display ([#12068](https://github.com/esphome/esphome/pull/12068)) - M5Stack Core2 display ([#12301](https://github.com/esphome/esphome/pull/12301)) @@ -227,7 +226,6 @@ Multiple enhancements improve the LVGL experience: - **Auto row/column padding** - `pad_all` now applies to inter-row/column spacing in flex layouts ([#11879](https://github.com/esphome/esphome/pull/11879)) - **Display sync option** - New `update_when_display_idle` option syncs LVGL updates with display refresh ([#11896](https://github.com/esphome/esphome/pull/11896)) - **Enhanced arc widget** - More arc parameters available in update actions ([#12066](https://github.com/esphome/esphome/pull/12066)) -- **Multiple widgets per grid cell** - New `multiple_widgets_per_cell` option for grid layouts ([#12091](https://github.com/esphome/esphome/pull/12091)) - **Scroll properties** - Added missing scroll-related configuration options ([#11901](https://github.com/esphome/esphome/pull/11901)) ## Climate and Component Enhancements From bf3505fa5014a3b24ad17fe23cd4345c36a75066 Mon Sep 17 00:00:00 2001 From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com> Date: Wed, 10 Dec 2025 11:01:28 -0500 Subject: [PATCH 5/5] Update content/changelog/2025.12.0.md --- content/changelog/2025.12.0.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/content/changelog/2025.12.0.md b/content/changelog/2025.12.0.md index 7b23a300e5..c4e473cdb8 100644 --- a/content/changelog/2025.12.0.md +++ b/content/changelog/2025.12.0.md @@ -111,12 +111,10 @@ The new [cc1101](/components/cc1101) component adds support for the Texas Instru cc1101: id: cc1101_transceiver cs_pin: GPIO5 - gdo0_pin: GPIO4 - tuner: - frequency: 433.92MHz - modulation: ASK/OOK - bandwidth: 203kHz - symbol_rate: 5000 + frequency: 433.92MHz + modulation: ASK/OOK + bandwidth: 203kHz + symbol_rate: 5000 ``` ## USB CDC-ACM Support