Merge pull request #5756 from esphome/bump-2025.12.0b1

2025.12.0b1

Author: swoboda1337

all_automations.json

@@ -136,6 +136,7 @@
     "grove_tb6612fng.run",
     "grove_tb6612fng.standby",
     "grove_tb6612fng.stop",
+    "hc8.calibrate",
     "homeassistant.action",
     "homeassistant.event",
     "homeassistant.service",

content/automations/all_actions.md

@@ -31,6 +31,7 @@ title: ""
 - **fingerprint_grow:** `aura_led_control`, `cancel_enroll`, `delete`, `delete_all`, `enroll`, `led_control`
 - **globals:** `set`
 - **grove_tb6612fng:** `break`, `change_address`, `no_standby`, `run`, `standby`, `stop`
+- **hc8:** `calibrate`
 - **homeassistant:** `event`, `service`, `tag_scanned`
 - **http_request:** `get`, `post`, `send`
 - **htu21d:** `set_heater`, `set_heater_level`

content/changelog/2025.12.0.md

@@ -3,4 +3,4 @@ description: "Changelog"
 title: "Changelog"
 ---
 
-{{< redirect url="/changelog/2025.11.0.html" >}}
+{{< redirect url="/changelog/2025.12.0.html" >}}

content/changelog/_index.md

@@ -169,6 +169,7 @@ Create update entities simplifying management of OTA updates.
 "SPI Bus","components/spi","spi.svg",""
 "TinyUSB","components/tinyusb","usb.svg","dark-invert"
 "UART","components/uart","uart.svg",""
+"USB CDC-ACM","components/usb_cdc_acm","usb.svg","dark-invert"
 "USB Host","components/usb_host","usb.svg","dark-invert"
 "USB UART","components/usb_uart","usb.svg","dark-invert"
 {{< /imgtable >}}
@@ -240,6 +241,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
 "GCJA5","components/sensor/gcja5","gcja5.svg","Particulate","",""
 "GP2Y1010AU0F","components/sensor/gp2y1010au0f","gp2y1010au0f.png","Particulate","",""
 "Grove Multichannel Gas V2","components/sensor/grove_gas_mc_v2","grove-gas-mc-v2.png","NO₂ & CO & Ethanol & Volatile organics","",""
+"HC8","components/sensor/hc8","hc8.png","CO₂","",""
 "HM3301","components/sensor/hm3301","hm3301.jpg","Particulate","",""
 "iAQ-Core","components/sensor/iaqcore","iaqcore.jpg","eCO₂ & Volatile organics","",""
 "MH-Z19","components/sensor/mhz19","mhz19.jpg","CO₂ & Temperature","",""
@@ -291,6 +293,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
 "Mopeka Pro Check LP","components/sensor/mopeka_pro_check","mopeka_pro_check.jpg","Tank level"
 "Mopeka Standard Check LP","components/sensor/mopeka_std_check","mopeka_std_check.jpg","Tank level"
 "RuuviTag","components/sensor/ruuvitag","ruuvitag.jpg","Temperature & Humidity & Accelerometer"
+"ThermoPro BLE","components/sensor/thermopro_ble","thermopro_tp357.jpg","Temperature & Humidity"
 "Xiaomi BLE","components/sensor/xiaomi_ble","xiaomi_mijia_logo.jpg","Various"
 {{< /imgtable >}}
 
@@ -335,6 +338,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
 "Daly BMS","components/sensor/daly_bms","daly_bms.jpg","Voltage & Current & Power"
 "DSMR","components/sensor/dsmr","dsmr.svg","Electrical counter"
 "HLW8012","components/sensor/hlw8012","hlw8012.svg","Voltage & Current & Power"
+"HLW8032","components/sensor/hlw8032","hlw8032.png","Voltage & Current & Power"
 "INA219","components/sensor/ina219","ina219.jpg","DC Current"
 "INA226","components/sensor/ina226","ina226.jpg","DC Current & Power"
 "INA228","components/sensor/ina2xx","ina228.jpg","DC Voltage & Current & Power & Charge"
@@ -380,6 +384,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
 "EMC2101","components/emc2101","emc2101.jpg","Temperature",""
 "ENS160","components/sensor/ens160","ens160.jpg","eCO₂ & Air Quality",""
 "ENS210","components/sensor/ens210","ens210.jpg","Temperature & Humidity",""
