Init
This commit is contained in:
81
Claude.md
Normal file
81
Claude.md
Normal 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
BIN
docs/.DS_Store
vendored
Normal file
Binary file not shown.
187
docs/Build system details.md
Normal file
187
docs/Build system details.md
Normal 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
131
docs/Hardware integration guide.md
Normal 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 в режим загрузки.
|
||||||
@@ -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
138
docs/protocol.md
Normal 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
122
docs/zcl_hvac.md
Normal 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);
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user