Multi - AC (betta) and some AI generated docs (not fully verefied)

2026-03-14 05:16:31 +03:00 · 2026-03-01 23:43:40 +03:00
parent 8db9e551ff
commit c5427251fc
32 changed files with 9688 additions and 90 deletions
--- a/documentation/modules_description.md
+++ b/documentation/modules_description.md
@@ -0,0 +1,864 @@
+# LightHub: Описание модулей и компонентов
+
+> Полное инженерное описание всех основных модулей LightHub с примерами конфигурации и протоколами управления.
+> Предназначено для разработчиков, интеграторов и системных инженеров.
+
+---
+
+## Содержание
+
+1. [Выходные модули (Out)](#выходные-модули)
+   - [out_Multivent](#out_multivent---многоканальный-кондиционер-вентиляция)
+   - [out_AC](#out_ac---управление-кондиционером)
+   - [out_PID](#out_pid---пид-регулятор)
+   - [out_Relay](#out_relay---электромагнитное-реле)
+   - [out_PWM](#out_pwm---широтно-импульсная-модуляция)
+   - [out_DMX](#out_dmx---dmx512-управление-светом)
+   - [out_Motor](#out_motor---управление-двигателем)
+   - [out_Elevator](#out_elevator---управление-лифтом)
+   - [out_Humidifier](#out_humidifier---управление-увлажнителем)
+   - [out_Counter](#out_counter---счётчик-импульсов)
+   - [out_SPILed](#out_spiled---управление-светодиодами)
+   - [out_Mercury](#out_mercury---счётчик-меркурий)
+   - [out_UARTBridge](#out_uartbridge---uart-мост)
+
+2. [Входные модули (In)](#входные-модули)
+   - [in_CCS811_HDC1080](#in_ccs811_hdc1080---датчик-качества-воздуха)
+
+---
+
+# Выходные модули
+
+## out_Multivent — Многоканальный кондиционер/вентиляция
+
+### Описание
+
+Модуль управления многозональными системами кондиционирования воздуха и центральной вентиляции.
+
+**Основные функции:**
+- Управление центральной установкой (компрессор, вентилятор)
+- Независимое регулирование температуры для каждой зоны/комнаты
+- PID-контроллеры для стабилизации микроклимата
+- Автоматическая балансировка воздушного потока между зонами
+- Каскадное управление задвижками и затворами
+
+### Тип в JSON
+```
+[14, ["device_name", {zones_and_settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"multizone_ac": [
+  14,
+  [
+    "haier",
+    {
+      "": {
+        "val": {"emit": "home/ac/temp"},
+        "mode": {"emit": "home/ac/mode"}
+      },
+      "bedroom": {
+        "fan": {"emit": "home/bedroom/fan"},
+        "cmd": {"emit": "home/bedroom/cmd"},
+        "out": {"emit": "home/bedroom/out"},
+        "V": 40,
+        "pid": [1.0, 0.05, 0.02, 5.0],
+        "set": {"emit": "home/bedroom/setpoint"},
+        "val": {"emit": "home/bedroom/temp"}
+      }
+    }
+  ]
+]
+```
+
+### Ключевые параметры
+
+| Параметр | Тип | Описание |
+|----------|-----|---------|
+| `V` | int | Номинальный объём воздуха (м³/ч) |
+| `pid` | [Kp, Ki, Kd, dT] | Коэффициенты PID-регулятора |
+| `set` | float | Требуемая температура |
+| `val` | float | Текущая температура |
+| `fan` | int (0-255) | Открытие вентилятора |
+| `cmd` | int | Команда (OFF, ON, HEAT, COOL, FAN, etc.) |
+| `out` | int (0-255) | Выход задвижки |
+
+### Режимы команд
+
+- `CMD_OFF` (0) — отключено
+- `CMD_ON` (1) — включено
+- `CMD_HEAT` (2) — нагрев
+- `CMD_COOL` (3) — охлаждение
+- `CMD_FAN` (4) — вентиляция
+- `CMD_DRY` (5) — осушение
+
+### Примеры
+
+Полное описание с примерами: [multivent_module_description.md](multivent_module_description.md)
+
+---
+
+## out_AC — Управление кондиционером
+
+### Описание
+
+Управление одиночным кондиционером через Modbus или прямое управление через протокол AC (18-100 байт).
+
+**Основные функции:**
+- Управление режимом (HEAT, COOL, FAN, DRY, AUTO)
+- Управление скоростью вентилятора (LOW, MEDIUM, HIGH, AUTO)
+- Управление температурой
+- Поддержка качания жалюзей (SWING)
+- Блокировка пульта
+- Режим QUIET (тихий режим)
+
+### Тип в JSON
+```
+[128, ["device_name", {parameters}]]
+```
+
+### Формат конфигурации
+
+```json
+"air_conditioner": [
+  128,
+  [
+    "haier",
+    {
+      "pwr": {"emit": "home/ac/power"},
+      "acmode": {"emit": "home/ac/mode"},
+      "set": {"emit": "home/ac/setpoint"},
+      "fan": {"emit": "home/ac/fan_speed"},
+      "swing": {"emit": "home/ac/swing"},
+      "lock": {"emit": "home/ac/lock"},
+      "$temp": {"emit": "home/ac/temp"}
+    }
+  ]
+]
+```
+
+### Параметры управления
+
+| Параметр | Значение | Описание |
+|----------|----------|---------|
+| `pwr` | ON/OFF | Питание компрессора |
+| `acmode` | COOL/HEAT/FAN/DRY/AUTO | Режим |
+| `set` | 16-32°C | Установка температуры |
+| `fan` | LOW/MED/HIGH/AUTO | Скорость вентилятора |
+| `swing` | ON/OFF | Качание жалюзей |
+| `$temp` | читаемый | Текущая температура воздуха |
+
+---
+
+## out_PID — PID-регулятор
+
+### Описание
+
+Универсальный PID-контроллер для стабилизации любых процессов (температура, влажность, давление и т.д.).
+
+**Основные функции:**
+- Независимое PID-регулирование с тремя коэффициентами
+- Регулируемый период сэмплирования
+- Будильник при выходе за пределы диапазона
+- Защита от интегральной раскрутки
+
+### Тип в JSON
+```
+[17, ["input_topic", "setpoint", "output_topic"]]
+```
+
+### Формат конфигурации
+
+```json
+"temperature_controller": [
+  17,
+  [
+    {"emit": "sensors/room/temp"},
+    21.5,
+    {"emit": "heating/power"}
+  ]
+]
+```
+
+### JSON с полными параметрами
+
+```json
+"pid_climate": [
+  17,
+  {
+    "in": {"emit": "sensors/temp"},
+    "set": 22.0,
+    "out": {"emit": "hvac/power"},
+    "Kp": 1.0,
+    "Ki": 0.05,
+    "Kd": 0.02,
+    "dT": 5,
+    "alarm": 2.0,
+    "alarmTimeout": 300
+  }
+]
+```
+
+### Параметры
+
+| Параметр | Тип | Диапазон | Описание |
+|----------|-----|----------|---------|
+| `Kp` | float | 0.1—10.0 | Пропорциональный коэффициент |
+| `Ki` | float | 0.0—1.0 | Интегральный коэффициент |
+| `Kd` | float | 0.0—1.0 | Дифференциальный коэффициент |
+| `dT` | int | 1—60 | Период сэмплирования (сек) |
+| `alarm` | float | - | Порог срабатывания будильника |
+| `alarmTimeout` | int | - | Время до срабатывания будильника (сек) |
+
+---
+
+## out_Relay — Электромагнитное реле
+
+### Описание
+
+Управление электромагнитными реле через цифровой выход микроконтроллера.
+
+**Основные функции:**
+- Включение/отключение нагрузки
+- Поддержка инвертированной логики
+- Управление периодом переключения
+
+### Тип в JSON
+```
+[1, [pin, {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"pump_relay": [
+  1,
+  [
+    33,
+    {
+      "inverted": false
+    }
+  ]
+]
+```
+
+### Параметры
+
+| Параметр | Тип | Описание |
+|----------|-----|---------|
+| `pin` | int | Номер GPIO-пина |
+| `inverted` | bool | Инвертировать логику (false = HIGH=ON) |
+| `period` | int | Период срабатывания (мс) |
+
+### Управление
+
+```
+Отправить: home/pump_relay
+Значение: 0 (OFF) или 1 (ON)
+```
+
+---
+
+## out_PWM — Широтно-импульсная модуляция
+
+### Описание
+
+Управление PWM для регулирования яркости светодиодов, скорости двигателей, интенсивности нагрузок.
+
+**Основные функции:**
+- Регулирование от 0% до 100%
+- Поддержка RGB-управления (в base-классе colorChannel)
+- Частотные настройки
+
+### Тип в JSON
+```
+[9, [channel, freq, {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"led_brightness": [
+  9,
+  [
+    5,
+    1000,
+    {}
+  ]
+]
+```
+
+### Управление
+
+```
+Отправить: home/led/brightness
+Значение: 0-255 (0=0%, 255=100%)
+```
+
+---
+
+## out_DMX — DMX512 управление светом
+
+### Описание
+
+Управление световыми приборами по протоколу DMX512 (театральное и архитектурное освещение).
+
+**Основные функции:**
+- Поддержка до 512 каналов
+- Управление цветом и интенсивностью
+- Синхронизированное обновление
+
+### Тип в JSON
+```
+[11, [channel_list, {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"stage_lighting": [
+  11,
+  [
+    [1, 2, 3, 4],
+    {}
+  ]
+]
+```
+
+### Управление
+
+```
+Отправить: home/lighting/color
+Значение: {"r":255, "g":128, "b":0}
+```
+
+---
+
+## out_Motor — Управление двигателем
+
+### Описание
+
+Управление моторами с обратной связью по положению (рольставни, жалюзи, шторы).
+
+**Основные функции:**
+- Управление направлением (вверх/вниз)
+- Обратная связь по положению
+- Защита от перегрузки по времени
+- Плавное позиционирование
+
+### Тип в JSON
+```
+[3, [pin_up, pin_down, pin_feedback, {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"roller_blind": [
+  3,
+  [
+    32,
+    33,
+    34,
+    {
+      "maxOnTime": 120000,
+      "feedbackOpen": 0,
+      "feedbackClosed": 1023,
+      "inverted": false
+    }
+  ]
+]
+```
+
+### Параметры
+
+| Параметр | Тип | Описание |
+|----------|-----|---------|
+| `pinUp` | int | GPIO для движения вверх |
+| `pinDown` | int | GPIO для движения вниз |
+| `pinFeedback` | int | GPIO обратной связи (аналоговый) |
+| `maxOnTime` | int | Макс. время работы (мс), 120000 = 2 мин |
+| `feedbackOpen` | int | Значение обратной связи (открыто) |
+| `feedbackClosed` | int | Значение обратной связи (закрыто) |
+
+### Команды
+
+| Команда | Значение | Описание |
+|---------|----------|---------|
+| UP | -1 | Поднять |
+| DOWN | 1 | Опустить |
+| STOP | 0 | Остановить |
+| Позиция | 0-255 | Установить позицию (0=открыто, 255=закрыто) |
+
+---
+
+## out_Elevator — Управление лифтом
+
+### Описание
+
+Управление лифтом через UART или интерфейс вызова. Синхронизация между контроллерами через сетевой мост.
+
+**Основные функции:**
+- Управление вызовом лифта
+- Передача команды на нужный этаж
+- Контроль состояния лифта
+- Дублирование по UART
+
+### Тип в JSON
+```
+[ELEVATOR_TYPE, ["uart_port", {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"elevator": [
+  50,
+  [
+    "Serial1",
+    {
+      "baud": 9600,
+      "floors": 5
+    }
+  ]
+]
+```
+
+### Параметры UART
+
+| Параметр | Значение | Описание |
+|----------|----------|---------|
+| `baud` | 9600-115200 | Скорость UART |
+| `serialParam` | 8N1 | Параметры кадра |
+
+---
+
+## out_Humidifier — Управление увлажнителем
+
+### Описание
+
+Управление промышленным ультразвуковым или парогенерирующим увлажнителем с контролем давления и защитой от отказов.
+
+**Основные функции:**
+- Контроль давления в баке
+- Управление электромагнитными клапанами
+- Защита от перепада давления
+- Автоматическая очистка (FLUSH)
+- Состояния готовности и отказа
+
+### Тип в JSON
+```
+[HUMIDIFIER_TYPE, [pump_pin, valve_pin, pressure_pin, {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"mist_humidifier": [
+  40,
+  [
+    25,
+    26,
+    35,
+    {
+      "minPressure": 400,
+      "maxPressure": 600,
+      "flushInterval": 125000
+    }
+  ]
+]
+```
+
+### Состояния
+
+| Состояние | Код | Описание |
+|-----------|-----|---------|
+| H_UNKNOWN | 0 | Неизвестное |
+| H_READY | 1 | Готов к работе |
+| H_PREPARE_FOR_START | 2 | Подготовка к пуску |
+| H_MOTOR_ON | 4 | Мотор работает |
+| H_OPERATE | 5 | В режиме увлажнения |
+| H_FLUSH | 8 | Промывка системы |
+| H_FAULT_PRESSURE | -1 | Ошибка давления |
+| H_FAULT_OVERPRESSURE | -3 | Перепад давления |
+
+---
+
+## out_Counter — Счётчик импульсов
+
+### Описание
+
+Счётчик импульсов для контроля расхода (воды, газа) или подсчета событий.
+
+**Основные функции:**
+- Подсчет импульсов
+- Накопление значений
+- Фильтрация дребезга контактов
+- Калибровка по расходу
+
+### Тип в JSON
+```
+[6, [input_pin, {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"water_meter": [
+  6,
+  [
+    14,
+    {
+      "pulsePerLiter": 10,
+      "debounce": 100
+    }
+  ]
+]
+```
+
+### Параметры
+
+| Параметр | Тип | Описание |
+|----------|-----|---------|
+| `pulsePerLiter` | int | Кол-во импульсов на 1 литр (для расчета) |
+| `debounce` | int | Фильтрация дребезга (мс) |
+
+---
+
+## out_SPILed — Управление светодиодами
+
+### Описание
+
+Управление адресуемыми RGB-светодиодами (WS2812, APA102) через SPI или GPIO.
+
+**Основные функции:**
+- Независимое управление каждым светодиодом
+- RGB-цветовая палитра
+- Эффекты и анимации
+- Поддержка Adafruit и FastLED библиотек
+
+### Тип в JSON
+```
+[10, [pin, numLeds, ledsType, {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"led_strip": [
+  10,
+  [
+    13,
+    30,
+    0,
+    {}
+  ]
+]
+```
+
+### Параметры
+
+| Параметр | Тип | Описание |
+|----------|-----|---------|
+| `pin` | int | GPIO пин (данные) |
+| `numLeds` | int | Количество светодиодов |
+| `ledsType` | int | Тип: 0=WS2812 (NeoPixel), 1=APA102 |
+
+### Управление
+
+```
+Отправить: home/leds/color
+Значение: {"r":255, "g":0, "b":128}
+
+Отправить: home/leds/brightness
+Значение: 0-255
+```
+
+---
+
+## out_Mercury — Счётчик Меркурий
+
+### Описание
+
+Управление и опрос электросчётчиков серии Меркурий через UART Modbus RTU.
+
+**Основные функции:**
+- Чтение энергопотребления (активная/реактивная)
+- Получение тарифных данных
+- Многозонное чтение (пиковое, полупиковое, ночное)
+- Контроль связи и состояния счётчика
+
+### Тип в JSON
+```
+[MERCURY_TYPE, ["device_address", {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"electricity_meter": [
+  45,
+  [
+    "1",
+    {
+      "baud": 9600,
+      "pollingInterval": 60000
+    }
+  ]
+]
+```
+
+### Параметры Modbus
+
+| Параметр | Значение | Описание |
+|----------|----------|---------|
+| `baud` | 9600 | Скорость UART |
+| `pollingInterval` | мс | Интервал опроса |
+
+### Получаемые значения
+
+```
+home/meter/total_power     - Общее потребление (кВт·ч)
+home/meter/peak_power      - Пиковое потребление
+home/meter/halfpeak_power  - Полупиковое потребление
+home/meter/night_power     - Ночное потребление
+```
+
+---
+
+## out_UARTBridge — UART мост
+
+### Описание
+
+Создание прозрачного двунаправленного моста между двумя UART портами с сохранением данных и логированием.
+
+**Основные функции:**
+- Прозрачная маршрутизация UART↔UART
+- Буферизация пакетов (до 64 байт)
+- Логирование трафика
+- Поддержка разных скоростей на каждом порту
+
+### Тип в JSON
+```
+[UARTBRIDGE_TYPE, ["portA", "portB", {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"uart_gateway": [
+  55,
+  [
+    "Serial1",
+    "Serial2",
+    {
+      "baudA": 9600,
+      "baudB": 19200,
+      "paramA": "8N1",
+      "paramB": "8N1"
+    }
+  ]
+]
+```
+
+### Параметры
+
+| Параметр | Тип | Описание |
+|----------|-----|---------|
+| `baudA/B` | int | Скорость портов (9600-115200) |
+| `paramA/B` | string | Формат кадра (8N1, 8E1, 8O1) |
+
+---
+
+# Входные модули
+
+## in_CCS811_HDC1080 — Датчик качества воздуха
+
+### Описание
+
+Комбинированный датчик для измерения качества воздуха с использованием:
+- **HDC1080** — датчик температуры и влажности (I2C)
+- **CCS811** — датчик CO₂ и TVOC (I2C)
+
+**Основные функции:**
+- Измерение температуры (-40...125°C)
+- Измерение влажности (0-100%)
+- Измерение eCO₂ (400-8192 ppm)
+- Измерение TVOC (0-1187 ppb)
+- Температурная компенсация
+
+### Тип в JSON
+```
+[SENSOR_TYPE, ["i2c_address", {settings}]]
+```
+
+### Формат конфигурации
+
+```json
+"air_quality": [
+  100,
+  [
+    "0x5A",
+    {
+      "tempOffset": 0.0,
+      "humidityOffset": 0.0,
+      "co2Offset": 0,
+      "pollInterval": 10000
+    }
+  ]
+]
+```
+
+### Выводимые параметры
+
+| Параметр | Единица | Диапазон | Описание |
+|----------|---------|----------|---------|
+| `temperature` | °C | -40...125 | Температура воздуха |
+| `humidity` | % | 0...100 | Относительная влажность |
+| `eCO2` | ppm | 400...8192 | Эквивалентный CO₂ |
+| `TVOC` | ppb | 0...1187 | Летучие органические соединения |
+
+### Адреса I2C
+
+| Устройство | Адрес | Описание |
+|-----------|-------|---------|
+| CCS811 | 0x5A | По умолчанию (WAK на GND) |
+| CCS811 | 0x5B | Альтернативный (WAK на VDD) |
+| HDC1080 | 0x40 | Всегда фиксирован |
+
+### MQTT маршрутизация
+
+```json
+{
+  "temp": {"emit": "home/sensors/air/temperature"},
+  "humidity": {"emit": "home/sensors/air/humidity"},
+  "co2": {"emit": "home/sensors/air/co2"},
+  "tvoc": {"emit": "home/sensors/air/tvoc"}
+}
+```
+
+### Примеры использования
+
+#### Простой мониторинг качества воздуха
+
+```json
+"room_air_sensor": [
+  100,
+  [
+    "0x5A",
+    {
+      "emit": "home/sensors/living_room/air"
+    }
+  ]
+]
+```
+
+#### С калибровкой смещений
+
+```json
+"calibrated_sensor": [
+  100,
+  [
+    "0x5A",
+    {
+      "tempOffset": -2.5,
+      "humidityOffset": 5.0,
+      "co2Offset": 50,
+      "pollInterval": 30000,
+      "emit": "sensors/hvac/inlet"
+    }
+  ]
+]
+```
+
+---
+
+## Сводная таблица типов модулей
+
+| Модуль | Тип | Назначение | Управление |
+|--------|-----|-----------|-----------|
+| out_Multivent | 14 | Многоканальный кондиционер | PID + MQTT |
+| out_AC | 128 | Одиночный кондиционер | Modbus/прямой протокол |
+| out_PID | 17 | PID-регулятор | MQTT |
+| out_Relay | 1 | Электромагнитное реле | GPIO |
+| out_PWM | 9 | ШИМ-управление | GPIO-PWM |
+| out_DMX | 11 | DMX512 освещение | DMX512 |
+| out_Motor | 3 | Управление двигателем | GPIO-пары |
+| out_Elevator | 50 | Управление лифтом | UART |
+| out_Humidifier | 40 | Управление увлажнителем | GPIO + датчики |
+| out_Counter | 6 | Счётчик импульсов | GPIO-счёт |
+| out_SPILed | 10 | Адресуемые светодиоды | SPI/GPIO |
+| out_Mercury | 45 | Электросчётчик | Modbus RTU |
+| out_UARTBridge | 55 | UART-мост | UART↔UART |
+| in_CCS811_HDC1080 | 100 | Качество воздуха | I2C |
+
+---
+
+## Общие принципы конфигурации
+
+### 1. Подключение MQTT
+
+Все параметры с полем `emit` автоматически публикуются в MQTT:
+
+```json
+"parameter": {
+  "emit": "home/device/parameter"
+}
+```
+
+### 2. Управление из MQTT
+
+Отправка значения:
+```
+mqtt publish home/device/parameter 128
+```
+
+### 3. Использование массивов
+
+Для нескольких параметров:
+```json
+[
+  {"emit": "topic1"},
+  {"emit": "topic2"},
+  {"emit": "topic3"}
+]
+```
+
+### 4. Служебные параметры
+
+- `@V` (null) — не публиковать значения
+- `@S` (null) — не публиковать при сохранении
+- `@C` — служебное, не использовать
+
+---
+
+## Диагностика проблем
+
+### Модуль не инициализируется
+
+Проверить:
+1. Конфигурация JSON синтаксически корректна
+2. GPIO-пины не конфликтуют
+3. I2C/UART устройства подключены
+4. Библиотеки установлены
+
+### Нет связи с устройством
+
+1. Проверить скорость UART (baud)
+2. Проверить подключение TX/RX
+3. Проверить адрес Modbus/I2C
+4. Посмотреть лог сообщений
+
+### Неустойчивые значения PID
+
+1. Снизить Kp (коэффициент пропорциональности)
+2. Увеличить dT (период сэмплирования)
+3. Добавить Kd (демпфирование)
+
+---
+
+**Версия документа:** 1.0  
+**Дата:** 2026-01-21  
+**Статус:** Утверждено