+"HC8","components/sensor/hc8","hc8.png","CO₂",""
 "HDC1080","components/sensor/hdc1080","hdc1080.jpg","Temperature & Humidity",""
 "HDC2010","components/sensor/hdc2010","hdc2010.png","Temperature & Humidity",""
 "HHCCJCY10 (MiFlora Pink)","components/sensor/xiaomi_hhccjcy10","xiaomi_hhccjcy10.jpg","Soil moisture & Temperature & Light",""
@@ -416,6 +421,7 @@ Sensors are organized into categories; if a given sensor fits into more than one
 "SHTCx","components/sensor/shtcx","shtc3.jpg","Temperature & Humidity",""
 "SMT100","components/sensor/smt100","smt100.jpg","Moisture & Temperature",""
 "STS3X","components/sensor/sts3x","sts3x.jpg","Temperature",""
+"STTS22H","components/sensor/stts22h","stts22h.jpg","Temperature",""
 "TC74","components/sensor/tc74","tc74.jpg","Temperature",""
 "TEE501","components/sensor/tee501","TEE501.png","Temperature",""
 "TE-M3200","components/sensor/tem3200","tem3200.jpg","Temperature & Pressure",""
@@ -999,6 +1005,7 @@ at the {{< docref "light/fastled" "FastLED Light" >}}.
 
 {{< imgtable >}}
 "Time Core","components/time/index","clock-outline.svg","dark-invert"
+"BM8563 RTC","components/time/bm8563","bm8563.svg",""
 "DS1307 RTC","components/time/ds1307","clock-outline.svg","dark-invert"
 "RX8130 RTC","components/time/rx8130","clock-outline.svg","dark-invert"
 "GPS Time","components/time/gps","crosshairs-gps.svg","dark-invert"
@@ -1037,6 +1044,7 @@ Used for creating infrared (IR) or radio frequency (RF) remote control transmitt
 ESPHome to cellular networks. **Does not encompass Wi-Fi.**
 
 {{< imgtable >}}
+"CC1101","components/cc1101","cc1101.webp",""
 "IR Remote Climate","components/climate/climate_ir","air-conditioner-ir.svg","dark-invert"
 "Remote Receiver","components/remote_receiver","remote.svg","dark-invert"
 "Remote Transmitter","components/remote_transmitter","remote.svg","dark-invert"

content/components/_index.md

@@ -58,7 +58,12 @@ api:
   > The defaults are set to balance memory usage with allowing multiple simultaneous connections.
 
 - **max_send_queue** (*Optional*, int): The maximum number of messages that can be queued for sending per connection before the connection is dropped. Must be between 1 and 64.
-  Defaults to `5` for ESP8266/RP2040, `8` for ESP32/BK72xx/RTL87xx/LN882x, `16` for host platform. This prevents memory exhaustion when a client is slow or network-stalled.
+  Defaults to:
+  - `5` for ESP8266/RP2040,
+  - `8` for ESP32/BK72xx/LN882x/nRF52/RTL87xx,
+  - `16` for host platform.
+  
+  This prevents memory exhaustion when a client is slow or network-stalled.
   Each queued message uses approximately 8-12 bytes of overhead plus the message size.
 
   > [!NOTE]
@@ -385,25 +390,51 @@ api:
     - logger.log: "API client disconnected!"
 ```
 
+## Conditions
+
 {{< anchor "api-connected_condition" >}}
 
-## `api.connected` Condition
+### `api.connected` Condition
+
+This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome native API.
+
+#### Configuration variables
+
+- **state_subscription_only** (*Optional*, boolean): If enabled, only counts clients that have subscribed to entity state updates. This filters out logger-only connections (such as `esphome logs` command), which can cause false positives when waiting for Home Assistant. Defaults to `false`.
 
-This [Condition](/automations/actions#all-conditions) checks if at least one client is connected to the ESPHome
-native API. Please note client not only includes Home Assistant, but also ESPHome's OTA log output
-if logs are shown remotely.
+**Check if any client is connected:**
 
 ```yaml
 on_...:
   if:
     condition:
       api.connected:
     then:
