Mrixs/ballu-remote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Init

Browse Source
This commit is contained in:
Vladimir Zagainov
2026-07-05 18:21:29 +03:00
commit 6c237faadb
7 changed files with 805 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
Claude.md Normal file
View File

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

BIN
docs/.DS_Store vendored Normal file
View File

Binary file not shown.

187
docs/Build system details.md Normal file
View File

@@ -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` или автоматически, если менеджер сам разрешит пути.

131
docs/Hardware integration guide.md Normal file
View File

@@ -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 в режим загрузки.

146
docs/plans/2026-07-05-ballu-ac-esp32c6-controller-implementation.md Normal file
View File

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

138
docs/protocol.md Normal file
View File

@@ -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 мс

122
docs/zcl_hvac.md Normal file
View File

@@ -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);
```