90 lines
3.0 KiB
Markdown
90 lines
3.0 KiB
Markdown
# 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. |