-      - logger.log: API is connected!
+      - logger.log: Client is connected to API!
 ```
 
 The lambda equivalent for this is `id(api_id).is_connected()`.
 
+**Check if a client subscribed to entity states is connected (typically Home Assistant):**
+
+```yaml
+on_boot:
+  - wait_until:
+      condition:
+        api.connected:
+          state_subscription_only: true
+  - logger.log: Home Assistant is connected!
+  - homeassistant.event:
+      event: esphome.device_booted
+```
+
+The lambda equivalent for this is `id(api_id).is_connected(true)`.
+
+**Use Cases:**
+
+- Use `state_subscription_only: false` (default) to detect any API connection
+- Use `state_subscription_only: true` when you need to ensure Home Assistant (or other connections that subscribe to states) is connected before sending events or calling services, preventing errors from logger-only connections
+
 {{< anchor "api-device-actions" >}}
 
 ## User-defined Actions
@@ -412,6 +443,10 @@ It is also possible to get data from Home Assistant to ESPHome with user-defined
 When you declare actions in your ESPHome YAML file, they will automatically show up in
 Home Assistant and you can call them directly.
 
+> [!NOTE]
+> User-defined actions can also send responses back to the calling client using the `api.respond` action.
+> See [Action Responses](#action-responses) for details.
+
 ```yaml
 # Example configuration entry
 api:
@@ -471,6 +506,144 @@ Each of these also exist in array form:
 - bool[]: An array of boolean values. C++ type: `std::vector<bool>`
 - ... - Same for other types.
 
