Init
This commit is contained in:
@@ -0,0 +1,146 @@
|
||||
# 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
|
||||
```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
|
||||
Reference in New Issue
Block a user