Merge branch 'current' into patch-4

Author: ChadMatsalla

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/2023.12.0.md

@@ -36,12 +36,12 @@ duplicate pin definitions. See the [Pin Schema](/guides/configuration-types#pin-
 
 ## Touchscreen internal changes
 
-The touchscreen compoenent code has had a big overhaul which breaks any external components or open PRs for
+The touchscreen component code has had a big overhaul which breaks any external components or open PRs for
 new touchscreens. See {{< pr number="4596" repo="esphome" >}} for details if this affects you.
 
 ## MCP3008 breaking changes
 
-The MCP3008 has has a restructure of the code and at the same time the default update interval has been changed
+The MCP3008 has had a restructure of the code and at the same time the default update interval has been changed
 to 60 seconds, the units, device class and state class default have also been set to sane defaults expected for
 a voltage sensor.
 

content/changelog/2024.12.0.md

@@ -20,7 +20,7 @@ ESPHome has now updated the core ESP32 code to use [ESP-IDF](https://github.com/
 This is a major upgrade and should bring more features, chip support (Most notably the ESP32-C6 that people
 keep raving on about) and in general more stability.
 
-To acommodate this change, ESPHome has moved away from the "official" platformio provided ESP32 platform,
+To accommodate this change, ESPHome has moved away from the "official" platformio provided ESP32 platform,
 and is now using a community fork [pioarduino/platform-espressif32](https://github.com/pioarduino/platform-espressif32)
 as platformio has decided to stop providing ESP-IDF updates to their platform for Espressif chips. As a user,
 you should not notice any difference.

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",""
@@ -739,6 +745,7 @@ Often known as "tag" or "card" readers within the community.
 "ILI9486","components/display/ili9xxx","ili9341.jpg"
 "ILI9488","components/display/ili9xxx","ili9488.svg"
 "WSPICOLCD","components/display/ili9xxx","ili9488.svg"
+"HUB75 LED Matrix","components/display/hub75","hub75.svg"
 "Inkplate","components/display/inkplate","inkplate6.jpg"
 "LCD Display","components/display/lcd_display","lcd.jpg"
 "MAX7219 Dot Matrix","components/display/max7219digit","max7219digit.jpg"
@@ -999,6 +1006,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 +1045,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

@@ -84,7 +84,7 @@ control panel is armed, a fault on this type of zone will cause the alarm to go
 The `instant_always` trigger mode is typically used for tamper inputs. Irrespective of whether the alarm control panel
 is armed, a fault will always cause the alarm to go directly to the `triggered` state.
 
-The `delayed_follower` trigger mode is typically specifed for interior passive infared (PIR) or microwave sensors. One
+The `delayed_follower` trigger mode is typically specified for interior passive infrared (PIR) or microwave sensors. One
 of two things happen when a `delayed_follower` zone is faulted:
 
 1. When the alarm panel is in the armed state, a fault on a zone with `delayed_follower` specified will cause the alarm
@@ -95,7 +95,7 @@ of two things happen when a `delayed_follower` zone is faulted:
 
 The `delayed_follower` trigger mode offers better protection if someone enters a premises via an unprotected window
 or door. If there is a PIR guarding the main hallway, it will cause an instant trigger of the alarm panel as someone
-entered the premises in a unusual manner. Likewise, if someone enters the premises though a door set to the `delayed`
+entered the premises in an unusual manner. Likewise, if someone enters the premises through a door set to the `delayed`
 trigger mode, and then triggers the PIR, the alarm will stay in the `pending` state until either they disarm the alarm,
 or the pending timer expires.
 

content/components/alarm_control_panel/template.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]
@@ -104,7 +109,7 @@ api:
 
 - **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID used for code generation.
 - **password** (*Optional*, **Deprecated**, string): The password to protect the API Server with. Defaults
-  to no password. It is recommended to use the `encryption` -> `key` above instead of the the `password`.
+  to no password. It is recommended to use the `encryption` -> `key` above instead of the `password`.
 
 - **on_client_connected** (*Optional*, [Action](/automations/actions#all-actions)): An automation to perform when a client
   connects to the API. See [`on_client_connected` Trigger](#api-on_client_connected_trigger).
@@ -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

@@ -34,6 +34,24 @@ binary_sensor:
     threshold: 0.5
 ```
 
+Alternatively, you can achieve similar functionality using a
+[Template Binary Sensor](/components/binary_sensor/template) with the `condition` option:
+
+```yaml
+# Alternative using template binary sensor
+binary_sensor:
+  - platform: template
+    name: "Engine Running"
+    condition:
+      sensor.in_range:
+        id: motor_current_sensor
+        above: 0.5
+```
+
+> [!NOTE]
+> The template approach does not support hysteresis. Use `analog_threshold` if you need
+> different upper and lower thresholds to reduce noise.
+
 ## Configuration variables
 
 - **sensor_id** (**Required**, [ID](/guides/configuration-types#id)): The ID of the source sensor.