Merge branch 'next' into mipi-rgb-wave-3.16

Author: clydebarrow

content/components/_index.md

@@ -337,6 +337,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"

content/components/api.md

@@ -443,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:
@@ -502,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/cc1101.md

@@ -53,9 +53,13 @@ cc1101:
 - **filter_bandwidth** (*Optional*, frequency): The receive filter bandwidth.
   Range: `58kHz` to `812kHz`. Defaults to `203kHz`.
 - **fsk_deviation** (*Optional*, frequency): Frequency deviation for FSK/GFSK modulation.
+  Range: `1.5kHz` to `381kHz`.
+- **msk_deviation** (*Optional*, int): Deviation index for MSK modulation. Range: `1` to `8`.
 - **channel** (*Optional*, int): Channel number (added to base frequency). Defaults to `0`.
-- **channel_spacing** (*Optional*, frequency): Spacing between channels. Defaults to `200kHz`.
-- **if_frequency** (*Optional*, frequency): Intermediate Frequency. Defaults to `153kHz`.
+- **channel_spacing** (*Optional*, frequency): Spacing between channels.
+  Range: `25kHz` to `405kHz`. Defaults to `200kHz`.
+- **if_frequency** (*Optional*, frequency): Intermediate Frequency.
+  Range: `25kHz` to `788kHz`. Defaults to `153kHz`.
 - **pktlen** (*Optional*, int): Packet length configuration. Sets the expected packet size for
   fixed-length packet mode. Range: `1` to `255`. Not typically needed for OOK/ASK modulation.
 

content/components/i2c.md

@@ -53,6 +53,9 @@ i2c:
 - **scl_pullup_enabled** (*Optional*, boolean): Enable the internal pullup resistor for the SCL pin.
   Defaults to `true`. Only available on ESP32.
 
