Skip to content
Get started

ESPHome 2025.12.0: API action responses and HUB75 matrix displays

ESPHome 2025.12.0: API action responses and HUB75 matrix displays
Jesse Hills
Jesse Hills
ESPHome Developer
BM8​5​6​3​ ​RTC
CC1​1​0​1​
HC8​
HLW8​0​3​2​
HUB7​5​ ​LED ​Matrix
STTS2​2​H
ThermoPro ​BLE
USB ​CDC-​ACM

Release Overview

Section titled “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 per-packet heap allocations in API connections and 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

Section titled “API Action Responses”

The Native API now supports actions that send structured responses back to clients like Home Assistant, enabling true bidirectional communication where actions return success/error status and JSON data payloads (esphome#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

Section titled “Conditional Package Inclusion”

The packages system now supports conditional inclusion, a long-awaited feature that enables dynamic configuration based on substitution variables (esphome#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 (esphome#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

Section titled “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 (esphome#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

CC1101 Sub-1GHz Transceiver

Section titled “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 (esphome#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

USB CDC-ACM Support

Section titled “USB CDC-ACM Support”

The new usb_cdc_acm component enables USB virtual serial port functionality on ESP32-S2 and ESP32-S3 devices (esphome#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

Section titled “WiFi Info Callback Architecture”

The WiFi component has been refactored from polling-based updates to event-driven callbacks, significantly improving responsiveness (esphome#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 (esphome#11480)
  • AP active condition - New wifi.ap_active condition for automation triggers (esphome#11852)

Low Latency UART Processing

Section titled “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 (esphome#12172).

Key Benefits:

  • Z-Wave Proxy performance - Reduces latency by ~10ms for WiFi-connected ZWA-2 devices, building on the USB-connected Ethernet/PoE optimizations from 2025.11.0 (esphome#12135)
  • Real-time serial applications - Any component requiring fast response to incoming serial data can now achieve sub-millisecond wake times by enabling this flag in their code
  • Automatic infrastructure - The socket wake infrastructure is automatically enabled when any UART requests RX wake

ESP8266 Socket Latency Elimination

Section titled “ESP8266 Socket Latency Elimination”

ESP8266 previously had higher network latency than ESP32 and LibreTiny because it used polling for socket data, sleeping up to 16ms before discovering incoming data. This affected every API request and Home Assistant command. The loop now wakes within microseconds of data arriving using ESP8266’s esp_schedule() mechanism, bringing ESP8266 to near parity with ESP32 and LibreTiny. This is automatic for all ESP8266 devices with no configuration needed (esphome#12397).

Memory and IRAM Optimizations

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

Text Sensor Optimization:

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

Dashboard Import Optimization:

  • Eliminates URL heap allocation:
    • Package import URL is now stored as a pointer to .rodata instead of a heap-allocated std::string.
    • On ESP32, .rodata resides in flash, providing RAM savings.
    • On ESP8266, .rodata is in RAM, but this still avoids heap overhead.
    • (esphome#11951)

API Connection Optimizations:

The API connection layer received significant optimizations to reduce heap fragmentation and memory churn:

  • Eliminated per-packet heap allocation - Previously every API packet received required a new heap allocation. The receive buffer is now reused across packets, with excess capacity released after initial sync completes. This reduces heap fragmentation on busy devices. For quiet devices, the initial sync memory spike is released rather than held for the lifetime of the connection. (Connections can last for months.) (esphome#12133)
  • Zero-copy API commands - Select and light effect commands now process strings directly from protobuf buffer without heap allocation (esphome#12329, esphome#12384)
  • Flash storage for device info - Device info strings stored in flash on ESP8266 (esphome#12173)
  • Flash storage for state subscriptions - Home Assistant state subscriptions stored in flash instead of heap (esphome#12008)
  • Reduced service call storage - Home Assistant service call strings use less heap (esphome#12151)
  • APINoiseContext optimization - Removed shared_ptr overhead (esphome#11981)
  • Loop-based reboot timeout - Avoids scheduler heap churn (esphome#12291)

Sensor Timeout Filter Optimization:

  • Eliminates scheduler heap churn - Timeout filters now use a loop-based implementation instead of scheduler timeouts. This is particularly important for LD2410/LD2420/LD2450 users with many timeout filters, where the old implementation caused ~70 heap operations/second and constant scheduler pool exhaustion when someone was in range of the sensor (esphome#11922)

New Hardware Support

Section titled “New Hardware Support”

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

New Sensor Components:

New Time Component:

New Display Models:

Platform Enhancements:

LVGL Improvements

Section titled “LVGL Improvements”

Multiple enhancements improve the LVGL experience:

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

Component Enhancements

Section titled “Component Enhancements”

Gree Climate:

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

Climate IR:

SPS30 Particulate Sensor:

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

PCA9685 PWM:

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

Prometheus:

MCP3204 ADC:

Developer Features

Section titled “Developer Features”

IDF Component Improvements:

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

Breaking Changes

Section titled “Breaking Changes”

Component Changes

Section titled “Component Changes”

  • Micronova: Multiple configuration changes (esphome#12226, esphome#12318, esphome#12371):

    • update_interval moved from hub to individual entities - remove from micronova: section and add to each sensor/text_sensor
    • memory_location now restricted to read locations (0x00-0x79) - subtract 0x80 from values above 0x79
    • memory_write_location removed from number entities (now calculated automatically)
    • Custom button/sensor entities now require explicit memory_location and address configuration

  • 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. esphome#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. esphome#12205

Platform Changes

Section titled “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. esphome#12063

Behavior Changes

Section titled “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. esphome#10748

Breaking Changes for Developers

Section titled “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. esphome#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(). esphome#12070

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

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

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

Release 2025.12.1 - December 19

Section titled “Release 2025.12.1 - December 19”

Release 2025.12.2 - December 23

Section titled “Release 2025.12.2 - December 23”

Release 2025.12.3 - December 30

Section titled “Release 2025.12.3 - December 30”

Release 2025.12.4 - December 31

Section titled “Release 2025.12.4 - December 31”

Release 2025.12.5 - January 6

Section titled “Release 2025.12.5 - January 6”

Release 2025.12.6 - January 13

Section titled “Release 2025.12.6 - January 13”

Release 2025.12.7 - January 16

Section titled “Release 2025.12.7 - January 16”

Full List of Changes

Section titled “Full List of Changes”

For the complete list of every merged pull request in this release, see the full 2025.12.0 changelog.

Tags:

Comments