Add release notes for 2025.12.0

content/changelog/2025.12.0.md

@@ -20,6 +20,291 @@ params:
 
 ## Release Overview
 
+<!-- RELEASE_OVERVIEW_START -->
+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.
+<!-- RELEASE_OVERVIEW_END -->
+
+<!-- FEATURE_HIGHLIGHTS_START -->
+## 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/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:**
+
+- **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
+  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))
+
+## 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)).
+
+**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))
+
+**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:
+
+**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))
+- 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))
+- **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
+
+**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))
+<!-- FEATURE_HIGHLIGHTS_END -->
+
+## Breaking Changes
+
+<!-- BREAKING_CHANGES_USERS_START -->
+### 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_USERS_END -->
+
+### Breaking Changes for Developers
+
+<!-- BREAKING_CHANGES_DEVELOPERS_START -->
+- **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/).
+<!-- BREAKING_CHANGES_DEVELOPERS_END -->
+
 <!-- markdownlint-disable MD013 -->
 
 ## Full list of changes