From 6c237faadb03b47dc84e43bfbe44c50f89cfef07 Mon Sep 17 00:00:00 2001 From: Vladimir Zagainov Date: Sun, 5 Jul 2026 18:21:29 +0300 Subject: [PATCH] Init --- Claude.md | 81 ++++++++ docs/.DS_Store | Bin 0 -> 6148 bytes docs/Build system details.md | 187 ++++++++++++++++++ docs/Hardware integration guide.md | 131 ++++++++++++ ...lu-ac-esp32c6-controller-implementation.md | 146 ++++++++++++++ docs/protocol.md | 138 +++++++++++++ docs/zcl_hvac.md | 122 ++++++++++++ 7 files changed, 805 insertions(+) create mode 100644 Claude.md create mode 100644 docs/.DS_Store create mode 100644 docs/Build system details.md create mode 100644 docs/Hardware integration guide.md create mode 100644 docs/plans/2026-07-05-ballu-ac-esp32c6-controller-implementation.md create mode 100644 docs/protocol.md create mode 100644 docs/zcl_hvac.md diff --git a/Claude.md b/Claude.md new file mode 100644 index 0000000..ac8d657 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/.DS_Store b/docs/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..5f0d0db6ecaccad422e773eb41adf9db7116d332 GIT binary patch literal 6148 zcmeH~J&pn~427Q;kXG7;k}}O6fEz@JJpmWsuN=Wjh(1T>*>S_L^=gEkCFjLXJU?GC z83VA*{k#U206yui`1WCB#(05W3^?F|+xd1Hj@RqpX?)~f59qwc^Lj2zL_h>YKm_o2{TYijEnpAHVu0#N5nhjAXg1hsgAT2otBW@wh( zgJr2j8{+vWr+#ah{~!8a{r{*$ zp$Le;n-Q@2cDLQ|rSfcjc|FhXGwbt4r^a>;Pd@<+{3u@0!?<32LanK-D>F3x2m}TV IBJi&S9xwY7mjD0& literal 0 HcmV?d00001 diff --git a/docs/Build system details.md b/docs/Build system details.md new file mode 100644 index 0000000..5480b78 --- /dev/null +++ b/docs/Build system details.md @@ -0,0 +1,187 @@ +# Спецификация системы сборки: ESP-IDF для ESP32-C6 +**Версия документа:** 1.0 +**Статус:** Одобрено (Release) +**Область применения:** Настройка окружения, конфигурация сборки, управление зависимостями и автоматизация команд для проектов на ESP32-C6 (включая Zigbee-приложения). + +--- + +## 1. Введение + +Официальным фреймворком для ESP32-C6 является **ESP-IDF** (начиная с версии v5.1+). Современный ESP-IDF использует **CMake** и систему сборки **Ninja**, управление которыми осуществляется через утилиту командной строки `idf.py`. + +Использование традиционного GNU Make в качестве основной системы сборки в ESP-IDF отключено, однако `Makefile` часто применяется на верхнем уровне как **удобная оболочка (wrapper)** для автоматизации рутинных задач, CI/CD пайплайнов и стандартизации команд в команде разработчиков. + +--- + +## 2. Структура проекта + +Стандартная структура директорий проекта для ESP32-C6 выглядит следующим образом: + +```text +my_esp32c6_project/ +├── CMakeLists.txt # Главный файл конфигурации CMake +├── Makefile # Оболочка (Wrapper) для быстрых команд +├── sdkconfig.defaults # Базовые настройки конфигурации (для Git) +├── idf_component.yml # Манифест зависимостей проекта (Registry) +├── main/ +│ ├── CMakeLists.txt # Конфигурация сборки исходников +│ ├── main.c # Точка входа приложения (app_main) +│ └── idf_component.yml # Зависимости конкретного компонента +└── components/ # Локальные компоненты (драйверы, библиотеки) + └── custom_sensor/ + ├── CMakeLists.txt + ├── include/ + └── custom_sensor.c +``` + +--- + +## 3. Структура оболочки Makefile (Wrapper) + +Так как прямой вызов `make` больше не поддерживается фреймворком напрямую, мы создаем `Makefile`, который транслирует привычные команды в вызовы `idf.py`. + +**Пример файла `Makefile` в корне проекта:** + +```makefile +# Makefile wrapper для ESP-IDF (ESP32-C6) + +# Настройки по умолчанию +PORT ?= /dev/ttyUSB0 +BAUD ?= 460800 +TARGET ?= esp32c6 + +.PHONY: all build flash monitor clean menuconfig set-target full + +all: build + +# Установка целевого микроконтроллера +set-target: + idf.py set-target $(TARGET) + +# Вызов графического конфигуратора +menuconfig: + idf.py menuconfig + +# Сборка проекта +build: + idf.py build + +# Прошивка устройства +flash: + idf.py -p $(PORT) -b $(BAUD) flash + +# Открытие последовательного монитора +monitor: + idf.py -p $(PORT) monitor + +# Прошивка и запуск монитора одной командой +full: + idf.py -p $(PORT) -b $(BAUD) flash monitor + +# Очистка артефактов сборки +clean: + idf.py clean + +# Полное удаление директории build и sdkconfig (Hard reset) +distclean: + idf.py fullclean + rm -rf build/ dependencies.lock +``` + +**Использование:** +Вместо ввода длинных команд, разработчик может использовать: +* `make build` — для компиляции. +* `make PORT=/dev/ttyACM0 full` — для сборки, прошивки и открытия логов. + +--- + +## 4. Конфигурация ESP-IDF (CMake и sdkconfig) + +### 4.1. Главный `CMakeLists.txt` +Располагается в корне проекта. Его задача — инициализировать фреймворк и объявить проект. + +```cmake +# Минимально требуемая версия CMake +cmake_minimum_required(VERSION 3.16) + +# Подключение базового скрипта сборки ESP-IDF +include($ENV{IDF_PATH}/tools/cmake/project.cmake) + +# Имя проекта +project(esp32c6_zigbee_node) +``` + +### 4.2. Конфигурация компонентов (`main/CMakeLists.txt`) +Определяет исходные файлы приложения и их зависимости от других модулей ESP-IDF. + +```cmake +idf_component_register( + SRCS "main.c" "zigbee_handler.c" + INCLUDE_DIRS "." "include" + REQUIRES nvs_flash esp_timer freertos + PRIV_REQUIRES esp_zigbee_gateway # Приватная зависимость от Zigbee +) +``` + +### 4.3. Настройки SDK (`sdkconfig` и `sdkconfig.defaults`) +Файл `sdkconfig` генерируется автоматически и **не должен** добавляться в систему контроля версий (Git). +Вместо этого используется файл `sdkconfig.defaults`, в котором фиксируются только те параметры, которые отличаются от стандартных. + +**Пример `sdkconfig.defaults` для Zigbee-проекта на ESP32-C6:** + +```ini +# Установка целевого чипа +CONFIG_IDF_TARGET="esp32c6" + +# Настройки FreeRTOS (частота тиков) +CONFIG_FREERTOS_HZ=1000 + +# Использование кастомной таблицы разделов (Partition Table) +CONFIG_PARTITION_TABLE_CUSTOM=y +CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv" + +# Включение поддержки IEEE 802.15.4 (Zigbee/Thread) +CONFIG_ZB_ENABLED=y +CONFIG_ZB_RADIO_NATIVE=y + +# Оптимизация размера прошивки (полезно для OTA) +CONFIG_COMPILER_OPTIMIZATION_SIZE=y +``` + +> **Примечание:** При выполнении сборки (`idf.py build`), система автоматически применит настройки из `sdkconfig.defaults` и сгенерирует финальный файл `sdkconfig`. + +--- + +## 5. Управление зависимостями + +ESP-IDF v5.x использует продвинутый менеджер компонентов (**ESP-IDF Component Manager**), который скачивает библиотеки из [ESP Component Registry](https://components.espressif.com/). + +### 5.1. Файл манифеста (`idf_component.yml`) +Для добавления внешних библиотек (например, официального стека ESP-Zigbee) создается файл `idf_component.yml` в директории `main/`. + +**Пример `main/idf_component.yml`:** + +```yaml +version: "1.0.0" +description: "Main application component for ESP32-C6 Zigbee Node" + +dependencies: + # Зависимость от официального SDK Espressif для Zigbee + espressif/esp-zigbee-lib: "^1.0.0" + + # Зависимость от библиотеки парсинга JSON + jsmn: "~1.1.0" + + # Пример подключения компонента из локальной директории или Git + custom_driver: + path: ../components/custom_driver +``` + +### 5.2. Разрешение зависимостей +Во время выполнения `idf.py build` (или `make build`) происходит следующее: +1. Менеджер компонентов анализирует `idf_component.yml`. +2. Скачивает нужные версии библиотек в директорию `managed_components/` (которая должна быть добавлена в `.gitignore`). +3. Создает файл `dependencies.lock`, фиксирующий точные версии загруженных библиотек. *Этот файл рекомендуется коммитить в Git для обеспечения воспроизводимости сборок на CI/CD.* + +### 5.3. Локальные компоненты +Если вы разрабатываете собственные драйверы, размещайте их в папке `components/` в корне проекта. ESP-IDF автоматически сканирует эту папку, и любой валидный компонент (с файлом `CMakeLists.txt`) будет доступен в `main` через директиву `REQUIRES` или автоматически, если менеджер сам разрешит пути. diff --git a/docs/Hardware integration guide.md b/docs/Hardware integration guide.md new file mode 100644 index 0000000..7689804 --- /dev/null +++ b/docs/Hardware integration guide.md @@ -0,0 +1,131 @@ +# Руководство по аппаратной интеграции: ESP32-C6 +**Версия документа:** 1.0 +**Статус:** Одобрено (Release) +**Область применения:** Аппаратная разработка, интеграция модулей ESP32-C6 (на примере ESP32-C6-WROOM-1), подключение UART и использование Zigbee 3.0. + +--- + +## 1. Введение +Данный документ описывает требования и рекомендации по аппаратной интеграции системы-на-кристалле (SoC) **ESP32-C6**. Особенностью ESP32-C6 является встроенная поддержка Wi-Fi 6 (802.11ax), Bluetooth 5.3 (LE) и 802.15.4 (Zigbee 3.0 / Thread). + +В руководстве рассмотрены базовая распиновка, схемы подключения интерфейса UART и варианты использования ESP32-C6 в качестве Zigbee-координатора или радиосопроцессора (RCP - Radio Co-Processor). + +--- + +## 2. Распиновка ESP32-C6 (Pinout) + +В таблице ниже приведена базовая распиновка на примере стандартного модуля **ESP32-C6-WROOM-1**. ESP32-C6 имеет гибкую матрицу GPIO, поэтому большинство периферийных устройств может быть переназначено на другие пины, однако существуют пины с фиксированными или специальными функциями (Strapping pins). + +### 2.1. Основные выводы (Power & System) +| Название пина | Тип | Описание | +| :--- | :---: | :--- | +| **3V3** | Power | Питание модуля, строго **3.0V - 3.6V**. | +| **GND** | Power | Общая земля. | +| **EN (CHIP_PU)** | Input | Включение чипа (High = ON, Low = OFF). Требуется подтяжка к 3V3 через резистор 10kΩ и конденсатор 1µF на GND (RC-цепь задержки). | + +### 2.2. Конфигурационные выводы (Strapping Pins) +Состояние этих пинов считывается во время сброса (Boot) для определения режима работы. + +| Пин | Функция при загрузке | Нормальное состояние | Режим прошивки (UART Download) | +| :--- | :--- | :---: | :---: | +| **GPIO9** | Boot Mode | **HIGH** (Pull-up) | **LOW** (Pull-down) | +| **GPIO8** | ROM Messages | Н/Д | HIGH / LOW (управляет выводом логов ROM) | +| **GPIO15** | JTAG Signal | HIGH (Pull-up) | Влияет на тайминги VDD_SDIO | + +> ⚠️ **Внимание:** Не подключайте к GPIO9 внешнюю периферию, которая может притянуть пин к земле в момент подачи питания, иначе ESP32-C6 не загрузится в рабочий режим (останется в режиме прошивки). + +### 2.3. Интерфейсы по умолчанию +| Пин | Функция | Описание | +| :--- | :--- | :--- | +| **GPIO16** | U0TXD | UART0 TX (Лог системы и прошивка) | +| **GPIO17** | U0RXD | UART0 RX (Лог системы и прошивка) | +| **GPIO12** | USB_D- | USB Serial/JTAG (Поддержка встроенного USB) | +| **GPIO13** | USB_D+ | USB Serial/JTAG (Поддержка встроенного USB) | + +--- + +## 3. Подключение UART (UART Wiring) + +ESP32-C6 использует логические уровни **3.3V**. Подключение к устройствам с 5V-логикой (например, к старым платам Arduino) требует использования конвертера логических уровней (Logic Level Shifter). + +### 3.1. Базовое подключение (Прошивка и отладка) +Для программирования и чтения логов используется **UART0**. + +* **Host TX** ➔ **ESP32 GPIO17** (U0RXD) +* **Host RX** ➔ **ESP32 GPIO16** (U0TXD) +* **Host GND** ➔ **ESP32 GND** (Обязательное соединение!) + +### 3.2. Подключение аппаратного контроля потока (Hardware Flow Control) +При передаче больших объемов данных (что критично для работы Zigbee RCP на высоких скоростях, например 115200 или 460800 бод), строго рекомендуется использовать аппаратный контроль потока. + +Любые свободные GPIO могут быть назначены как RTS/CTS через матрицу GPIO. Пример конфигурации для **UART1**: +* **UART1 TX:** GPIO4 +* **UART1 RX:** GPIO5 +* **UART1 CTS:** GPIO6 *(подключается к RTS хоста)* +* **UART1 RTS:** GPIO7 *(подключается к CTS хоста)* + +#### Диаграмма подключения UART RCP (Host ↔ ESP32-C6) +```mermaid +graph LR + subgraph Host [Host CPU / Raspberry Pi] + HTX[TXD] + HRX[RXD] + HRTS[RTS] + HCTS[CTS] + HGND[GND] + end + + subgraph ESP [ESP32-C6 Zigbee RCP] + ERX[RXD - GPIO5] + ETX[TXD - GPIO4] + ECTS[CTS - GPIO6] + ERTS[RTS - GPIO7] + EGND[GND] + end + + HTX -->|3.3V| ERX + ETX -->|3.3V| HRX + HRTS -->|3.3V| ECTS + ERTS -->|3.3V| HCTS + HGND --- EGND +``` + +--- + +## 4. Подключение и интеграция Zigbee (Zigbee Module Connections) + +ESP32-C6 содержит встроенный радиомодуль IEEE 802.15.4, что означает, что он **сам является Zigbee-модулем**. Внешний Zigbee-трансивер не требуется. + +Архитектурно ESP32-C6 может использоваться в двух режимах интеграции: + +### Вариант А: Режим "Radio Co-Processor" (RCP) +В этом режиме стек протоколов Zigbee (например, Z2M / Zigbee2MQTT / ZHA) работает на основном хосте (Linux, Raspberry Pi), а ESP32-C6 выступает только как радио-модем. + +1. **Интерфейс связи:** UART1 или USB (через пины GPIO12/13). +2. **Прошивка:** ESP-Zigbee-RCP (компилируется через ESP-IDF). +3. **Требования к железу:** + * Обязательное подключение пинов CTS/RTS (см. раздел 3.2). + * Качественное питание 3.3V, способное обеспечить пиковые токи до **350 мА** во время передачи (TX) в режиме 802.15.4. + +### Вариант Б: Режим "Standalone SoC" (Координатор / Роутер / Конечное устройство) +В этом режиме весь стек Zigbee-координатора (ZC), роутера (ZR) или конечного устройства (ZED) крутится на самом процессоре RISC-V внутри ESP32-C6. + +1. **Подключение датчиков:** Напрямую к пинам ESP32-C6 по I2C (обычно GPIO8/GPIO9), SPI или ADC. +2. **Питание (Для ZED):** Если устройство работает от батарейки (Sleepy End Device), необходимо минимизировать энергопотребление. + * Использовать внешние подтягивающие резисторы большого номинала (от 100kΩ). + * Во время Deep Sleep ток потребления ESP32-C6 составляет **около 7 мкА**. +3. **Интеграция антенны:** + * При использовании версии с PCB-антенной (ESP32-C6-WROOM-1): Запрещается размещать медь на печатной плате под антенной. Необходимо обеспечить "Keepout Zone" минимум 15 мм вокруг антенны. + * При использовании версии с U.FL (IPEX) коннектором (ESP32-C6-WROOM-1U): Убедиться, что ВЧ-кабель имеет импеданс строго 50 Ом. + +--- + +## 5. Чек-лист проектирования печатной платы (PCB Layout) + +- [ ] **Питание (LDO):** Стабилизатор 3.3V должен выдавать не менее 500 мА для обеспечения пиковых нагрузок Wi-Fi + Zigbee (Coexistence). +- [ ] **Конденсаторы (Bypass):** Возле пина 3V3 модуля ESP32-C6 должны быть размещены конденсаторы на 10µF и 0.1µF. +- [ ] **Кнопки BOOT/EN:** Для ручной прошивки добавьте тактовые кнопки: + - Кнопка `RST` замыкает `EN` на `GND`. + - Кнопка `BOOT` замыкает `GPIO9` на `GND`. +- [ ] **Изоляция радиочастот:** Если на плате присутствуют другие высокочастотные компоненты (USB 3.0, импульсные преобразователи), они должны быть экранированы для предотвращения деградации сигнала Zigbee 2.4 GHz. +- [ ] **Auto-Programmer Circuit:** При подключении к USB-UART мосту (CP2102, CH340), использовать стандартную схему с двумя NPN транзисторами (DTR/RTS) для автоматического перевода ESP32-C6 в режим загрузки. diff --git a/docs/plans/2026-07-05-ballu-ac-esp32c6-controller-implementation.md b/docs/plans/2026-07-05-ballu-ac-esp32c6-controller-implementation.md new file mode 100644 index 0000000..7bbdc55 --- /dev/null +++ b/docs/plans/2026-07-05-ballu-ac-esp32c6-controller-implementation.md @@ -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 diff --git a/docs/protocol.md b/docs/protocol.md new file mode 100644 index 0000000..515865b --- /dev/null +++ b/docs/protocol.md @@ -0,0 +1,138 @@ +# Протокол MideaUART + +## Основные параметры UART +- **Бодовая скорость**: 9600 +- **Формат кадра**: 8N1 (8 бит данных, отсутствие стоп-бита, четность отключена) +- **Таймаут**: 50 мс + +## Структура команды +```c +struct Control { + Mode mode; // Режим работы + float targetTemp; // Целевая температура (°C) + bool modeChange; // Флаг смены режима + bool tempChange; // Флаг смены целевой температуры + uint8_t pwmArg; // ШИМ-аргумент (2 байта) + bool powerState; // Состояние питания + int16_t presets; // Индекс предварительно установленных действий +}; +``` + +## Доступные режимы работы +```c +enum class Mode { + MODE_OFF, // Выключено + MODE_COOL, // Охлаждение + MODE_HEAT, // Отопление + MODE_AUTO, // Авторегулировка + MODE_DRY, // Сушка + MODE_FAN, // Вентилятор + MODE_SLEEP, // Сон + MODE_TURBO, // Турбо + MODE_PRESET_1-16 // Предварительно заданные режимы +}; +``` + +## Команды управления + +### 4.1. Изменение режима работы +```c +Control control; +control.mode = Mode::MODE_COOL; // Установка режима охлаждения +control.modeChange = true; // Нужно отправить команду +ac.control(control); // Таймаут 50 мс +``` + +### 4.2. Изменение температуры +```c +control.targetTemp = 25.0f; // 25°C +control.tempChange = true; // Нужно отправить команду +ac.control(control); +``` + +### 4.3. Изменение параметров подогрева (PWM) +```c +control.pwmArg = 7000; // ШИМ-аргумент (мощность) +ac.control(control); +``` + +### 4.4. Изменение глушения (Swing Mode) +```c +control.swingMode = SwingMode::VERTICAL; // Вертикальное +ac.control(control); +``` + +### 4.5. Изменение состояния питания +```c +ac.setPowerState(false); // Выключить питание +``` + +### 4.6. Изменение режима и температуры одновременно +```c +control.mode = MODE_COOL; // Режим охлаждения +control.targetTemp = 26.0f; // Изменение целевой температуры +control.modeChange = true; +control.tempChange = true; +ac.control(control); +``` + +## Пример полного цикла управления +```c +void setup() { + Serial.begin(9600); + ac.setStream(&Serial); + ac.setup(); +} + +void loop() { + // Пример: включить охлаждение на 25°C через 3 секунды + delay(3000); + + Control control; + control.mode = MODE_COOL; + control.targetTemp = 25.0f; + control.modeChange = true; + control.tempChange = true; + + ac.control(control); // Таймаут 50 мс + + // Подождать 5 минут коммутации + delay(300000); + + // Выключить + ac.setPowerState(false); +} +``` + +## Дополнительные функции +1. **Получение состояния**: + ```c + float indoorTemp = ac.getIndoorTemp(); // Текущая температура + Mode currentMode = ac.getMode(); // Текущий режим + float targetTemperature = ac.getTargetTemp(); // Целевая температура + ``` + +2. **Сброс всех настроек**: + ```c + ac.reset(); + ``` + +3. **Создание предварительных действий**: + ```c + control.presets = 5; // Установить алгоритм 5 + ac.control(control); + ``` + +## Особенности реализации +- **Тайминг**: Все команды должны быть отправлены через 50 мс после инициализации +- **Мультиплексирование**: Одну команду можно отправить каждые 50 мс +- **Порядок команд**: + 1. Выбор режима + 2. Изменение температуры + 3. Установка параметров подогрева + 4. Включение/выключение питания + +## Примечания +- Все значения температуры в целых десятых градусов (15.7 = 157) +- Для создания алгоритмов используйте `presets`-ше +- Не забывайте вызывать `ac.loop()` каждые ~5 мс \ No newline at end of file diff --git a/docs/zcl_hvac.md b/docs/zcl_hvac.md new file mode 100644 index 0000000..8888053 --- /dev/null +++ b/docs/zcl_hvac.md @@ -0,0 +1,122 @@ +# Zigbee ZCL HVAC Specification (Thermostat Cluster) + +## Основные атрибуты термостата + +### Обязательные атрибуты: +- `local_temperature` (int16_t): Текущая измеренная температура + - Диапазон: -1°C до 32767°C (значение -1°C означает неинициализированное/недоступное значение) + - Единицы: 0.01°C (так что значение 2500 = 25.00°C) + +- `control_sequence_of_operation` (uint8_t): Последовательность управления + - 0x00: Cooling only + - 0x01: Cooling with Reheat + - 0x02: Heating only + - 0x03: Heating with Reheat + - 0x04: Cooling and Heating + - 0x05: Cooling and Heating with Reheat + +- `system_mode` (uint8_t): Текущий режим работы системы + - 0x00: Off + - 0x01: Auto + - 0x02: Program (запрограммированный режим) + - 0x03: Cool + - 0x04: Heat + - 0x05: Emergency Heat + - 0x06: Precool + - 0x07: Fan Only + - 0x08: Dry + - 0x09: Sleep + +### Атрибуты кондиционера (AC): +- `ACType`: Тип кондиционера + - Охлаждение только + - Тепловой насос (охлаждение/нагрев) + - Охлаждение с электрическим нагревом + - Геотермальный тепловой насос + - Максимальная эффективность + +- `ACCapacityFormat`: Формат емкости + - 0x00: BTU/h (Британские тепловые единицы в час) + - 0x01: Тонны рефрижерации + - 0x02: Ватты + - 0x03: Лошадиные силы + +## Критические константы + +### Режимы системы (system_mode): +- `EZB_ZCL_SYSTEM_MODE_OFF = 0x00`: Выключено +- `EZB_ZCL_SYSTEM_MODE_AUTO = 0x01`: Автоматический режим +- `EZB_ZCL_SYSTEM_MODE_COOL = 0x03`: Охлаждение +- `EZB_ZCL_SYSTEM_MODE_HEAT = 0x04`: Отопление +- `EZB_ZCL_SYSTEM_MODE_EMERG_HEAT = 0x05`: Аварийный обогрев +- `EZB_ZCL_SYSTEM_MODE_PRECOOL = 0x06`: Предварительное охлаждение +- `EZB_ZCL_SYSTEM_MODE_FAN_ONLY = 0x07`: Только вентилятор +- `EZB_ZCL_SYSTEM_MODE_DRY = 0x08`: Сушка +- `EZB_ZCL_SYSTEM_MODE_SLEEP = 0x09`: Режим сна + +### Типы HVAC систем: +- `EZB_ZCL_HVAC_SYSTEM_TYPE_CONFIGURATION_COOLING_SYSTEM_STAGE = 0x03`: Охлаждающая система со ступенями + +## Команды управления + +### Команды настройки расписания (Weekly Schedule): +- `0x00`: Set Weekly Schedule +- `0x01`: Get Weekly Schedule +- `0x02`: Clear Weekly Schedule + +### Команды настройки точек уставки (Setpoint): +- `0x00`: Setpoint Raise/Lower +- `0x01`: Setpoint Set +- `0x02`: Setpoint Get + +## Мониторинг состояния + +### Маска тревог (AlarmMask): +- Биты 0-7: Различные типы аппаратных сбоев + - Датчик температуры неисправен + - Компрессор перегрет + - Недостаток хладагента + - Ошибка вентилятора + +### Коды ошибок кондиционера (ACErrorCode): +- 0x00: Нет ошибок +- 0x01: Ошибка датчика температуры +- 0x02: Ошибка датчика влажности +- 0x03: Ошибка компрессора +- 0x04: Ошибка вентилятора +- 0x05: Ошибка системы размораживания + +## Интеграция с Ballu AC контроллером + +### Преобразование режимов работы: +| ZCL System Mode | Ballu AC Mode | Описание | +|-----------------|---------------|----------| +| 0x00 (Off) | MODE_OFF | Выключено | +| 0x01 (Auto) | MODE_AUTO | Авторегулировка | +| 0x03 (Cool) | MODE_COOL | Охлаждение | +| 0x04 (Heat) | MODE_HEAT | Отопление | +| 0x08 (Dry) | MODE_DRY | Сушка | +| 0x07 (Fan Only) | MODE_FAN | Вентилятор | +| 0x09 (Sleep) | MODE_SLEEP | Режим сна | + +### Преобразование температуры: +- ZCL температура передается в 0.01°C единицах +- При отправке в MideaUART: значение/100 (пример: 2500 → 25.0°C) + +### Последовательность обработки команд: +1. Получить команду через Zigbee ZCL +2. Преобразовать в формат MideaUART Control structure +3. Отправить по UART в кондиционер +4. Получить статус от кондиционера +5. Отправить обновление по Zigbee (если изменились параметры) + +## Пример обработки команды охлаждения +```c +// Получено через Zigbee: system_mode = 0x03 (Cool), local_temperature = 2400 (24.00°C) +Control control; +control.mode = MODE_COOL; +control.targetTemp = 24.0f; // Преобразование из 0.01°C +control.modeChange = true; +control.tempChange = true; +ac.control(control); +``` \ No newline at end of file