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>
99 lines
4.5 KiB
Markdown
99 lines
4.5 KiB
Markdown
# 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.
|