# 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.