Vladimir Zagainov
ff22483f8b
- Rewrite project CLAUDE.md to match actual C/Unity implementation and modules - Add docs/hardware_connection_diagram.md (ESP32-C6 <-> Ballu AC wiring) - Add docs/home_assistant_integration.md (HA usage examples) - Update Readme.md doc index and fix unclosed code fence - Validate docs against implementation (build + all tests pass) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
145 lines
3.8 KiB
Markdown
145 lines
3.8 KiB
Markdown
# Home Assistant Integration Guide
|
|
|
|
This controller presents the Ballu AC to Home Assistant as a standard Zigbee
|
|
**ZCL Thermostat** device. Home Assistant talks to it through a Zigbee
|
|
coordinator running either ZHA or Zigbee2MQTT — no custom integration is needed
|
|
beyond the device pairing.
|
|
|
|
## 1. What the Device Exposes
|
|
|
|
The firmware implements a ZCL Thermostat cluster server
|
|
(`src/zigbee_zcl.c`) with these attributes:
|
|
|
|
| ZCL attribute | Type | Meaning |
|
|
| :-- | :-- | :-- |
|
|
| `local_temperature` | int16, 0.01°C | Current indoor temperature read from the AC |
|
|
| `system_mode` | uint8 | Operating mode (see mapping below) |
|
|
|
|
`system_mode` values (as exposed on the Zigbee side):
|
|
|
|
| Value | Mode |
|
|
| :-- | :-- |
|
|
| 0 | Off |
|
|
| 1 | Auto |
|
|
| 3 | Cool |
|
|
| 4 | Heat |
|
|
|
|
Internally these map to MideaUART modes via the integration layer
|
|
(`integration_layer_map_zcl_to_midea_mode`); MideaUART additionally supports
|
|
Dry, Fan, Sleep, and Turbo (`src/midea_protocol.h`).
|
|
|
|
## 2. Pairing
|
|
|
|
1. Put the Zigbee coordinator into permit-join mode (ZHA: *Add device*;
|
|
Zigbee2MQTT: *Permit join*).
|
|
2. Power on the ESP32-C6 controller; it joins as a Zigbee end device / router.
|
|
3. The device appears with a Thermostat entity exposing current temperature and
|
|
a mode selector.
|
|
|
|
## 3. Home Assistant Climate Entity
|
|
|
|
Once paired, ZHA/Zigbee2MQTT automatically create a `climate.*` entity backed by
|
|
the Thermostat cluster. Example resulting entity state:
|
|
|
|
```yaml
|
|
climate.ballu_ac:
|
|
current_temperature: 24.5 # from local_temperature (2450 * 0.01°C)
|
|
hvac_mode: cool # from system_mode = 3
|
|
temperature: 25.0 # target setpoint
|
|
```
|
|
|
|
### Setting mode and temperature (Lovelace / service call)
|
|
|
|
```yaml
|
|
# Turn on cooling at 25°C
|
|
service: climate.set_temperature
|
|
target:
|
|
entity_id: climate.ballu_ac
|
|
data:
|
|
hvac_mode: cool
|
|
temperature: 25
|
|
```
|
|
|
|
```yaml
|
|
# Switch to heating
|
|
service: climate.set_hvac_mode
|
|
target:
|
|
entity_id: climate.ballu_ac
|
|
data:
|
|
hvac_mode: heat
|
|
```
|
|
|
|
```yaml
|
|
# Turn the unit off
|
|
service: climate.set_hvac_mode
|
|
target:
|
|
entity_id: climate.ballu_ac
|
|
data:
|
|
hvac_mode: "off"
|
|
```
|
|
|
|
## 4. Example Automations
|
|
|
|
Cool the room when it gets warm:
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "Cool bedroom when hot"
|
|
trigger:
|
|
- platform: numeric_state
|
|
entity_id: climate.ballu_ac
|
|
attribute: current_temperature
|
|
above: 27
|
|
action:
|
|
- service: climate.set_temperature
|
|
target:
|
|
entity_id: climate.ballu_ac
|
|
data:
|
|
hvac_mode: cool
|
|
temperature: 24
|
|
```
|
|
|
|
Turn the AC off when everyone leaves:
|
|
|
|
```yaml
|
|
automation:
|
|
- alias: "AC off when away"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: group.family
|
|
to: "not_home"
|
|
action:
|
|
- service: climate.set_hvac_mode
|
|
target:
|
|
entity_id: climate.ballu_ac
|
|
data:
|
|
hvac_mode: "off"
|
|
```
|
|
|
|
## 5. Zigbee2MQTT Notes
|
|
|
|
If using Zigbee2MQTT, the device publishes to
|
|
`zigbee2mqtt/<friendly_name>` with a JSON payload containing
|
|
`local_temperature` and `system_mode`. Publish a command like:
|
|
|
|
```json
|
|
{ "system_mode": "cool", "occupied_heating_setpoint": 2500 }
|
|
```
|
|
|
|
Setpoints in raw ZCL are in 0.01°C units (2500 = 25.0°C), matching the firmware's
|
|
temperature representation.
|
|
|
|
## 6. Status Reporting & Faults
|
|
|
|
- The controller polls the AC on a configurable interval (default 5000 ms,
|
|
`status_monitor_config_t.poll_interval_ms`) and updates `local_temperature` /
|
|
`system_mode` accordingly.
|
|
- If the AC reports a non-zero `error_code` or `alarm_mask`, the status monitor
|
|
latches a fault (`status_monitor_has_fault`) and the app controller reports
|
|
unhealthy (`app_controller_is_healthy`).
|
|
- A communication watchdog triggers automatic reset/recovery
|
|
(`app_controller_recover_if_needed`) if polling fails repeatedly.
|
|
|
|
See `docs/zcl_hvac.md` for the full ZCL Thermostat cluster reference and
|
|
`docs/hardware_connection_diagram.md` for wiring.
|