CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

Build: make build - Compiles firmware for ESP32-C6
Upload: make upload - Flashes firmware to device (requires USB connection)
Test: make test - Runs all unit/integration tests using Vitest
Single Test: make test TEST_NAME="test_module_name" - Runs specific test
Debug: make debug - Starts debug mode with serial console

Code Architecture

The system implements a layered architecture for AC controller control:

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
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
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:

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

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

3.2 KiB Raw Blame History