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)

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

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

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.