feat: finalize documentation and validation (Task 7)
- 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>
This commit is contained in:
98
docs/hardware_connection_diagram.md
Normal file
98
docs/hardware_connection_diagram.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# Hardware Connection Diagram: ESP32-C6 ↔ Ballu AC
|
||||
|
||||
This document describes the physical wiring between the ESP32-C6 controller and
|
||||
the Ballu air conditioner's MideaUART port, and the logical signal path through
|
||||
the firmware.
|
||||
|
||||
> Pin numbers below match the firmware defaults in `src/app_controller.c`
|
||||
> (`apply_default_uart_config`): **TX = GPIO16**, **RX = GPIO17**, 9600 baud, 8N1.
|
||||
> These are configurable via `app_controller_config_t.uart_config`.
|
||||
|
||||
## 1. Signal Overview
|
||||
|
||||
```
|
||||
+---------------------+ UART 9600 8N1 +---------------------+
|
||||
| | (50 ms command spacing) | |
|
||||
| Home Assistant | | Ballu AC unit |
|
||||
| (Zigbee coord.) | | (Midea UART bus) |
|
||||
| | | |
|
||||
+----------+----------+ +----------+----------+
|
||||
| |
|
||||
Zigbee 2.4 GHz (802.15.4) 3.3V TTL UART
|
||||
| |
|
||||
+----------v---------------------------------------------------v----------+
|
||||
| ESP32-C6 controller |
|
||||
| |
|
||||
| [Zigbee radio] --> zigbee_zcl --> integration_layer --> midea_protocol |
|
||||
| | | |
|
||||
| v v |
|
||||
| status_monitor <--> uart_driver |
|
||||
| | |
|
||||
| GPIO16 (TX) --------+ |
|
||||
| GPIO17 (RX) --------+ |
|
||||
+-------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## 2. Physical Wiring (ESP32-C6 ↔ AC MideaUART header)
|
||||
|
||||
The Ballu/Midea indoor unit exposes a 3-wire (or 4-wire) TTL UART header. The AC
|
||||
side already provides regulated power on some models; **verify the voltage on the
|
||||
AC connector before wiring** — the ESP32-C6 GPIO are strictly 3.3V tolerant.
|
||||
|
||||
| ESP32-C6 pin | Direction | AC MideaUART pin | Notes |
|
||||
| :-- | :--: | :-- | :-- |
|
||||
| GPIO16 (TX) | ESP → AC | RX | Controller transmits commands to the AC |
|
||||
| GPIO17 (RX) | AC → ESP | TX | Controller receives status frames from the AC |
|
||||
| GND | common | GND | **Mandatory** common ground reference |
|
||||
| 3V3 | power | +5V/+12V | Do **not** connect AC +5V/+12V directly to 3V3; use a suitable regulator if powering the ESP32-C6 from the AC |
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph AC [Ballu AC - Midea UART header]
|
||||
ARX[RX]
|
||||
ATX[TX]
|
||||
AGND[GND]
|
||||
APWR[+5V / +12V]
|
||||
end
|
||||
|
||||
subgraph ESP [ESP32-C6 controller]
|
||||
ETX[GPIO16 TX]
|
||||
ERX[GPIO17 RX]
|
||||
EGND[GND]
|
||||
E3V3[3V3]
|
||||
end
|
||||
|
||||
ETX -->|3.3V TTL| ARX
|
||||
ATX -->|3.3V TTL| ERX
|
||||
EGND --- AGND
|
||||
APWR -.->|via 3.3V regulator only| E3V3
|
||||
```
|
||||
|
||||
## 3. Wiring Rules
|
||||
|
||||
- **Cross TX/RX**: controller TX (GPIO16) → AC RX; AC TX → controller RX (GPIO17).
|
||||
- **Common ground is mandatory** — floating grounds cause framing errors.
|
||||
- **3.3V logic only.** If the AC UART header uses 5V logic, insert a logic-level
|
||||
shifter between the boards.
|
||||
- **Power isolation.** Never feed the AC's raw supply rail into the ESP32-C6 3V3
|
||||
pin; step it down with a regulator (or power the ESP32-C6 over USB during
|
||||
development).
|
||||
- **Strapping pins.** GPIO16/GPIO17 are the ESP32-C6 default UART0 pins used for
|
||||
boot logging/flashing. When wiring the AC to these pins, disconnect the AC
|
||||
during flashing, or remap the AC UART to spare GPIO via
|
||||
`uart_config_t.tx_pin` / `rx_pin` to keep the boot console free.
|
||||
|
||||
## 4. Firmware Signal Path
|
||||
|
||||
- **Command path (HA → AC):**
|
||||
`zigbee_zcl` receives a ZCL Thermostat command → `integration_layer` maps
|
||||
`system_mode`/temperature to a `midea_control_t` → `midea_protocol` encodes the
|
||||
frame → `uart_driver` transmits it on GPIO16 with ≥50 ms spacing.
|
||||
- **Feedback path (AC → HA):**
|
||||
`uart_driver` reads a frame on GPIO17 → `midea_protocol` decodes it to
|
||||
`midea_status_t` → `status_monitor` runs fault detection + watchdog and maps to
|
||||
`zcl_thermostat_attrs_t` → `zigbee_zcl` publishes `local_temperature` and
|
||||
`system_mode` for Home Assistant.
|
||||
|
||||
See `docs/Hardware integration guide.md` for detailed ESP32-C6 pinout, strapping
|
||||
pin cautions, and PCB layout guidance.
|
||||
144
docs/home_assistant_integration.md
Normal file
144
docs/home_assistant_integration.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 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.
|
||||
@@ -80,12 +80,12 @@ Implementation of ESP32-C6 based AC controller that bridges Zigbee (Home Assista
|
||||
- [x] Update Readme.md
|
||||
|
||||
### Task 7: Documentation and Validation
|
||||
- [ ] Update CLAUDE.md with implementation details
|
||||
- [ ] Create hardware connection diagram in docs/
|
||||
- [ ] Add usage examples for Home Assistant integration
|
||||
- [ ] Validate all documentation against implementation
|
||||
- [ ] Final review and cleanup
|
||||
- [ ] Update Readme.md
|
||||
- [x] Update CLAUDE.md with implementation details
|
||||
- [x] Create hardware connection diagram in docs/
|
||||
- [x] Add usage examples for Home Assistant integration
|
||||
- [x] Validate all documentation against implementation
|
||||
- [x] Final review and cleanup
|
||||
- [x] Update Readme.md
|
||||
|
||||
## Technical Details
|
||||
|
||||
|
||||
Reference in New Issue
Block a user