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
- [x] Configure ESP32-C6 UART pins (TX/RX) for MideaUART communication
- [x] Initialize UART driver at 9600 baud 8N1
- [x] Implement basic UART send/receive functionality
- [x] Create UART abstraction layer with timeout handling
- [x] Write unit tests for UART driver (success/failure scenarios)
- [x] Run tests - must pass before next task
- [x] 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
```c
// 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