+- **low_power_mode** (*Optional*, boolean): Enable the low-power (master only) I²C bus.
+  Only availible on ESP32C5, ESP32C6 and ESP32P4. Defaults to `false` unless required.
+
 - **id** (*Optional*, [ID](/guides/configuration-types#id)): Manually specify the ID for this I²C bus if you need multiple I²C buses.
 
 > [!NOTE]

content/components/micronova.md

@@ -49,16 +49,14 @@ micronova:
 ### Configuration variables
 
 - **enable_rx_pin** (**Required**, [Pin](/guides/configuration-types#pin)): Output pin to be used to switch the line between RX and TX.
-- **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked.
-  Defaults to 60 seconds.
 
 > [!NOTE]
 > For all text sensors, sensors, numbers, buttons and switches hereafter most of the the default **memory_location** and **memory_address** parameters will work so you should
 > not specify them. However your Micronova boad may require you to specify alternate values. So every text sensor, button,
 > switch or number accepts these parameters:
 >
-> - **memory_location** (*Optional*): The memory location where the parameter must be read. For most stoves this is 0x00 for RAM
->   or 0x20 for EPROM.
+> - **memory_location** (*Optional*): The memory location for the parameter (0x00 for RAM, 0x20 for EPROM on most stoves).
+>   The write bit is set automatically when writing.
 >
 > - **memory_address** (*Optional*): The address where the parameter is stored.
 
@@ -74,7 +72,8 @@ text_sensor:
 ### Configuration variables
 
 - **stove_state** (*Optional*): The current stove state.
-  All options from [Text Sensor](/components/text_sensor#config-text_sensor).
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
+  - All options from [Text Sensor](/components/text_sensor#config-text_sensor).
 
 ## Sensors
 
@@ -103,27 +102,34 @@ sensor:
 ### Configuration variables
 
 - **room_temperature** (*Optional*): Sensor that reads the stoves ambient room temperature.
-  All options from [Sensor](/components/sensor).
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
+  - All options from [Sensor](/components/sensor).
 
 - **fumes_temperature** (*Optional*): Fumes temperature.
-  All options from [Sensor](/components/sensor).
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
+  - All options from [Sensor](/components/sensor).
 
 - **stove_power** (*Optional*): Current stove power.
-  All options from [Sensor](/components/sensor).
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
+  - All options from [Sensor](/components/sensor).
 
 - **fan_speed** (*Optional*): Current fan speed. The raw value from the stove is multiplied by 10 + `fan_rpm_offset`.
-
   - **fan_rpm_offset** (*Optional*, integer): Offset the reported RPM value. Must be between 0 and 255. Defaults to 0.
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
   - All other options from [Sensor](/components/sensor).
-- **water_temperature** (*Optional*): Internal boiler water termperature.
-  All options from [Sensor](/components/sensor).
+
+- **water_temperature** (*Optional*): Internal boiler water temperature.
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
+  - All options from [Sensor](/components/sensor).
 
 - **water_pressure** (*Optional*): Internal boiler water pressure.
-  All options from [Sensor](/components/sensor).
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
+  - All options from [Sensor](/components/sensor).
 
 - **memory_address_sensor** (*Optional*): Can be any **memory_location** / **memory_address** you want to track. Usefull
   when you don't know where the parameter is for your stove is.
-  All options from [Sensor](/components/sensor).
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
+  - All options from [Sensor](/components/sensor).
 
 ## Numbers
 
@@ -141,15 +147,11 @@ number:
 
 - **thermostat_temperature** (*Optional*): Number that holds the current stove thermostat value.
   - **step** (*Optional*): Temperature step. This value is used to multiply/devide the raw value when setting/reading the **thermostat_temperature**
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
   - All other options from [Number](/components/number#config-number).
 - **power_level** (*Optional*): Number that sets/reads the requested stove power.
-  All options from [Number](/components/number#config-number).
-
-> [!NOTE]
-> Besides **memory_location** and **memory_address** you can specify a specific **memory_write_location** parameter.
-> This parameter is a hex value for the **memory_location** where the new thermostat value must be written.
->
-> - **memory_write_location** (*Optional*): The **memory_location** where to write the new thermostat value.
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval that the sensors should be checked. Defaults to 60 seconds.
+  - All options from [Number](/components/number#config-number).
 
 ## Buttons
 
@@ -185,8 +187,10 @@ switch:
 ### Configuration variables
 
 - **stove** (*Optional*): Turn the stove on or off. This switch will also reflect the current stove state.
-  If the **stove_state** is "Off" the switch will be off, in all other states, the switch wil be on.
-  All options from [Switch](/components/switch#config-switch).
+  If the **stove_state** is "Off" the switch will be off, in all other states, the switch will be on.
+  - **update_interval** (*Optional*, [Time](/guides/configuration-types#time)): The interval at which the state should
+    be checked. Defaults to 60 seconds.
+  - All options from [Switch](/components/switch#config-switch).
 
 > [!NOTE]
 > Besides **memory_location** and **memory_address** you can specify specific **memory_data_on** and **memory_data_off** parameters.

content/components/output/pca9685.md

@@ -53,6 +53,22 @@ output:
     channel: 0
 ```
 
+```yaml
+# Example configuration entry with disabled phase_balancer
+pca9685:
+  - id: pca9685_hub1
+    phase_balancer: none
+
+# Individual outputs
+output:
+  - platform: pca9685
+    pca9685_id: 'pca9685_hub1'
+    channel: 0
+  - platform: pca9685
+    pca9685_id: 'pca9685_hub1'
+    channel: 1
+```
+
 ### Configuration variables
 
 - **frequency** (*Optional*, float): The frequency to let the
@@ -66,6 +82,20 @@ output:
 - **id** (*Optional*, [ID](/guides/configuration-types#id)): The id to use for
    this pca9685 component. Use this if you have multiple PCA9685s connected at the same time
 
+- **phase_balancer** (*Optional*, string): The phase balancer algorithm to use.
+  See [Phase Balancer](#phase-balancer) below.
+
+### Phase Balancer
+
+The PCA9685 allows setting different phase angles on each output. The following algorithms can be used
+to set the phase angle of each output:
+
+- `linear` (default): The phase angle is set by distributing all defined outputs equally among 360°.
+  So with 3 outputs the first would have 0°, the second 120° and the last 240°. This algorithm can
+  cause flickering when animating the light, because the PCA9685 chip will need an additional frame
+  where no PWM is generated if the start angle is higher than the stop angle.
+- `none`: The phase angle is always 0°. This is the safer option if you control LED lights.
+
 {{< anchor "pca9685-output" >}}
 
 ## PCA9685 Output