ballu-remote/docs/plans/2026-07-05-ballu-ac-esp32c6-controller-implementation.md

2026-07-05-ballu-ac-esp32c6-controller-implementation

Overview

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

Context

• Hardware: ESP32-C6 with Zigbee module and UART connection to AC
• Protocol: MideaUART for AC communication (9600 baud, 8N1)
• Integration: Zigbee ZCL Thermostat cluster for smart home control
• Documentation: Created protocol.md (MideaUART) and zcl_hvac.md (Zigbee ZCL)

Development Approach

• Regular approach (code first, then tests) for rapid prototyping
• Each task includes unit tests for new/modified functionality
• Tests must pass before proceeding to next task
• Maintain backward compatibility with existing MideaUART library

Testing Strategy

• Unit tests for all protocol handling and integration logic
• Mock UART and Zigbee interfaces for isolated testing
• Integration testing with actual hardware in later phases

Implementation Steps

Task 1: ESP32-C6 Hardware Setup and Basic UART

• Configure ESP32-C6 UART pins (TX/RX) for MideaUART communication
• Initialize UART driver at 9600 baud 8N1
• Implement basic UART send/receive functionality
• Create UART abstraction layer with timeout handling
• Write unit tests for UART driver (success/failure scenarios)
• Run tests - must pass before next task
• Update Readme.md

Task 2: MideaUART Protocol Implementation

• Implement Control structure for MideaUART commands
• Create protocol encoder (Control → UART bytes)
• Implement protocol decoder (UART bytes → Control/status)
• Add timing control (50ms command spacing)
• Implement AC command set: mode, temperature, power, fan
• Write unit tests for encoding/decoding all command types
• Run tests - must pass before next task
• Update Readme.md

Task 3: Zigbee Stack and ZCL Thermostat Cluster

• Initialize Zigbee stack on ESP32-C6
• Implement ZCL Thermostat cluster server
• Handle local_temperature attribute reporting
• Implement system_mode attribute handling (Cool/Heat/Auto/Off)
• Add weekly schedule command handling (set/clear/get)
• Write unit tests for ZCL attribute processing
• Run tests - must pass before next task
• Update Readme.md

Task 4: Zigbee-UART Integration Layer

• Create message broker between Zigbee and UART layers
• Map ZCL system_mode to MideaUART MODE_* enums
• Convert ZCL temperature (0.01°C) to MideaUART format
• Implement bidirectional status synchronization
• Handle command queuing and rate limiting (50ms spacing)
• Write unit tests for mapping logic and error cases
• Run tests - must pass before next task
• Update Readme.md

Task 5: Status Monitoring and Feedback

• Implement AC status polling via UART (temperature, mode, etc.)
• Map MideaUART status to ZCL attributes for reporting
• Implement error handling and fault detection
• Add watchdog for communication timeouts
• Write unit tests for status monitoring and error paths
• Run tests - must pass before next task
• Update Readme.md

Task 6: End-to-End Integration and Testing

• Integrate all layers: Zigbee ←→ Integration ←→ UART
• Test command flow: HA → Zigbee → UART → AC → Status → Zigbee → HA
• Validate timing constraints under load
• Implement reset/recovery procedures
• Write integration tests for full command cycles
• Run full test suite - must pass before completion
• Update Readme.md

Task 7: Documentation and Validation

• Update CLAUDE.md with implementation details
• Create hardware connection diagram in docs/
• Add usage examples for Home Assistant integration
• Validate all documentation against implementation
• Final review and cleanup
• Update Readme.md

Technical Details

Data Structures

// UART Control structure (from MideaUART)
typedef struct {
    uint8_t mode;           // AC mode (COOL, HEAT, etc.)
    int16_t target_temp;    // Temperature * 100 (for 0.01°C resolution)
    uint8_t mode_change;    // Boolean flag
    uint8_t temp_change;    // Boolean flag
    uint16_t pwm_arg;       // PWM argument for fan speed
    uint8_t power_state;    // ON/OFF
    int16_t presets;        // Preset configuration
} midea_control_t;

// ZCL Thermostat attributes (mapped)
typedef struct {
    int16_t local_temperature;     // Current temp in 0.01°C units
    uint8_t system_mode;           0=Off, 1=Auto, 3=Cool, 4=Heat
    uint8_t control_sequence;      HVAC operation sequence
} zcl_thermostat_attrs_t;

Processing Flow

1. Incoming Zigbee Command → Parse ZCL attributes
2. Integration Layer → Convert to MideaUART Control structure
3. UART Layer → Encode and send via ESP32-C6 UART (50ms spacing)
4. AC Response → Decode UART response to status
5. Status Update → Convert to ZCL attributes and report

What Goes Where

Files to Create/Modify:

• Create: src/uart_driver.c and uart_driver.h
• Create: src/midea_protocol.c and midea_protocol.h
• Create: src/zigbee_zcl.c and zigbee_zcl.h
• Create: src/integration_layer.c and integration_layer.h
• Create: src/main.c (application entry point)
• Modify: docs/protocol.md (add implementation notes)
• Modify: docs/zcl_hvac.md (add mapping details)
• Create: test/uart_driver_test.c
• Create: test/midea_protocol_test.c
• Create: test/zigbee_zcl_test.c
• Create: test/integration_layer_test.c

Post-Completion

Items requiring manual intervention or external systems

Manual verification:

• Physical hardware testing with Ballu AC unit
• Zigbee network pairing and Home Assistant integration
• Temperature accuracy validation (±0.5°C)
• Command response time verification (<100ms end-to-end)

External system updates:

• Home Assistant configuration examples
• ESP-IDF project configuration and dependencies