81 lines
3.2 KiB
Markdown
81 lines
3.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Common Development Commands
|
|
1. **Build**: `make build` - Compiles firmware for ESP32-C6
|
|
2. **Upload**: `make upload` - Flashes firmware to device (requires USB connection)
|
|
3. **Test**: `make test` - Runs all unit/integration tests using Vitest
|
|
4. **Single Test**: `make test TEST_NAME="test_module_name"` - Runs specific test
|
|
5. **Debug**: `make debug` - Starts debug mode with serial console
|
|
|
|
## Code Architecture
|
|
The system implements a layered architecture for AC controller control:
|
|
|
|
1. **Zigbee Interface Module**
|
|
- Receives and decodes Zigbee messages from Home Assistant or similar
|
|
- Translates commands to UART format
|
|
- Key files: `zigbee-handler.c`, `zigbee-decoder.h`
|
|
|
|
2. **Command Processing Core**
|
|
- Implements MideaUART protocol (based on cloned MideaUART repository)
|
|
- Parses UART commands and converts to AC control signals
|
|
- Key files: `uart-controller.c`, `midea-parser.h`
|
|
|
|
3. **Hardware Abstraction Layer**
|
|
- Manages ESP32-C6 GPIO and UART operations
|
|
- Handles precise timing for AC communication protocol
|
|
- Key files: `hardware-abstraction.c`
|
|
|
|
## Development Notes
|
|
- Protocol implementation must strictly follow MideaUART specifications
|
|
- UART communication requires 50ms baud rate timing
|
|
- Testing should focus on edge cases for time-sensitive operations
|
|
- Dependencies managed via Makefile - do not modify directly
|
|
- MideaUART implementation: https://github.com/dudanov/MideaUART
|
|
|
|
## Zigbee ZCL HVAC Integration (Thermostat Cluster)
|
|
|
|
### 1. Core Zigbee Cluster Attributes
|
|
- `local_temperature` (int16_t): Current measured temperature (0.01°C resolution)
|
|
- `system_mode` (uint8_t): Current system mode
|
|
- 0x00: Off, 0x01: Auto, 0x03: Cooling, 0x04: Heating
|
|
- 0x08: Dry, 0x09: Sleep
|
|
- `local_temperature_display`: Display temperature value for UI
|
|
|
|
### 2. HVAC System Types
|
|
- Supports standard HVAC modes: Cooling, Heating, Heat Pump (Cooling + Heating)
|
|
- Configuration constants:
|
|
- `EZB_ZCL_HVAC_SYSTEM_TYPE_CONFIGURATION_COOLING_SYSTEM_STAGE = 0x03`
|
|
|
|
### 3. Temperature Control
|
|
- Temperature range: -1°C to 32767°C (0.01°C resolution)
|
|
- Convert to MideaUART format: divide by 100 (e.g., 2500 → 25.0°C)
|
|
- Command structure:
|
|
```c
|
|
control.mode = MODE_COOL; // Zigbee mode: 0x03 (Cooling)
|
|
control.targetTemp = 25.0f; // 25°C target
|
|
control.modeChange = true;
|
|
ac.control(control);
|
|
```
|
|
|
|
### 4. Schedule Management
|
|
- Support weekly schedule setting/clearing through Zigbee cluster commands
|
|
- Convert schedule entries to MideaUART Control scheduling parameters
|
|
|
|
### 5. Status Monitoring Integration
|
|
- Monitor `AlarmMask` for hardware failures
|
|
- Track `ACErrorCode` for system fault detection
|
|
- Implement status callbacks for UI updates
|
|
|
|
### 6. Mapping Example
|
|
```c
|
|
// When Zigbee reports mode = 0x03 (Cooling) and target temp = 2500 (25.00°C)
|
|
Control control;
|
|
control.mode = MODE_COOL;
|
|
control.targetTemp = 25.0f; // Convert from 0.01°C units
|
|
control.modeChange = true;
|
|
ac.control(control);
|
|
```
|
|
|
|
This documentation covers both the core Midea UART protocol for device communication and the Zigbee ZCL thermostat cluster integration for smart home control. |