# 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

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

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