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_connection_diagram.md - ESP32-C6 <-> Ballu AC wiring diagram
  home_assistant_integration.md  - Home Assistant usage examples
  Hardware integration guide.md  - ESP32-C6 hardware integration (RU)
  Build system details.md        - Build system and dependencies
```

## Documentation

- [MideaUART protocol](docs/protocol.md)
- [Zigbee ZCL Thermostat cluster](docs/zcl_hvac.md)
- [Hardware connection diagram](docs/hardware_connection_diagram.md)
- [Home Assistant integration guide](docs/home_assistant_integration.md)
- [ESP32-C6 hardware integration guide](docs/Hardware%20integration%20guide.md)
- [Build system details](docs/Build%20system%20details.md)

## Getting Started

### Prerequisites

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

### Building

```bash
make build
```

### Uploading

```bash
make upload
```

### Running Tests

```bash
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.