# 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.