Init

Claude.md

@@ -0,0 +1,81 @@
+# 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.