ballu-remote/docs/hardware_connection_diagram.md

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

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.