ESPHome 2025.12.0 - December 2025

Edit this page on GitHub

ESPHome 2025.12.0 - December 2025

BM8​5​6​3​ ​RTC
CC1​1​0​1​
HC8​
HLW8​0​3​2​
HUB7​5​
STTS2​2​H
ThermoPro ​BLE
USB ​CDC-​ACM

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).

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.

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).

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)
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 component brings native support for HUB75 LED matrix panels, enabling large-format LED displays for information dashboards, signage, and creative projects (#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
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 component adds support for the Texas Instruments CC1101 Sub-1GHz transceiver, enabling 433MHz remote control integration and other sub-GHz wireless applications (#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
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 component enables USB virtual serial port functionality on ESP32-S2 and ESP32-S3 devices (#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).

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)
  • AP active condition - New wifi.ap_active condition for automation triggers (#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).

Key Benefits:

  • Z-Wave Proxy performance - Reduces latency by ~10ms, bringing wired Ethernet performance within milliseconds of direct USB/serial connection (#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).

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)
  • ~1.5KB additional IRAM savings - Ring buffer functions moved to flash (#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)

Text Sensor Optimization:

  • 24-32 bytes per text sensor - Eliminated duplicate string storage when no filters configured (#12205)

Dashboard Import Optimization:

  • ~20 bytes per device - Package import URL now stored as pointer to flash instead of heap-allocated string (#11951)

New Hardware Support

This release adds support for 8 new components and numerous display models:

New Sensor Components:

New Time Component:

New Display Models:

  • Waveshare 4.26" e-paper with SSD1677 controller (#11887)
  • Waveshare S3 LCD 3.16" (#12309)
  • Guition JC4827W543 480x272 display (#12034)
  • Guition JC4880P443 480x800 MIPI DSI display (#12068)
  • M5Stack Core2 display (#12301)

Platform Enhancements:

  • ESP32-C5 PSRAM support with quad mode and speeds up to 120MHz (#12215)
  • Seeed XIAO ESP32-C6 board definition (#12307)
  • Remote transmitter/receiver support for RP2040 (#12048)
  • nRF52 DC-DC converter settings (#11841)

LVGL Improvements

Multiple enhancements improve the LVGL experience:

  • Direct button text - Set text: directly on buttons without nested label widgets (#11964)
  • Auto row/column padding - pad_all now applies to inter-row/column spacing in flex layouts (#11879)
  • Display sync option - New update_when_display_idle option syncs LVGL updates with display refresh (#11896)
  • Enhanced arc widget - More arc parameters available in update actions (#12066)
  • Scroll properties - Added missing scroll-related configuration options (#11901)

Climate and Component Enhancements

Gree Climate:

  • New turbo, light, health, and xfan switches for supported models (#12160)

Climate IR:

  • Optional humidity sensor support (#9805)

SPS30 Particulate Sensor:

  • Idle mode functionality to extend sensor life and reduce power consumption (#12255)

PCA9685 PWM:

  • Phase balancer option to fix LED flickering during animations (#9792)

Prometheus:

  • Event and text component metrics support (#10240)

MCP3204 ADC:

  • Differential mode measurement support (#7436)

Developer Features

IDF Component Improvements:

  • Shorthand syntax for ESP-IDF components like espressif/esp_hosted^2.6.6 (#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)
  • New measurement_angle state class for angle sensors (#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

  • 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

  • Micronova: Custom button and sensor entities now require explicit memory_location and address configuration - the misleading default values have been removed. #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

  • 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

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

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

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

  • 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

  • TextSensor::raw_state: Changed from public member to protected raw_state_. Use get_raw_state() method instead of direct member access. #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

  • Micronova: MicroNovaFunctions enum removed - value interpretation now determined at compile time. The get_set_fan_speed_offset() public method removed from sensor entity. #12363

For detailed migration guides and API documentation, see the ESPHome Developers Documentation.

Full list of changes

New Features

New Components

New Platforms

Breaking Changes

  • [core] Deprecate unsafe const char* APIs in mark_failed() and status_set_error(), add LogString* overloads esphome#12021 by @bdraco (breaking-change)
  • [wifi_info] Use callbacks instead of polling esphome#10748 by @kbx81 (breaking-change)
  • [esp32_ble_client] Replace std::string with char[18] for BLE address storage esphome#12070 by @bdraco (breaking-change)
  • [prometheus] Avoid generating unused light color metrics to reduce memory usage on ESP8266 esphome#9530 by @pgolawsk (breaking-change)
  • [text_sensor] Avoid duplicate string storage when no filters configured esphome#12205 by @bdraco (breaking-change)
  • [micronova] Set update_interval on entities instead on hub esphome#12226 by @edenhaus (breaking-change)
  • [micronova] Set the write bit automatically esphome#12318 by @edenhaus (breaking-change)
  • [i2c] Fix port logic with ESP-IDF esphome#12063 by @arno1801 (breaking-change)
  • [micronova] Remove MicroNovaFunctions esphome#12363 by @edenhaus (breaking-change)
  • [micronova] Require memory location and address for custom entities esphome#12371 by @edenhaus (breaking-change)

All changes

All Changelogs

ESPHome 2025.12.0 - December 2025

Edit this page on GitHub