ballu-remote/Readme.md

Ballu AC ESP32-C6 Controller

Implementation of ESP32-C6 based AC controller that bridges Zigbee (Home Assistant) communication with UART-based MideaUART protocol for Ballu air conditioner control.

Overview

This project implements a bridge between Zigbee (Home Assistant) and UART-based MideaUART protocol for controlling Ballu air conditioners using an ESP32-C6 microcontroller.

Features

• UART communication at 9600 baud 8N1 for MideaUART protocol
• Zigbee ZCL Thermostat cluster implementation
• Bidirectional communication between Zigbee and UART layers
• Status monitoring with periodic AC polling, fault detection, and a communication watchdog
• Configurable timing controls (50ms command spacing)
• End-to-end application controller wiring all layers together with reset/recovery

Directory Structure

src/
  uart_driver.c/h      - UART driver implementation
  midea_protocol.c/h   - MideaUART protocol encoding/decoding
  zigbee_zcl.c/h       - Zigbee ZCL Thermostat cluster
  integration_layer.c/h- Integration between Zigbee and UART layers
  status_monitor.c/h   - AC status polling, fault detection, and comms watchdog
  app_controller.c/h   - End-to-end controller wiring all layers + reset/recovery
  main.c               - Application entry point

test/
  uart_driver_test.c          - Unit tests for UART driver
  midea_protocol_test.c       - Unit tests for MideaUART protocol
  zigbee_zcl_test.c           - Unit tests for Zigbee ZCL
  integration_layer_test.c    - Unit tests for integration layer
  status_monitor_test.c       - Unit tests for status monitoring
  app_controller_test.c       - End-to-end integration tests (full command cycles)

docs/
  protocol.md                 - MideaUART protocol details
  zcl_hvac.md                 - Zigbee ZCL Thermostat cluster details
  Hardware integration guide.md - Hardware connection information
  Build system details.md     - Build system and dependencies

## Getting Started

### Prerequisites

- ESP-IDF toolchain
- ESP32-C6 development board
- UART to TTL converter (for debugging)

### Building

```bash
make build

Uploading

make upload

Running Tests

make test

Status Monitoring

The status_monitor module (see src/status_monitor.c/h) provides:

• Periodic AC status polling: sends a MideaUART status-request frame over the UART driver, receives the response, and decodes it into a midea_status_t.
• ZCL mapping: decoded status is mapped to ZCL Thermostat attributes (local_temperature, system_mode) for Home Assistant reporting.
• Fault detection: any non-zero error_code or alarm_mask from the AC raises a fault flag (status_monitor_has_fault) and records the fault code.
• Communication watchdog: tracks the time of the last successful poll and trips a timeout when the poll interval (plus per-attempt timeout) is exceeded or when max_retries consecutive attempts fail.

Configuration (status_monitor_config_t) exposes poll_interval_ms (default 5000ms), timeout_ms (default 1000ms), and max_retries (default 3).

End-to-End Integration

The app_controller module (see src/app_controller.c/h) ties every layer together and drives the two full data flows:

• Command path (HA → Zigbee → Integration → UART → AC): app_controller_process_zigbee_command() forwards an incoming Zigbee command through the integration layer, which encodes and transmits the corresponding MideaUART frame with 50ms rate limiting.
• Feedback path (AC → UART → Status → Integration → Zigbee → HA): app_controller_process_ac_status() decodes a MideaUART status frame, runs fault detection / watchdog bookkeeping, and publishes the result to the ZCL Thermostat cluster for Home Assistant to read.

Reset and recovery:

• app_controller_reset() re-initializes UART and integration state and clears status-monitor error counters without dropping configuration.
• app_controller_recover_if_needed() performs a reset automatically when the communication watchdog trips (retries exhausted or poll window exceeded).
• app_controller_is_healthy() reports comms liveness plus fault state.

src/main.c provides the firmware entry point and service loop. Its main() is compiled only for the firmware build; unit-test binaries define UNIT_TEST and supply their own main().

Integration tests in test/app_controller_test.c exercise full command cycles, including a HA→…→AC→…→HA round trip, timing under a 100-command burst, and the reset/recovery paths.

Implementation Progress

See docs/plans/2026-07-05-ballu-ac-esp32c6-controller-implementation.md for detailed implementation plan and progress tracking.

License

This project is licensed under the MIT License.