+### Action Responses
+
+User-defined actions can send responses back to the calling client (such as Home Assistant). This enables
+bidirectional communication where actions can report success/error status or return structured JSON data.
+
+#### Response Modes
+
+The response behavior is controlled by the `supports_response` option, which can be set explicitly or
+auto-detected based on your action configuration:
+
+- **none** (default): No response is sent. The action is "fire and forget".
+- **status**: Reports success/error status without data. Auto-detected when `api.respond` is used without `data:`.
+- **optional**: Returns JSON data when the client requests it. Auto-detected when `api.respond` is used with `data:`.
+- **only**: Always returns JSON data. Must be set explicitly. Use this for query-type actions.
+
+#### Configuration variables
+
+- **supports_response** (*Optional*, string): The response mode for this action. One of `none`, `status`,
+  `optional`, or `only`. If not specified, the mode is auto-detected based on `api.respond` usage in the action.
+
+#### Trigger variables
+
+When `supports_response` is not `none`, the following variables are available in the action:
+
+- **call_id** (`uint32_t`): A unique identifier for this action call. Used internally by `api.respond`.
+- **return_response** (`bool`): Only available in `optional` mode. Indicates whether the client requested
+  a response. You don't typically need to check this - `api.respond` handles it automatically.
+
+### `api.respond` Action
+
+This action sends a response back to the client that called the user-defined action. It can report
+success/error status and optionally include JSON data.
+
+#### Configuration variables
+
+- **success** (*Optional*, boolean, [templatable](/automations/templates)): Whether the action succeeded.
+  Defaults to `true`.
+- **error_message** (*Optional*, string, [templatable](/automations/templates)): An error message to include
+  when `success` is `false`. Defaults to an empty string.
+- **data** (*Optional*, [lambda](/automations/templates#config-lambda)): A lambda that populates a JSON object
+  with response data. The lambda receives a `root` variable of type [`JsonObject`](https://arduinojson.org/v7/api/jsonobject/)
+  that you can populate with key-value pairs.
+
+#### Status Response Example
+
+Report success or error without returning data:
+
+```yaml
+api:
+  actions:
+    - action: validate_input
+      variables:
+        value: int
+      then:
+        - if:
+            condition:
+              lambda: 'return value < 0;'
+            then:
+              - api.respond:
+                  success: false
+                  error_message: "Value must be positive"
+            else:
+              - api.respond:
+                  success: true
+```
+
+#### Data Response Example
+
+Return structured JSON data to the caller:
+
+```yaml
+api:
+  actions:
+    - action: get_sensor_data
+      variables:
+        sensor_name: string
+      then:
+        - api.respond:
+            data: !lambda |-
+              root["sensor"] = sensor_name;
+              root["value"] = id(my_sensor).state;
+              root["unit"] = "°C";
+              root["timestamp"] = id(homeassistant_time).now().timestamp;
+```
+
+This action will be auto-detected as `optional` mode because it uses `api.respond` with `data:`.
+
+#### Query Action Example
+
+For actions that always return data (like queries), explicitly set `supports_response: only`:
+
+```yaml
+api:
+  actions:
+    - action: get_device_info
+      supports_response: only
+      then:
+        - api.respond:
+            data: !lambda |-
+              root["hostname"] = App.get_name();
+              root["version"] = ESPHOME_VERSION;
+              root["uptime"] = millis() / 1000;
+```
+
+#### Nested JSON Data
+
+You can create complex nested JSON structures:
+
+```yaml
+api:
+  actions:
+    - action: get_full_status
+      supports_response: only
+      then:
+        - api.respond:
+            data: !lambda |-
+              root["device"]["name"] = "living_room";
+              root["device"]["version"] = 1;
+              root["sensors"]["temperature"] = id(temp_sensor).state;
+              root["sensors"]["humidity"] = id(humidity_sensor).state;
+```
+
+#### Calling from Home Assistant
+
+Actions with response support appear in Home Assistant with their response mode indicated. You can call
+them and receive the response data:
+
+```yaml
+# Home Assistant automation example
+action: esphome.device_get_sensor_data
+data:
+  sensor_name: "living_room"
+response_variable: sensor_response
+```
+
+The response will be available in the `sensor_response` variable with the structure you defined in the
+`data:` lambda.
+
 ## Advantages over MQTT
 
 The ESPHome native API has many advantages over using MQTT for communication with Home

content/components/api.md

@@ -10,6 +10,7 @@ params:
 {{< anchor "esp32-can" >}}
 
 The ESP32 has an integrated CAN controller and therefore doesn't necessarily need an external controller.
+Some variants (ESP32-C5, ESP32-C6, ESP32-P4) have multiple CAN controllers - see [Multiple CAN Controllers](#multiple-can-controllers) below.
 You only need to specify the RX and TX pins. Any GPIO will work.
 
 ```yaml
@@ -39,28 +40,43 @@ canbus:
 
 The following table lists the bit rates supported by the component for ESP32 variants:
 
-| bit_rate          | ESP32 | ESP32-C3 | ESP32-C6 | ESP32-H2 | ESP32-S2 | ESP32-S3 |
-| ----------------- | ----- | -------- | -------- | -------- | -------- | -------- |
-| 1KBPS             |       | x        | x        | x        | x        | x        |
-| 5KBPS             |       | x        | x        | x        | x        | x        |
-| 10KBPS | | x | x | x | x | x |
-| 12K5BPS | | x | x | x | x | x |
-| 16KBPS | | x | x | x | x | x |
-| 20KBPS | | x | x | x | x | x |
-| 25KBPS | x | x | x | x | x | x |
-| 31K25BPS | | | | | | |
-| 33KBPS | | | | | | |
-| 40KBPS | | | | | | |
-| 50KBPS | x | x | x | x | x | x |
-| 80KBPS | | | | | | |
-| 83K38BPS | | | | | | |
-| 95KBPS | | | | | | |
-| 100KBPS | x | x | x | x | x | x |
-| 125KBPS (Default) | x | x | x | x | x | x |
-| 250KBPS | x | x | x | x | x | x |
-| 500KBPS | x | x | x | x | x | x |
-| 800KBPS | x | x | x | x | x | x |
-| 1000KBPS | x | x | x | x | x | x |
+| bit_rate          | ESP32 | Other variants* |
+| ----------------- | ----- | --------------- |
+| 1KBPS             |       | x               |
+| 5KBPS             |       | x               |
+| 10KBPS            |       | x               |
+| 12K5BPS           |       | x               |
+| 16KBPS            |       | x               |
+| 20KBPS            |       | x               |
+| 25KBPS            | x     | x               |
+| 31K25BPS          |       |                 |
+| 33KBPS            |       |                 |
+| 40KBPS            |       |                 |
+| 50KBPS            | x     | x               |
+| 80KBPS            |       |                 |
+| 83K3BPS           |       |                 |
+| 95KBPS            |       |                 |
+| 100KBPS           | x     | x               |
+| 125KBPS (Default) | x     | x               |
+| 250KBPS           | x     | x               |
+| 500KBPS           | x     | x               |
+| 800KBPS           | x     | x               |
+| 1000KBPS          | x     | x               |
+
+Other variants: ESP32-C3, ESP32-C5, ESP32-C6, ESP32-H2, ESP32-P4, ESP32-S2, ESP32-S3
+
+> [!NOTE]
+> ESP32-C2 and ESP32-C61 do not have TWAI/CAN hardware and are not supported.
+
+## Multiple CAN Controllers
+
+Some ESP32 variants have multiple CAN (TWAI) controllers:
+
+- **ESP32-C5**: 2 controllers
+- **ESP32-C6**: 2 controllers
+- **ESP32-P4**: 3 controllers
+
+All other supported variants have a single controller. ESP32-C2 and ESP32-C61 do not have CAN hardware.
 
 ## Wiring options