docs: audit references and examples against source code

Cross-checked all channel types, suffixes, commands, JSON config formats, HTTP/MQTT API examples and driver docs with the actual code; fixed the discrepancies (channel numbers 0..23, real command set, real suffix handling, CAN 50 kbit/s, DRY/Freeze sprinkler semantics, AC subitems, multivent zones, Mercury/Motor/Counter configs, etc.)
2026-10-28 11:15:00 +00:00 · 2026-10-03 00:41:16 +03:00
parent 6a10d85c55
commit b90325bfef
12 changed files with 7567 additions and 0 deletions
@@ -0,0 +1,336 @@
+# LightHub: Справочник типов каналов (Items)
+
+> **Инженерный справочник** соответствия цифровых кодов типов каналов к текстовым обозначениям и функциональности.
+> Актуально для версии ядра с типами DMX (0) до SPRINKLR (23).
+> Источник: [lighthub/item.h](../../lighthub/item.h)
+
+---
+
+## Таблица типов каналов
+
+| Код | Текстовое обозначение | Английское название | Описание | Конфигурация |
+|-----|----------------------|---------------------|---------|--------------|
+| **0** | `DMX` | DMX Dimmer | DMX 512 выход с регулировкой яркости (1-5 каналов (3=RGB, 4=RGBW, 5=RGBWW)) | Номер DMX канала или массив номеров |
+| **1** | `DMXRGBW` | DMX RGBW | DMX 512 выход RGB+White (4 канала) | Номер стартового DMX канала |
+| **2** | `DMXRGB` | DMX RGB | DMX 512 выход RGB (3 канала) | Номер стартового DMX канала |
+| **3** | `PWM` | PWM Output | Широтно-импульсная модуляция на GPIO (1-5 каналов) | Номер GPIO пина или массив GPIO пинов |
+| **4** | `MBUSDIM` | Modbus AC Dimmer (Legacy) | Управление AC-диммером через Modbus RTU | `[адрес, регистр, маска, макс_значение, тип_регистра]` |
+| **5** | `THERMO` | Simple Thermostat | ON/OFF термостат с гистерезисом | `[GPIO_pin, целевая_температура_°C]` |
+| **6** | `RELAY` | Relay Output | Электромагнитное реле ON/OFF | GPIO пин |
+| **7** | `GROUP` | Group Channel | Логическая группа каналов для синхронного управления | Массив строк с именами каналов |
+| **8** | `VCTEMP` | Vacom PID Thermo | Температура из VC-канала Vacom (ссылка на item типа CH_VC) | `[имя_канала_VC]` (строка) |
+| **9** | `MBUSVC` | Vacom Modbus Motor | Управление мотор-регулятором вентилятора Vacom через Modbus | `[modbus_адрес, "имя_объекта"]` |
+| **10** | `ACHAIER` | Air Conditioner Haier | Управление кондиционером Haier по проприетарному UART-протоколу (9600) | `[порт_serial(0-3)]` |
+| **11** | `SPILED` | SPI LED Strip | Управление NeoPixel LED лентой (WS2812B и совместимые, один data-пин) | `[data_pin, numLeds(дефолт 43), ledsType]` |
+| **12** | `MOTOR` | Motorized Air Gateway | Управление моторной задвижкой с обратной связью (позиция 0-255) | `[pinUp, pinDown, pinFeedback, fbOpen, fbClosed, maxOnTime_ms(дефолт 10000)]` |
+| **13** | `PID` | PID Regulator | Универсальный PID-контроллер для регулирования процессов | `[Kp, Ki, Kd, dT, timeout, alarm_val, min_out, max_out]` |
+| **14** | `MBUS` | Universal Modbus | Универсальный Modbus канал с шаблонизацией | `[адрес, шаблон, параметры]` |
+| **15** | `UARTBRDG` | UART Bridge | Мост между двумя UART портами с отладкой через UDP | `{serial, baud, ip, port, hd, log, bond}` |
+| **16** | `RELAYPWM` | Relay PWM | Медленный PWM через реле для инертных систем | `[GPIO_pin, период_цикла_сек(дефолт 5)]` |
+| **17** | `DMXRGBWW` | DMX RGBWW | DMX 512 выход RGB + теплый белый + холодный белый (5 каналов) | Номер стартового DMX канала |
+| **18** | `VENTS` | Multiroom Ventilation | Многозональная вентиляция с каскадным управлением | `[объект_зон]` (без Modbus-адреса) |
+| **19** | `ELEVATOR` | Elevator Control | Управление лифтом | `{"serial":"8N1","baud":19200,"log":...}` (компилируется с ELEVATOR_ENABLE) |
+| **20** | `COUNTER` | Generic Counter | Счётчик импульсов (электроэнергия, газ, вода) | `[коэффициент_импульса, период_автосуммирования_сек]` |
+| **21** | `HUM` | Humidifier | Управление увлажнителем воздуха (только один в системе) | `[[pumpPin, flushPin, pressurePin, maxPumpTime, idleTime, capacity, minLevel, startLevel], {зоны_краны}, motorExec, faultExec]` |
+| **22** | `MERCURY` | Mercury Energy Meter | Счётчик энергии Mercury по RS485/Modbus | `[адрес, baud, "8N1", уровень_доступа, пароль, pollingInterval_ms(дефолт 10000)]` |
+| **23** | `SPRINKLR` | Irrigation System | Система автоматического полива с многозональным управлением | `[23, {конфиг}]` или `[23, имя, {зоны}]` |
+
+> **Примечание о доступности по целям сборки** (из build-flags): SPRINKLER — due, esp32-wifi, esp32c3-wifi, lighthub21, nrf52840; MERCURY — due, lighthub21, stm32; ELEVATOR — только custom-build mega2560-optiboot; HUMIDIFIER — только custom-build lighthub21; UARTBRIDGE — отключён (закомментирован) во всех стандартных build-flags.
+
+---
+
+## Альтернативное определение типа (текстовое)
+
+Вместо числового кода можно использовать текстовое обозначение типа:
+
+```json
+"lamp1": [0, 1]              // числовой код
+"lamp1": ["DMX", 1]          // текстовое обозначение
+"relay1": ["RELAY", 10]      // текстовое обозначение
+```
+
+---
+
+## Примеры конфигурации по типам
+
+### CH_DIMMER (0) - DMX выход с регулировкой
+
+```json
+"dimmer1": [0, 5],           // DMX канал 5
+"dimmer2": [0, [1, 2, 3, 4]] // 4-канальный (RGBW), DMX 1-4
+```
+
+### CH_RGBW (1) - DMX RGB+White
+
+```json
+"rgb_light": [1, 10]         // RGB+W на DMX 10-13
+```
+
+### CH_RGB (2) - DMX RGB
+
+```json
+"rgb_light": [2, 15]         // RGB начиная с 15-го (на DMX 15-17)
+```
+
+### CH_PWM (3) - GPIO PWM
+
+```json
+"pwm1": [3, 9],              // PWM на GPIO pin 9
+"pwm_4ch": [3, [11, 12, 13, 14]] // 4-х канальный PWM
+```
+
+### CH_MODBUS (4) - AC Dimmer (Legacy)
+
+```json
+"mbus_dim": [4, [96, 0, 0, 255]]
+// Адрес: 96
+// Регистр: 0
+// Маска: 0 (LSB)
+// Макс значение: 255
+```
+
+### CH_THERMO (5) - Термостат
+
+```json
+"thermo_bath": [5, 24, 33]   // GPIO 24, уставка 33°C
+```
+
+### CH_RELAY (6) - Реле
+
+```json
+"relay1": [6, 23],           // Реле на GPIO 23
+"relay2": ["RELAY", 28, 1, 1] // Реле, по умолчанию ON
+```
+
+### CH_GROUP (7) - Группа каналов
+
+```json
+"lights_all": [7, [
+  "lamp1", "lamp2", "lamp3",
+  "rgb1", "rgb2"
+]],
+"lights_bedroom": [7, ["lamp1", "rgb1"]]
+```
+
+### CH_VCTEMP (8) - Vacom PID терморегулятор
+
+```json
+"fm_t": [8, "fm"]            // строка-имя item типа CH_VC (9)
+```
+
+### CH_VC (9) - Vacom мотор регулятор
+
+```json
+"fan_speed": [9, [96, "a_ext"]]   // Modbus адрес 96, "имя_объекта" (строка)
+```
+
+### CH_AC (10) - Кондиционер Haier
+
+```json
+"ac_main": [10, 1]             // номер порта serial (0-3)
+// подканалы: fan (LOW/MEDIUM/HIGH), set (16-40), temp, cmd
+// также доступны подканалы lock/swing/queit/raw (/mode — число, текстовые режимы — в /cmd)
+```
+
+### CH_SPILED (11) - SPI LED лента
+
+```json
+"led_strip": [11, [7, 8]]    // data-пин GPIO7, 8 светодиодов
+```
+
+### CH_MOTOR (12) - Моторная задвижка с обратной связью
+
+```json
+"gate_motor": [12, [9, 10, 11, 0, 255, 30000]]
+// pinUp: 9, pinDown: 10, pinFeedback: 11 (аналоговый)
+// fbOpen: 0, fbClosed: 255, maxOnTime_ms: 30000
+```
+
+### CH_PID (13) - PID регулятор
+
+```json
+"pid_temp": [13, [
+  [1.0, 0.05, 0.02, 5.0, 3600, 50, 0, 255],
+  {"emit": "pid/output"},
+  {"emit": "pid/cascade"}
+]]
+// Kp=1.0, Ki=0.05, Kd=0.02
+// dT=5.0 сек, alarm timeout=3600 сек (при отсутствии измерений), alarm value на выходе=50
+// min_out=0, max_out=255
+```
+
+### CH_MBUS (14) - Универсальный Modbus
+
+```json
+"mbus_generic": [14, [96, "temperature_sensor", {
+  "temp": {"emit": "sensors/temp"},
+  "humidity": {"emit": "sensors/humidity"}
+}]]
+```
+
+### CH_UARTBRIDGE (15) - UART мост
+
+```json
+"uart_debug": [15, {
+  "serial": "8N1",
+  "baud": 9600,
+  "ip": "192.168.1.100",
+  "port": 9001,
+  "log": true
+}]
+```
+
+### CH_RELAYX (16) - Медленный PWM через реле
+
+```json
+"relay_pwm": [16, [22, 60]]  // GPIO 22, период цикла 60 сек
+```
+
+### CH_RGBWW (17) - DMX RGBWW
+
+```json
+"led_warm_cold": [17, 30]    // DMX 30-34 (RGBWW, 5 каналов)
+```
+
+### CH_MULTIVENT (18) - Многозональная вентиляция
+
+```json
+"multivent_system": [18, {
+  "": {"val": {"emit": "main/temp"}},
+  "bedroom": {
+    "val": {"emit": "bed/temp"},
+    "fan": {"emit": "bed/fan"},
+    "V": 40,
+    "pid": [1.0, 0.05, 0.02, 5.0]
+  }
+}]
+```
+
+### CH_COUNTER (20) - Счётчик по импульсам/времени
+
+```json
+"energy_meter": [20, [0.02, 1.2]] // коэфф 0.02, период автосуммирования 1.2 с
+"gas_counter": [20, 0]             // без калибровки
+```
+
+### CH_HUMIDIFIER (21) - Увлажнитель
+
+```json
+"humidifier1": [21, [13, 14, 15, 120, 15, 50, 5, 25]]
+// [pumpPin, flushPin, pressurePin, maxPumpTime, idleTime, capacity, minLevel, startLevel]
+// (только один humidifier в системе; компилируется с HUMIDIFIER_ENABLE)
+```
+
+### CH_MERCURY (22) - Счётчик энергии Mercury
+
+```json
+"mercury_meter": [22, [1, 9600, "8N1", 2, "123456", 10000]]
+// Адрес: 1
+// Baud: 9600
+// Формат: "8N1"
+// Уровень доступа: 2
+// Пароль: "123456" (строка из 6 цифр или массив 6 цифр)
+// Интервал опроса: 10000 мс (дефолт)
+```
+
+### CH_SPRINKLR (23) - Система полива
+
+```json
+"irrigation_system": [23, {
+  "": {                                // корневой объект: пины платы
+    "vIn": 10, "rDren": 11, "rPump": 12,
+    "wMax": 13, "wMin": 14,
+    "fbDren": 15, "fbPump": 16, "wCtr": 17,
+    "onFault": {"exec": "alarm"}
+  },
+  "north_zone": {"pin": 20},           // зона: только pin
+  "south_zone": {"pin": 21}            // cmd/val/set создаются автоматически
+}]
+// команды: ON, OFF, DRY, RESET
+```
+
+---
+
+## Заметки по конфигурации
+
+### Форматы параметров конфигурации
+
+1. **Простой формат** (число или строка):
+   ```json
+   "item": [тип, параметр]
+   ```
+
+2. **Массив параметров**:
+   ```json
+   "item": [тип, [параметр1, параметр2, параметр3]]
+   ```
+
+3. **С начальным значением и командой**:
+   ```json
+   "item": [тип, конфигурация, начальное_значение, начальная_команда]
+   ```
+
+### Поддерживаемые режимы (для каналов с управлением):
+
+- `ON` / `OFF` — включение/отключение
+- `REST` / `TOGGLE` / `HALT` — включение после HALT / переключение / выключение
+- `XON` / `XOFF` — принудительное включение/выключение
+- `INCREASE N` / `DECREASE N` — увеличение/уменьшение (шаг по умолчанию 5)
+- `ENABLE` / `DISABLE` / `FREEZE` / `UNFREEZE` — включение/отключение и заморозка канала
+- `AUTO` / `HEAT_COOL` / `HEAT` / `COOL` / `DRY` / `FAN_ONLY` — режимы (кондиционер/термостат/вентиляция)
+- `HIGH` / `MEDIUM` / `LOW` — скорость вентилятора
+- `RGB` / `HSV` / `RESET` — цветовые команды (для RGB каналов) и сброс
+
+Полный список команд: ON OFF REST TOGGLE HALT XON XOFF INCREASE DECREASE ENABLE DISABLE UNFREEZE FREEZE AUTO FAN_ONLY HIGH MEDIUM LOW HEAT_COOL HEAT COOL DRY RGB HSV RESET.
+
+---
+
+## Визуализация иерархии
+
+```
+ITEMS (каналы)
+├── Digital Output (Реле)
+│   ├── CH_RELAY  "RELAY"(6)
+│   ├── CH_THERMO "THERMO"(5)
+│   ├── CH_RELAYX "RELAYPWM"(16)
+│   └── CH_MOTOR  "MOTOR"(12)
+│
+├── DMX
+│   ├── CH_DIMMER "DMX"(0)
+│   ├── CH_RGBW   "DMXRGBW"(1)
+│   ├── CH_RGB    "DMXRGB"(2)
+│   └── CH_RGBWW  "DMXRGBWW"(17)
+│
+├── Analog Output (PWM)
+│   └──  CH_PWM "PWM"(3)
+|
+├── Каналы с множеством подканалов
+│   ├── CH_SPILED     "SPILED"(11)
+│   ├── CH_MULTIVENT  "VENTS"(18)
+│   ├── CH_SPRINKLER  "SPRINKLR"(23)
+│   └── CH_HUMIDIFIER "HUM"(21)
+│
+├── Modbus/RS485 Slaves/UART
+│   ├── CH_MODBUS "MBUSDIM"(4) - Legacy
+│   ├── CH_MBUS   "MBUS"(14) - Universal
+│   ├── CH_VCTEMP "VCTEMP"(8)
+│   ├── CH_VC     "MBUSVC"(9)
+│   ├── CH_AC     "ACHAIER"(10)
+│   └── CH_MERCURY "MERCURY"(22)
+│
+├── System/Special
+│   ├── CH_GROUP     "GROUP"(7)
+│   ├── CH_PID       "PID"(13)
+│   ├── CH_COUNTER   "COUNTER"(20)
+│   ├── CH_UARTBRIDGE "UARTBRDG"(15)
+│   └── CH_ELEVATOR  "ELEVATOR"(19)
+```
+
+---
+
+## Полезные ссылки
+
+- [Полное описание конфигурации](light_hub_полное_инженерное_описание_json_конфигурации_v2.md)
+- [Описание модулей](modules_description.md)
+- [Исходный код item.h](../../lighthub/item.h)
+- [Исходный код item.cpp](../../lighthub/item.cpp)
@@ -0,0 +1,688 @@
+# LightHub: Полное инженерное описание JSON‑конфигурации контроллера
+
+> **Документ актуален для ядра LightHub с типами каналов CH_DIMMER (0) - CH_SPRINKLER (23)**
+> 
+> Предназначен для инженеров автоматизации, интеграторов и разработчиков.
+> Основан **строго** на официальной документации LazyHome / LightHub и исходном коде.
+> Описывает реальный формат конфигурации, без абстракций и допущений.
+
+---
+
+## Содержание
+
+1. [Назначение конфигурационного файла](#назначение)
+2. [Общая структура JSON](#структура)
+3. [Секция `mqtt`](#mqtt)
+4. [Секция `topics`](#topics)
+5. [Секция `syslog`](#syslog)
+6. [Секция `ow` (1-Wire)](#1wire)
+7. [Секция `modbus` (КЛЮЧЕВАЯ)](#modbus)
+8. [Секция `items` (ЛОГИКА)](#items)
+9. [Секция `in` (входы)](#in)
+10. [Полный пример](#пример)
+11. [Справочники и ссылки](#справочники)
+
+---
+
+## Назначение конфигурационного файла {#назначение}
+
+JSON‑конфигурация LightHub — это **единственный источник описания системы**. Она определяет:
+
+- **Сетевую интеграцию** (MQTT, syslog)
+- **Подключённые физические интерфейсы** (DMX, RS485, GPIO, 1-Wire)
+- **Библиотеки Modbus‑устройств** (шаблоны с параметрами)
+- **Логические объекты (items)** — каналы управления (0-23 типов)
+- **Маршрутизацию данных и команд** между MQTT и локальными объектами
+
+❗ **В LightHub нет runtime‑конфигурации** — всё задаётся декларативно при загрузке файла.
+
+---
+
+## Общая структура JSON {#структура}
+
+Корневой объект конфигурации содержит **независимые секции**:
+
+```json
+{
+  "mqtt": [],
+  "topics": {},
+  "syslog": [],
+  "dmx": [],
+  "ow": {},
+  "modbus": {},
+  "in": {},
+  "items": {}
+}
+```
+
+**Любая секция может отсутствовать**, если функциональность не используется.
+
+---
+
+## Секция `mqtt` {#mqtt}
+
+### Назначение
+
+Определяет **MQTT‑клиент LightHub**. Контроллер всегда работает как клиент.
+
+### Формат
+
+```json
+"mqtt": [
+  "client_id",
+  "broker_host",
+  1883,
+  "username",
+  "password"
+]
+```
+
+### Параметры (позиционные!)
+
+
+| № | Назначение | Тип | Обязателен | Пример |
+|--|--|--|--|--|
+| 0 | MQTT Client ID | string | **✓** | `"lighthub-07"` |
+| 1 | DNS‑имя или IP брокера | string | **✓** | `"192.168.88.2"` |
+| 2 | Порт | int | - | `1883` |
+| 3 | Логин | string | - | `"mqtt_user"` |
+| 4 | Пароль | string | - | `"pass123"` |
+
+### Примеры
+
+```json
+"mqtt": ["lighthub", "m2m.eclipse.org"]
+
+"mqtt": ["lh1", "192.168.1.10", 1883, "user", "pass"]
+
+"mqtt": ["abc3", "192.168.88.2"]
+```
+
+⚠️ **Безопасность**: пароль рекомендуется задавать через CLI, а не хранить в JSON.
+
+---
+
+## Секция `topics` {#topics}
+
+### Назначение
+
+Глобальные настройки MQTT‑топиков.
+
+### Формат
+
+```json
+"topics": {
+  "root": "myhome",
+  "bcst": "in",
+  "out": "s_out"
+}
+```
+
+### Параметры
+
+| Ключ | Назначение | По умолчанию |
+|--|--|--|
+| `root` | Корневой префикс всех топиков | `"myhome"` |
+| `bcst` | Входящие команды | `"in"` |
+| `out` | Исходящие статусы | `"s_out"` |
+
+По умолчанию: `root=myhome`, `bcst=in`, `out=s_out`.
+
+### Поведение
+
+Все MQTT‑топики, создаваемые LightHub, будут иметь вид:
+
+```
+<root>/<item>/<parameter>
+```
+
+**Пример**:
+```
+myhome/dev/lamp1/val         # статус яркости
+myhome/dev/lamp1/cmd         # последняя команда
+myhome/s_out/lamp1/hue       # текущий оттенок RGB лампы
+```
+
+---
+
+## Секция `syslog` {#syslog}
+
+### Назначение
+
+Передача логов контроллера на удалённый syslog‑сервер (UDP).
+
+### Формат
+
+```json
+"syslog": ["192.168.1.10", 514]
+```
+
+### Параметры
+
+| № | Параметр | Тип | По умолчанию |
+|--|--|--|--|
+| 0 | IP адрес сервера | string | - |
+| 1 | UDP порт | int | `514` |
+
+---
+
+## Секция `dmx` {#dmx}
+
+### Назначение
+
+Конфигурация DMX 512 выхода (для работы с LED декодерами).
+
+### Форматы
+
+**Простой** (для всех плат):
+```json
+"dmx": [512]   // 512 DMX каналов
+```
+
+**Расширенный** (для Arduino Mega):
+```json
+"dmx": [3, 512]  // берётся только последний элемент — число каналов
+```
+
+### Параметры
+
+| Параметр | Описание |
+|--|--|
+| GPIO pin | Не используется: пин фиксирован (AVR_DMXOUT_PIN) |
+| Кол-во каналов | Число DMX каналов (обычно 512) — берётся только последний элемент массива |
+
+---
+
+## Секция `ow` (1‑Wire) {#1wire}
+
+### Назначение
+
+Подключение датчиков 1‑Wire (DS18B20 и совместимые).
+
+### Формат
+
+```json
+"ow": {
+  "28FF641D2A1603B1": {
+    "emit": "temp/outdoor",
+    "item": "t_out"
+  },
+  "284811170400005B": {
+    "emit": "temp/indoor"
+  }
+}
+```
+
+### Параметры
+
+| Ключ | Назначение |
+|--|--|
+| Ключ объекта | **ROM‑код датчика** (уникальный адрес, HEX) |
+| `emit` | MQTT‑топик публикации (опционально) |
+| `item` | Привязка к локальному объекту (опционально) |
+
+### Поведение
+
+- Датчик автоматически опрашивается по расписанию
+- Температура публикуется в MQTT топик `root/emit_name`
+- Если задан `item`, значение передаётся в локальный объект
+
+---
+
+## Секция `modbus` — КЛЮЧЕВАЯ {#modbus}
+
+### Назначение
+
+Раздел `modbus` — это **библиотека описаний Modbus‑устройств**.
+
+❗ **Здесь НЕ задаются реальные адреса устройств**, только **шаблоны**.
+Реальные адреса и параметры задаются в секции `items` при использовании шаблонов.
+
+### Общая структура
+
+```json
+"modbus": {
+  "device_template_name": {
+    "baud": 9600,
+    "serial": "8N1",
+    "poll": {},
+    "par": {}
+  }
+}
+```
+
+### Параметры линии
+
+#### `baud`
+Скорость RS‑485: `9600`, `19200`, `38400`, `115200`
+
+#### `serial`
+Формат кадра:
+- `8N1` — 8 бит, без чётности, 1 стоп-бит (стандарт)
+- `8E1` — 8 бит, чётность even, 1 стоп-бит
+- `8O1` — 8 бит, чётность odd, 1 стоп-бит
+
+### Раздел `poll` — стратегия опроса
+
+```json
+"poll": {
+  "regs": [[0, 40], [100, 20]],
+  "irs": [300, 301],
+  "coils": [0, 1],
+  "delay": 2000
+}
+```
+
+#### Интерпретация
+
+- **`regs`** — Holding Registers (блоки для чтения/записи)
+  - Формат: `[начальный_адрес, кол-во]`
+  - Пример: `[[0, 40], [100, 20]]` = два блока: 0-39 и 100-119
+  
+- **`irs`** — Input Registers (только чтение, статус)
+  - Формат: массив адресов
+  - Пример: `[300, 301]`
+
+- **`coils`** — Coil Registers (логические выходы)
+  - Формат: массив адресов
+  - Пример: `[0, 1]`
+
+- **`delay`** — Задержка между циклами опроса (мс)
+  - Пример: `2000` = опрашивать каждые 2 секунды
+
+**LightHub автоматически объединяет регистры в минимальное число Modbus‑запросов**.
+
+### Раздел `par` — параметры устройства
+
+```json
+"par": {
+  "power": {
+    "reg": 41,
+    "type": "u16",
+    "map": {"cmd": [["OFF", 0], ["ON", 1]]}
+  },
+  "temperature": {
+    "ir": 5,
+    "type": "x10"
+  }
+}
+```
+
+#### Поля параметра
+
+| Поле | Назначение | Тип |
+|--|--|--|
+| `reg` | Holding Register (R/W) | int |
+| `ir` | Input Register (R only) | int |
+| `coil` | Coil Register | int |
+| `type` | Тип данных | string |
+| `map` | Преобразование значений | object |
+
+#### Типы данных (`type`)
+
+| Тип | Значение | Диапазон |
+|--|--|--|
+| `u16` | uint16 | 0 - 65535 |
+| `i16` | int16 | -32768 - 32767 |
+| `u32` | uint32 | 0 - 4294967295 |
+| `i32` | int32 | -2147483648 - 2147483647 |
+| `u8h` | uint8 high byte | старший байт u16 |
+| `u8l` | uint8 low byte | младший байт u16 |
+| `i8h` | int8 high byte | старший байт i16 |
+| `i8l` | int8 low byte | младший байт i16 |
+| `x10` | масштаб ×0.1 | - |
+| `100` | масштаб ×0.01 | - |
+
+### Пример Modbus шаблона (реальный)
+
+```json
+"modbus": {
+  "haier_ac": {
+    "baud": 9600,
+    "serial": "8N1",
+    "poll": {
+      "regs": [[1, 30]],
+      "delay": 1000
+    },
+    "par": {
+      "power": {
+        "reg": 1,
+        "type": "u16",
+        "map": {"cmd": [["OFF", 0], ["ON", 1]]}
+      },
+      "mode": {
+        "reg": 2,
+        "type": "u16",
+        "map": {"cmd": [["COOL", 0], ["HEAT", 1], ["DRY", 2], ["FAN", 3], ["AUTO", 4]]}
+      },
+      "temperature": {
+        "reg": 3,
+        "type": "x10"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Секция `items` — ЛОГИКА {#items}
+
+### Назначение
+
+`items` — это **логические объекты (каналы) LightHub**.
+
+Они связывают:
+- Физические интерфейсы (GPIO, DMX, RS485)
+- Modbus параметры
+- MQTT топики
+- входы (кнопки, датчики)
+
+### Общий формат
+
+```json
+"item_name": [
+  TYPE,
+  CONFIG,
+  initial_value,    // опционально
+  initial_command   // опционально
+]
+```
+
+### Параметры
+
+| Элемент | Назначение | Обязателен | Тип |
+|--|--|--|--|
+| 0 | **TYPE** — тип канала (0-23) | **✓** | int или string |
+| 1 | **CONFIG** — конфигурация (зависит от типа) | **✓** | int, string, или array |
+| 2 | Начальное значение (preset) | - | int или array |
+| 3 | Начальная команда | - | int |
+
+### Типы каналов (0-23)
+
+**Полный справочник типов каналов см. в [channel_types_reference.md](channel_types_reference.md)**
+
+| Код | Тип | Описание | Конфигурация |
+|--|--|--|--|
+| **0** | `DMX` | DMX выход с регулировкой | DMX канал или массив каналов |
+| **1** | `DMXRGBW` | DMX RGB+White | Стартовый DMX канал |
+| **2** | `DMXRGB` | DMX RGB | Стартовый DMX канал |
+| **3** | `PWM` | GPIO PWM | GPIO пин или массив пинов |
+| **4** | `MBUSDIM` | Modbus AC Dimmer (Legacy) | `[адрес, регистр, маска, макс]` |
+| **5** | `THERMO` | ON/OFF термостат | `[pin]`, уставка — 3-й элемент item |
+| **6** | `RELAY` | GPIO реле | GPIO пин |
+| **7** | `GROUP` | Группа каналов | Массив имён каналов |
+| **8** | `VCTEMP` | Vacom PID терморегулятор | `[имя_канала_VC]` (строка) |
+| **9** | `MBUSVC` | Vacom мотор | `[Modbus_адрес, "имя_объекта"]` |
+| **10** | `ACHAIER` | Кондиционер Haier (проприетарный UART, не Modbus) | `[portNum(0-3)]` |
+| **11** | `SPILED` | SPI LED лента | `[data_pin, numLeds, ledsType]` |
+| **12** | `MOTOR` | Двигатель с позиционной ОС | `[pinUp, pinDown, pinFeedback, fbOpen, fbClosed, maxOnTime]` |
+| **13** | `PID` | PID регулятор | `[[Kp, Ki, Kd, ...], execObj, ...]` |
+| **14** | `MBUS` | Universal Modbus | `[адрес, шаблон, параметры]` |
+| **15** | `UARTBRDG` | UART мост | `{serial, baud, ip, port, hd, log, bond}` (порты фиксированные) |
+| **16** | `RELAYX` | Медленный PWM | `[GPIO_pin, период_сек]` |
+| **17** | `DMXRGBWW` | DMX RGBWW | Стартовый DMX канал |
+| **18** | `VENTS` | Многозональная вентиляция | `{зоны}` (объект; рабочая форма `[[18,5], {зоны}]`) |
+| **19** | `ELEVATOR` | Лифт (ELEVATOR_ENABLE) | `{serial, baud, log}` |
+| **20** | `COUNTER` | Автосуммирующий счётчик | `[коэффициент_импульса, период_автосуммирования_сек]` |
+| **21** | `HUM` | Увлажнитель (HUMIDIFIER_ENABLE) | `[[пины...], {зоны}, motorExecObj, faultExecObj]` |
+| **22** | `MERCURY` | Счётчик энергии Mercury | `[адрес, baudrate, ...]` |
+| **23** | `SPRINKLR` | Система полива | `{конфиг}` (корневой объект `""` + зоны с `pin`) |
+
+### Примеры конфигурации items
+
+#### CH_RELAY (6) — Простое реле
+
+```json
+"relay1": [6, 23],              // Реле на GPIO 23
+"relay2": ["RELAY", 28],        // Текстовое обозначение типа
+"relay3": [6, 28, 1, 1]         // С начальным значением и командой
+```
+
+#### CH_DMX (0) — DMX выход
+
+```json
+"lamp1": [0, 5],                // DMX канал 5
+"lamp2": [0, [10, 11, 12]],     // Массив DMX каналов
+"dmx_4ch": ["DMX", [1, 2, 3, 4]]  // 4-х канальный диммер
+```
+
+#### CH_RGBW (1) — RGB+White
+
+```json
+"rgb_light": [1, 10]            // RGB+W на DMX 10-13
+```
+
+#### CH_PWM (3) — GPIO PWM
+
+```json
+"pwm1": [3, 9],                 // PWM на GPIO 9
+"pwm_4ch": [3, [11, 12, 13, 14]] // 4-х канальный PWM
+```
+
+#### CH_GROUP (7) — Группа каналов
+
+```json
+"lights_all": [7, [
+  "lamp1", "lamp2", "lamp3",
+  "rgb1", "rgb2"
+]],
+"lights_bedroom": [7, ["lamp1", "rgb1", "relay1"]]
+```
+
+#### CH_THERMO (5) — Термостат
+
+```json
+"thermo_bath": [5, 24, 33]      // GPIO 24, уставка 33°C
+```
+
+#### CH_ACHAIER (10) — Кондиционер Haier
+
+Проприетарный UART-протокол (НЕ Modbus):
+
+```json
+"ac_haier": [10, 0]              // portNum 0-3
+```
+
+#### CH_COUNTER (20) — Счётчик энергии
+
+```json
+"energy": [20, [0.02, 60]],      // импульс, период автосуммирования (сек)
+"gas": [20, 0]                   // без калибровки
+```
+
+#### CH_MULTIVENT (18) — Многозональная вентиляция
+
+```json
+"multivent": [[18, 5], {
+  "": {
+    "val": {"emit": "main/temp"}
+  },
+  "bedroom": {
+    "val": {"emit": "bedroom/temp"},
+    "fan": {"emit": "bedroom/fan"},
+    "set": 22,
+    "pid": [1.0, 0.05, 0.02, 5.0]
+  },
+  "living_room": {
+    "val": {"emit": "living/temp"},
+    "set": 21
+  }
+}]
+```
+
+---
+
+## Секция `in` (входы) {#in}
+
+### Назначение
+
+Связывает физические входы (GPIO, кнопки) с логикой.
+
+### Формат
+
+```json
+"in": {
+  "37": {
+    "T": 0,
+    "item": "light",
+    "scmd": "TOGGLE",
+    "rcmd": "TOGGLE"
+  }
+}
+```
+
+### Параметры
+
+| Параметр | Назначение | Описание |
+|--|--|--|
+| Ключ | GPIO пин | Номер пина входа |
+| `T` | Тип входа | 0 = нормальный, 1 = кнопка |
+| `emit` | MQTT топик | Куда публиковать (опционально) |
+| `item` | Локальный объект | Какой канал управлять |
+| `scmd` | Short command | Команда при нажатии (T=0) |
+| `rcmd` | Release command | Команда при отпускании (T=0) |
+
+### Пример
+
+```json
+"in": {
+  "37": {
+    "T": 0,
+    "emit": "/myhome/in/all",
+    "scmd": "HALT",
+    "rcmd": "REST"
+  },
+  "38": {
+    "item": "spots",
+    "scmd": "TOGGLE",
+    "rcmd": "TOGGLE"
+  },
+  "39": {
+    "emit": "/myhome/s_out/water_leak"
+  }
+}
+```
+
+---
+
+## Полный пример конфигурации {#пример}
+
+```json
+{
+  "mqtt": ["lighthub-07", "192.168.88.2"],
+  "topics": {"root": "myhome"},
+  "syslog": ["192.168.88.2", 514],
+  "dmx": [512],
+  
+  "modbus": {
+    "haier_ac": {
+      "baud": 9600,
+      "serial": "8N1",
+      "poll": {
+        "regs": [[1, 30]],
+        "delay": 1000
+      },
+      "par": {
+        "power": {
+          "reg": 1,
+          "type": "u16",
+          "map": {"cmd": [["OFF", 0], ["ON", 1]]}
+        },
+        "mode": {
+          "reg": 2,
+          "type": "u16",
+          "map": {"cmd": [["COOL", 0], ["HEAT", 1], ["DRY", 2]]}
+        },
+        "temperature": {
+          "reg": 3,
+          "type": "x10"
+        }
+      }
+    }
+  },
+  
+  "items": {
+    "lights_all": [7, [
+      "lamp_bedroom",
+      "lamp_kitchen",
+      "lamp_hall",
+      "rgb_living"
+    ]],
+    
+    "lamp_bedroom": [0, 1],
+    "lamp_kitchen": [0, 2],
+    "lamp_hall": [0, 3],
+    
+    "rgb_living": [1, 10],
+    
+    "relay_water": [6, 23],
+    "relay_heat": [6, 24],
+    
+    "ac_main": [10, 0],          // ACHAIER: проприетарный UART, portNum
+    
+    "thermo_bath": [5, 35, 33],
+    
+    "energy_meter": [20, [0.02, 1.2]]
+  },
+  
+  "in": {
+    "37": {
+      "item": "lights_all",
+      "scmd": "TOGGLE",
+      "rcmd": "TOGGLE"
+    },
+    "38": {
+      "item": "relay_water",
+      "scmd": "OFF"
+    }
+  }
+}
+```
+
+---
+
+## Справочники и ссылки {#справочники}
+
+### Основные справочники
+
+- **[Справочник типов каналов](channel_types_reference.md)** — коды, текстовые обозначения, синтаксис конфигурации
+- **[Справочник суффиксов](suffixes_reference.md)** — параметры (/cmd, /val, /set, /hue, /sat, /temp и др.)
+- **[Описание модулей](modules_description.md)** — подробная документация по каждому типу
+
+### Дополнительная информация
+
+- [Исходный код item.h](../../lighthub/item.h) — определения типов и констант
+- [Исходный код item.cpp](../../lighthub/item.cpp) — реализация логики
+- Репозиторий: https://github.com/anklimov/lighthub
+
+---
+
+## Инженерные принципы конфигурирования
+
+1. **Сначала描述 Modbus устройства** в секции `modbus`
+2. **Затем создаются items** в секции `items` с использованием шаблонов
+3. **Затем подключается MQTT** через `emit` параметры
+4. **Минимизировать `poll` задержку** (не ниже 100 мс для RS485)
+5. **Использовать `topics.root`** для всех MQTT топиков
+
+---
+
+## Заключение
+
+LightHub использует **жёстко структурированную, декларативную модель конфигурации**.
+
+Это даёт:
+- **Предсказуемость** — структура всегда одинакова
+- **Надёжность** — явное лучше неявного
+- **Промышленный стиль** — как в PLC системах
+- **Масштабируемость** — легко добавлять новые устройства
+
+**Вся логика контроллера полностью определяется конфигурацией, без необходимости перекомпиляции кода.**
+
+---
+
+**Версия документа**: 2.0  
+**Дата обновления**: 2025-01-24  
+**Актуально для**: LightHub с CH_DIMMER (0) - CH_SPRINKLER (23)  
+**Источник**: [item.h](../../lighthub/item.h), [item.cpp](../../lighthub/item.cpp)
@@ -0,0 +1,728 @@
+# LightHub: Модули управления и конфигурация
+
+> Описание реальных параметров модулей, загружаемых кодом.
+> Основано исключительно на анализе исходных файлов C++.
+
+---
+
+## Типы модулей (numbers в JSON)
+
+| Type | Модуль | Класс | Описание |
+|------|--------|-------|---------|
+| 0 | DMX | out_dmx | DMX512 управление освещением |
+| 3 | PWM | out_pwm | Широтно-импульсная модуляция |
+| 4 | Modbus Dimmer | out_Modbus | AC-диммер через Modbus RTU (legacy) |
+| 6 | Реле | out_relay | Управление электромагнитным реле |
+| 10 | AC | out_AC | Управление кондиционером (Haier, UART) |
+| 11 | SPI LED | out_SPILed | Адресуемые светодиоды WS2812/APA102 |
+| 12 | Мотор | out_Motor | Управление моторами с обратной связью |
+| 13 | PID | out_pid | PID-регулятор |
+| 14 | Modbus | out_Modbus | Modbus устройства (general) |
+| 15 | UART Bridge | out_UARTbridge | UART-мост между портами |
+| 16 | RELAYX | out_relay | Медленный PWM через реле |
+| 18 | Multivent | out_Multivent | Многозональная вентиляция |
+| 19 | Лифт | out_Elevator | Управление лифтом (UART) |
+| 20 | Счётчик | out_counter | Счётчик импульсов |
+| 21 | Увлажнитель | out_humidifier | Форсуночное увлажнение |
+| 22 | Меркурий | out_Mercury | Счётчик электроэнергии Меркурий |
+| 23 | Полив | out_sprinkler | Система полива |
+
+---
+
+## 1. out_counter — Счётчик импульсов
+
+### Конфигурация (Type 20)
+
+```json
+"pumpctr": [20, [0.02, 1.2]],
+"gasctr": [20, 0]
+```
+
+### Параметры массива
+
+| Индекс | Тип | Описание | Пример |
+|--------|-----|---------|--------|
+| [0] | float | Импульс (накопление за период) | 0.02 л/импульс |
+| [1] | float | Период накопления (сек) | 1.2 сек |
+
+### Логика работы
+
+1. Модуль ждёт команду (S_SET или любой CMD)
+2. При получении команды с процентом > 0 запускается таймер
+3. По истечении периода [1] добавляется значение [0] * TENS_BASE
+4. Считанное значение публикуется в MQTT
+
+### Пример использования
+
+```json
+{
+  "items": {
+    "water_meter": [20, [0.01, 5.0]],
+    "gas_meter": [20, [0.1, 10.0]]
+  }
+}
+```
+
+---
+
+## 2. out_relay — Электромагнитное реле (Type 6)
+
+### Конфигурация
+
+```json
+"pump": [6, [pin, period_сек]]
+```
+
+### Параметры
+
+| Индекс | Тип | Описание | Диапазон |
+|--------|-----|---------|----------|
+| [0] | int | GPIO пин (отрицательное = инвертировать) | 0-54 |
+| [1] | float | Период цикла (сек), для RELAYX (16) | любой > 0 |
+
+### Логика
+
+- HIGH (или LOW если инвертировано) = ON
+- LOW (или HIGH если инвертировано) = OFF
+- Если pin < 0, используется инверсия логики
+
+### Примеры
+
+```json
+"relay_normal": [6, 33],
+"relay_inverted": [6, -33],
+"relay_with_period": [16, [32, 5]]
+```
+
+---
+
+## 3. out_Motor — Управление моторами (Type 12)
+
+### Конфигурация
+
+```json
+"roller_blind": [12, [pinUp, pinDown, pinFeedback, feedbackOpen, feedbackClosed, maxOnTime]]
+```
+
+### Параметры
+
+| Индекс | Тип | Описание | Диапазон | Значение по умолч. |
+|--------|-----|---------|----------|-------------------|
+| [0] | int | GPIO пин UP (отрицательное = инвертировать) | 0-54 | 32 |
+| [1] | int | GPIO пин DOWN | 0-54 | 33 |
+| [2] | int | GPIO пин обратной связи (аналоговый) | 0-54 | 0 |
+| [3] | int | Значение обратной связи (открыто) | 0-1024 | 0 |
+| [4] | int | Значение обратной связи (закрыто) | 0-1024 | 1024 |
+| [5] | int | Максимальное время движения (мс) | > 0 | 10000 |
+
+### Логика работы
+
+1. Модуль сравнивает **targetPos** (из команды 0-255) с **curPos** (из обратной связи)
+2. Если разница > POS_ERR (10):
+   - Если targetPos < curPos → движение вниз (pinDown)
+   - Если targetPos > curPos → движение вверх (pinUp)
+3. При достижении targetPos или maxOnTime мотор останавливается
+4. Защита от перегрузки: одновременно работают макс. MOTOR_QUOTE моторов (обычно 2)
+
+### Примеры
+
+```json
+"blind_motor": [12, [32, 33, 36, 0, 1023, 120000]],
+"gate_motor": [12, [-10, -11, 12, 100, 900, 60000]]
+```
+
+### Управление
+
+```
+Команда: CMD_ON → движение вверх до конца
+Команда: CMD_OFF → движение вниз до конца
+Значение 0-255 → позиция (0=полностью открыто, 255=полностью закрыто)
+```
+
+---
+
+## 4. out_PID — PID-регулятор (Type 13)
+
+### Конфигурация
+
+```json
+"heater": [13, [
+  [Kp, Ki, Kd, dT, alarmTO, alarmVal, outMin, outMax],
+  {output_execObj},
+  {cascade_execObj}
+], setpoint]
+```
+
+### Параметры массива [0]
+
+| Индекс | Тип | Описание | Обязательный |
+|--------|-----|---------|-------------|
+| [0] | float | Kp (пропорциональный) | ✓ |
+| [1] | float | Ki (интегральный) | ✓ |
+| [2] | float | Kd (дифференциальный) | ✓ |
+| [3] | float | dT (период сэмплирования, сек) | опционально (5 по умолч.) |
+| [4] | int | Timeout будильника (сек) | опционально |
+| [5] | float | Порог будильника | опционально |
+| [6] | float | Минимум выхода | опционально |
+| [7] | float | Максимум выхода | опционально |
+
+### Логика
+
+- **Kp < 0** → режим REVERSE (для охлаждения)
+- **Kp > 0** → режим DIRECT (для нагрева)
+- Выход ограничивается [outMin, outMax]
+- dT = период опроса в секундах
+
+### Примеры
+
+```json
+"room_temperature": [
+  13,
+  [
+    [1.0, 0.05, 0.02, 5.0],
+    {"item": "heater"},
+    null
+  ],
+  21.5
+]
+```
+
+---
+
+## 5. out_PWM — ШИМ управление (Type 3)
+
+### Конфигурация
+
+```json
+"led_brightness": [3, [pin0, pin1, ...]]
+```
+
+### Параметры
+
+| Индекс | Тип | Описание |
+|--------|-----|---------|
+| [0] | int | GPIO пин (1 канал) или массив пин |
+
+Число пин задаёт тип: 3 → RGB, 4 → RGBW, 5 → RGBWW. Частота PWM настраивается в коде, не в конфиге.
+
+### Примеры
+
+```json
+"pwm_led": [3, 5],
+"pwm_fan": [3, 6],
+"pwm_rgbw": [3, [11, 12, 13, 14]]
+```
+
+---
+
+## 6. out_relay (Type 6) — детально
+
+### Загружаемые параметры (getConfig)
+
+```cpp
+pin = item->getArg(0);           // основной параметр
+if (pin < 0) {
+  pin = -pin;
+  inverted = true;               // инвертировать логику
+}
+period = item->getFloatArg(1) * 1000.0;  // период из конфига в СЕКундах → мс
+if (!period) period = 5000UL;    // по умолчанию 5 сек
+```
+
+**Вывод**: модуль загружает ровно 2 параметра; тот же драйвер используется для RELAYX (Type 16), где период определяет цикл ШИМ
+
+---
+
+## 7. out_counter (Type 20) — детально
+
+### Загружаемые параметры (Poll)
+
+```cpp
+uint32_t impulse = item->getFloatArg(0) * TENS_BASE;  // [0]
+uint32_t period = item->getFloatArg(1) * 1000.0;       // [1] в мс
+```
+
+**Логика**:
+1. Модуль ждёт активации (getExt() = 0)
+2. При получении команды ON/HEAT/COOL/etc запускает таймер
+3. По истечении period добавляет impulse к накопленному значению
+4. Публикует обновлённое значение
+
+---
+
+## 8. out_Motor (Type 12) — детально
+
+### Загружаемые параметры (getConfig)
+
+```cpp
+pinUp = item->getArg(0);                  // [0]
+pinDown = item->getArg(1);                // [1]
+pinFeedback = item->getArg(2);            // [2]
+feedbackOpen = item->getArg(3);           // [3]
+feedbackClosed = item->getArg(4);         // [4]
+maxOnTime = item->getArg(5);              // [5], по умолчанию 10000 мс
+```
+
+### Обработка отрицательных значений
+
+```cpp
+if (pinUp < 0) {
+  pinUp = -pinUp;
+  inverted = true;
+}
+if (pinDown < 0) {
+  pinDown = -pinDown;
+  inverted = true;
+}
+```
+
+---
+
+## 9. out_PID (Type 13) — детально
+
+### Загружаемые параметры (getConfig)
+
+```cpp
+aJsonObject * kPIDObj = aJson.getArrayItem(item->itemArg, 0);
+// Обрабатывает случаи от 1 до 8 элементов:
+// [Kp]
+// [Kp, Ki]
+// [Kp, Ki, Kd]
+// [Kp, Ki, Kd, dT]
+// [Kp, Ki, Kd, dT, alarmTO]
+// [Kp, Ki, Kd, dT, alarmTO, alarmVal]
+// [Kp, Ki, Kd, dT, alarmTO, alarmVal, outMin]
+// [Kp, Ki, Kd, dT, alarmTO, alarmVal, outMin, outMax]
+
+if (kP < 0) {
+  kP = -kP;
+  direction = REVERSE;  // Отрицательный Kp = режим REVERSE
+}
+```
+
+### Использование вторых параметров
+
+```cpp
+store->setpoint = item->itemVal->valuefloat;  // Установка из JSON value
+```
+
+---
+
+## 11. out_humidifier (Type 21) — Форсуночное увлажнение
+
+### Конфигурация
+
+```json
+"hum": [21, [
+  [pumpPin, flushPin, pressurePin, maxPumpTime, idleTime, capacity, minLevel, startLevel],
+  {
+    "zone1": {"N": 1, "pin": 24},
+    "zone2": {"N": 2, "pin": 33}
+  },
+  {"item": "pumpctr"},
+  255,
+  2
+]]
+```
+
+### Параметры конфигурации [0] (массив переменной длины)
+
+| Индекс | Тип | Описание | По умолч. | Обязателен |
+|--------|-----|---------|----------|-----------|
+| [0] | int | GPIO пин насоса (отрицательное = инвертировать) | 22 | ✓ |
+| [1] | int | GPIO пин очистки (отрицательное = инвертировать) | 23 | опционально |
+| [2] | int | GPIO пин датчика давления (аналоговый) | 54 | опционально |
+| [3] | int | Макс. время работы насоса (сек) | 255 | опционально |
+| [4] | int | Время ожидания между циклами (мс) | 2500 | опционально |
+| [5] | int | Максимум одновременно открытых форсунок | 4 | опционально |
+| [6] | int | Минимальный уровень (%) для включения форсунки | 10 | опционально |
+| [7] | int | Пороговый уровень для запуска цикла (%) | 20 | опционально |
+
+### Параметры зон (объект)
+
+Каждая зона — это объект с полями:
+
+```json
+"zone_name": {
+  "N": 1,           // номер зоны для балансировки нагрузки
+  "pin": 24         // GPIO пин электромагнитного клапана форсунки
+}
+```
+
+| Поле | Тип | Описание |
+|------|-----|---------|
+| `N` | int | Номер группы (1-4) для ограничения одновременно открытых клапанов |
+| `pin` | int | GPIO пин клапана (отрицательное = инвертировать логику) |
+| `set` | float | Требуемый уровень влажности (создаётся автоматически) |
+| `cmd` | int | Статус команды (создаётся автоматически) |
+
+### Счётчик импульсов
+
+```json
+{"item": "pumpctr"}  // привязка к счётчику для контроля расхода
+```
+
+### Пороги и состояния
+
+Из кода определены константы:
+
+```
+PREPARATION_TIME = 10000 мс      // подготовка к пуску
+PRESSURE_ACHIEVING_TIME = 8000 мс // время достижения давления
+MIN_KEEP_TIME = 2500 мс            // минимальное время работы форсунки
+FLUSH_PRESSURE = 200               // давление очистки
+FLUSH_TIMEOUT = 125000 мс          // таймаут очистки
+MIN_OPERATION_PRESSURE = 400       // минимальное рабочее давление
+MAX_OPERATION_PRESSURE = 600       // максимальное рабочее давление
+```
+
+### Состояния модуля
+
+| Состояние | Код | Описание |
+|-----------|-----|---------|
+| H_UNKNOWN | 0 | Неизвестное состояние |
+| H_READY | 1 | Готов к работе |
+| H_PREPARE_FOR_START | 2 | Подготовка к пуску |
+| H_PREPARE_VALVES | 3 | Открытие форсунок |
+| H_MOTOR_ON | 4 | Включение насоса |
+| H_OPERATE | 5 | В режиме увлажнения |
+| H_MOTOR_PAUSE | 6 | Пауза насоса |
+| H_MOTOR_OFF | 7 | Выключение насоса |
+| H_MOTOR_OFF_OK | 10 | Насос остановлен |
+| H_FLUSH | 8 | Промывка системы |
+| H_IDLE | 9 | Ожидание |
+| H_FAULT_PRESSURE | -1 | Ошибка давления |
+| H_FAULT_PRESSURE_KEEP | -2 | Потеря давления во время работы |
+| H_FAULT_OVERPRESSURE | -3 | Перепад давления |
+| H_FAULT_MOTOR_OFF | -4 | Отказ насоса |
+
+### Логика работы
+
+1. **Инициализация**: модуль ждёт команду включения или когда уровень влажности > startLevel
+2. **Подготовка**: открывает клапаны форсунок, ждёт достижения давления
+3. **Работа**: включает насос, поддерживает давление в диапазоне [MIN_OPERATION_PRESSURE, MAX_OPERATION_PRESSURE]
+4. **Балансировка**: одновременно открыто не более `capacity` форсунок из группы `N`
+5. **Очистка**: периодическая промывка при давлении FLUSH_PRESSURE
+6. **Контроль**: отключение при падении давления ниже MIN_OPERATION_PRESSURE
+
+### Примеры конфигурации
+
+#### Простая система увлажнения
+
+```json
+{
+  "items": {
+    "humidifier": [21, [
+      [22, 23, 54, 255, 2500, 4, 10, 20],
+      {
+        "bedroom": {"N": 1, "pin": 24},
+        "living": {"N": 2, "pin": 25}
+      },
+      {"item": "waterctr"}
+    ]]
+  }
+}
+```
+
+#### Многозональная система (из официального примера)
+
+```json
+{
+  "items": {
+    "hum": [21, [
+      [22, 15, 30, 4, 10, 20],
+      {
+        "bedr1": {"N": 1, "pin": 24},
+        "ktc1": {"N": 1, "pin": 25},
+        "dinner1": {"N": 1, "pin": 9},
+        "bedr2m": {"N": 1, "pin": 8},
+        "bedr21": {"N": 1, "pin": 11},
+        "bedr22": {"N": 1, "pin": 12},
+        "zal2": {"N": 2, "pin": 33},
+        "cab3": {"N": 1, "pin": 32},
+        "zal3": {"N": 4, "pin": 31},
+        "bedr3": {"N": 1, "pin": 30}
+      },
+      {"item": "pumpctr"},
+      255,
+      2
+    ]]
+  }
+}
+```
+
+---
+
+## 12. out_Mercury (Type 22) — Счётчик электроэнергии
+
+### Конфигурация
+
+```json
+"merc": [22, [
+  0,                    // [0] адрес Modbus (обычно на выходе item)
+  9600,                 // [1] скорость UART (baud)
+  "8N1",                // [2] параметры кадра
+  2,                    // [3] уровень доступа
+  [2,2,2,2,2,2],       // [4] пароль (массив из 6 чисел)
+  10000,                // [5] период опроса (мс)
+  {}                    // [6] параметры (обычно пусто)
+]]
+```
+
+### Параметры массива
+
+| Индекс | Тип | Назначение |
+|--------|-----|-----------|
+| [0] | int | Адрес устройства (из item->getArg(0)) |
+| [1] | int | Скорость UART |
+| [2] | string | Параметры (8N1, 8E1, 8O1) |
+| [3] | int | Уровень доступа (обычно 2) |
+| [4] | array/string | Пароль (6 символов или массив 6 чисел) |
+| [5] | int | Интервал опроса (мс) |
+| [6] | object | Дополнительные параметры |
+
+### Примеры
+
+```json
+"electricity_meter": [22, [
+  1,
+  9600,
+  "8N1",
+  2,
+  [0x01, 0x02, 0x03, 0x04, 0x05, 0x06],
+  60000,
+  {}
+]]
+```
+
+---
+
+## 13. out_AC (Type 10) — Управление кондиционером
+
+### Конфигурация
+
+```json
+"ac": [10, portNum],
+"ac": [10, [
+  portNum,          // [0] номер UART порта
+  {callbacks}       // [1] объект колбэков: fan / set / temp / cmd
+]]
+```
+
+### Загружаемые параметры
+
+```cpp
+portNum = item->getArg(0);  // 0=Serial, 1=Serial1, 2=Serial2, 3=Serial3
+```
+
+Проприетарный UART-протокол Haier (9600 baud), не Modbus; modbus-шаблонов для AC нет.
+
+### Поддерживаемые команды
+
+Модуль работает с 37-байтовым протоколом:
+
+| Байт | Назначение |
+|------|-----------|
+| 13 | Текущая температура |
+| 17 | Статус команды |
+| 23 | Режим (04=DRY, 01=COOL, 02=HEAT, 00=AUTO, 03=FAN) |
+| 25 | Скорость вентилятора |
+| 27 | SWING |
+| 28 | Блокировка пульта |
+| 29 | Питание |
+| 31 | Fresh |
+| 35 | Установка температуры |
+
+---
+
+## 14. out_Modbus (тип MBUS) — Modbus устройства
+
+### Конфигурация общая
+
+```json
+"modbus": {
+  "device_name": {
+    "baud": 9600,
+    "serial": "8N1",
+    "poll": {
+      "regs": [[0, 40], [100, 20]],
+      "irs": [[0, 10]],
+      "coils": [0, 1],
+      "dins": [0],
+      "delay": 5000
+    },
+    "par": {
+      "parameter_name": {
+        "reg": 0,
+        "type": "i16",
+        "id": 1,
+        "map": {}
+      }
+    }
+  }
+}
+```
+
+### Items использование Modbus
+
+```json
+"device_instance": [14, [
+  96,                 // [0] modbus-адрес устройства (обязательно)
+  "device_name",      // [1] имя шаблона (строка)
+  {
+    "power": {"emit": "home/ac/power"},
+    "temp": {"emit": "home/ac/temp"}
+  }
+]]
+```
+
+### Загружаемые параметры
+
+```cpp
+// From template:
+baud = baudObj->valueint;              // скорость (по умолчанию 9600)
+serialParam = str2SerialParam(...);    // формат (по умолчанию 8N1)
+
+// Poll strategy:
+pollingRegisters = aJson.getObjectItem(pollObj, "regs");   // блоки Holding Reg
+pollingIrs = aJson.getObjectItem(pollObj, "irs");           // Input Reg
+pollingCoils = aJson.getObjectItem(pollObj, "coils");       // Coil Reg
+poolingDiscreteIns = aJson.getObjectItem(pollObj, "dins");  // Discrete In
+pollingInterval = delayObj->valueint;  // по умолчанию 1000 мс
+```
+
+### Типы данных в параметрах
+
+| type | Описание |
+|------|---------|
+| i16 | int16 |
+| i32 | int32 |
+| u16 | uint16 |
+| u32 | uint32 |
+| i8h | старший байт |
+| i8l | младший байт |
+| u8h | старший байт unsigned |
+| u8l | младший байт unsigned |
+| x10 | ×0.1 (сырое значение / 10) |
+| 100 | ×0.01 (сырое значение / 100) |
+
+### Параметры в "par"
+
+```json
+"parameter": {
+  "reg": 0,              // Holding Register номер
+  "ir": 0,               // Input Register номер
+  "coil": 0,             // Coil номер
+  "type": "i16",         // тип данных
+  "id": 1,               // ID команды
+  "map": {               // маппинг значений
+    "cmd": [["OFF",0], ["ON",1]],
+    "val": null,
+    "def": "acmode"
+  }
+}
+```
+
+---
+
+## 15. out_Multivent (Type 18) — Многозональная вентиляция
+
+### Конфигурация
+
+itemArg — **объект** с зонами (не массив), рабочая форма `[[18, нач_значение], {зоны}]`:
+
+```json
+"vac": [[18, 5],
+  {
+    "": {            // AC-узел: привязка к AC item
+      "item": "ac_2"
+    },
+    "zone1": {       // зона 1
+      "pid": [490, 100, 9879, 40],
+      "set": 21.0,
+      "fan": 0,
+      "cmd": 14,
+      "item": "ac_zone1/set"
+    }
+  }
+]
+```
+
+### Параметры зоны
+
+| Параметр | Тип | Описание |
+|----------|-----|---------|
+| `pid` | [kP, kI, kD, dT] | Коэффициенты PID (массив ≥3) |
+| `set` | float | Уставка температуры (число) |
+| `fan` | int (0-255) | Текущий процент открытия |
+| `cmd` | int | Текущая команда |
+| `item` | string | Привязка к другому item |
+| `V` | int | Номинальный объём (для балансировки) |
+| `AlarmTime` | int | Время срабатывания аварии, деф 120 |
+| `AlarmValue` | float | Значение аварии, деф 0 |
+
+---
+
+## Практические примеры конфигурации
+
+### Система со счётчиками
+
+```json
+{
+  "items": {
+    "pumpctr": [20, [0.02, 1.2]],
+    "gasctr": [20, 0.1],
+    "waterctr": [20, 0]
+  },
+  "in": [
+    {"#": 41, "item": "waterctr/set", "scmd": "%0.01", "rcmd": ""},
+    {"#": 39, "item": "gasctr/set", "scmd": "%0.1", "rcmd": ""}
+  ]
+}
+```
+
+### Система с реле и мотором
+
+```json
+{
+  "items": {
+    "pump": [6, 33],
+    "blind": [12, [32, 33, 36, 0, 1023, 120000]]
+  }
+}
+```
+
+### PID регулятор
+
+```json
+{
+  "items": {
+    "heater": [13, [
+      [1.0, 0.05, 0.02, 5.0],
+      {"item": "heater_output"},
+      null
+    ], 22.0]
+  }
+}
+```
+
+---
+
+## Ключевые правила конфигурации
+
+1. **Инверсия логики**: отрицательное значение пина = инвертировать логику
+2. **Единицы времени**: 
+   - counter/relay: float конвертируется в миллисекунды (* 1000)
+   - mercury: миллисекунды напрямую
+3. **Параметры по умолчанию**:
+   - relay period = 5000 мс
+   - motor maxOnTime = 10000 мс
+   - modbus baud = 9600
+   - modbus polling = 1000 мс
+4. **Массивы переменной длины**: PID и Mercury поддерживают опциональные параметры
+
+---
+
+**Документ основан на анализе C++ кода без домыслов**  
+**Версия: 1.0**  
+**Дата: 2026-01-21**
@@ -0,0 +1,475 @@
+# LightHub: Справочник MQTT API и топиков
+
+> **Инженерный справочник** структуры MQTT топиков и HTTP API контроллера LightHub.
+> Источник: [wiki.lazyhome.ru - работа с MQTT](https://www.lazyhome.ru/dokuwiki/doku.php?id=%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0_%D1%81_mqtt) и [api](https://www.lazyhome.ru/dokuwiki/doku.php?id=api)
+
+---
+
+## Структура MQTT топиков
+
+### Общий формат топика
+
+```
+root/[id-устройства или bcst или out]/имя_item/[subitem/]suffix
+```
+
+### Компоненты топика
+
+#### 1. **root** — корневой префикс
+- **Назначение**: разделение систем при одном брокере
+- **По умолчанию**: `myhome`
+- **Пример**: `myhome`
+
+#### 2. **Адресация** (второй уровень)
+
+**Широковещательные (broadcast) командные топики**:
+- `bcst` — команда выполняется на всех контроллерах с одинаковым `bcst` именем
+- **Пример**: `myhome/in/lamp1/cmd` (где `in` — это значение `bcst`)
+
+**Индивидуальные командные топики**:
+- `id-устройства` — имя конкретного контроллера из конфигурации MQTT
+- **Пример**: `myhome/lighthub01/lamp1/cmd`
+
+**Статусные топики**:
+- `out` — контроллер публикует статус в эти топики
+- **Пример**: `myhome/s_out/lamp1/set` (где `s_out` — значение `out`)
+
+#### 3. **item_name** — имя объекта (канала)
+
+Определяется в разделе `items` конфигурации.
+
+```json
+"items": {
+  "lamp_bedroom": [0, 1],
+  "ac_main": [10, {...}]
+}
+```
+
+**Пример топиков для item `lamp_bedroom`**:
+- Команда: `myhome/in/lamp_bedroom/cmd`
+- Статус: `myhome/s_out/lamp_bedroom/set` (0-255) + общий `myhome/s_out/lamp_bedroom` (0-100)
+
+#### 4. **subitem** (опционально) — подпараметр
+
+Для каналов с множественными элементами (например, адресуемая LED лента, многозональная вентиляция).
+
+**Пример для многозональной вентиляции**:
+```
+myhome/in/multivent/bedroom/set      (установить T в спальне)
+myhome/in/multivent/kitchen/fan      (управление вентилятором кухни)
+```
+
+**Пример для LED ленты (пиксели 10-20; работает ТОЛЬКО для CH_SPILED, тип 11 — DMX-драйвер subitem игнорирует)**:
+```
+myhome/in/led_strip/10-20/set        (установить значение пиксели 10-20)
+```
+
+**Пример для состояния (условное выполнение)**:
+
+```
+myhome/in/floor/AUTO/set             (применится для теплых полов в режиме AUTO)
+myhome/in/floor/OFF/set              (применится для теплых полов в режиме OFF)
+```
+
+#### 5. **suffix** (суффикс) — параметр объекта
+
+Определяет **какое** свойство объекта меняется.
+
+---
+
+## Таблица суффиксов
+
+| Суффикс | Тип | Назначение | Применимость |
+|---------|-----|-----------|--------------|
+| **`/cmd`** | Command, Status | Основная команда управления (ON, OFF, TOGGLE и др.) | Все типы |
+| **`/set`** | Command, Status | Установка параметра (яркость, температура и др.) | Диммеры, регуляторы, термостаты |
+| **`/val`** | Command | Вход сенсора: значение регулируемого параметра направляется с сенсора сюда | THERMO, PID, MULTIVENT, SPRINKLER|
+| **`/hue`** | Command | Оттенок (0-365°, HSV формат) | RGB/RGBW/RGBWW |
+| **`/sat`** | Command | Насыщенность (0-100%, HSV формат) | RGB/RGBW/RGBWW |
+| **`/HSV`** | Command | Полный цвет (hue,saturation,volume). Суффикс ЗАГЛАВНЫЙ, строчный `/hsv` игнорируется | RGB/RGBW/RGBWW |
+| **`/rgb`** | Command | **Не обрабатывается** в текущей сборке (S_RGB) | — |
+| **`/temp`** | Command | Цветовая температура 153-500 mireds (RGBWW); у AC — текущая T | RGBWW, AC |
+| **`/raw`** | Command | «Сырые» данные, передаваемые драйверу без интерпретации | AC, ELEVATOR |
+| **`/fan`** | Command, Status | Скорость вентилятора 0-255 или (HIGH, MEDIUM, LOW, OFF) | AC, Multivent |
+| **`/mode`** | Command, Status | Режим работы — число 0-4 (AC). Команды FAN нет — есть FAN_ONLY. Текстовые режимы (HEAT, COOL, DRY, AUTO) — payload в /cmd | AC, Multivent |
+| **`/lock`** | Command, Status | Блокировка (ON, OFF) | AC |
+| **`/swing`** | Command, Status | Направление воздушного потока (ON, OFF) | AC |
+| **`/quiet`** | Command, Status | Тихий режим (ON, OFF) | AC |
+| **`/ctrl`** | Command, Status | Управление состоянием (FREEZE, UNFREEZE, ENABLE, DISABLE) | Специальное |
+| **`/del`** | Command | Команда с задержкой — только команды ON…FAN_ONLY (код ≤ 0x0F); HIGH/MEDIUM/LOW/HEAT_COOL/HEAT/COOL/DRY запланировать нельзя | ON…FAN_ONLY |
+
+---
+
+## Три типа топиков
+
+### 1. Командные топики (INPUT) — контроллер получает
+
+#### Широковещательные (broadcast)
+```
+root/bcst/item[/subitem]/suffix
+```
+
+**Примеры** (при bcst="in"):
+```
+myhome/in/lamp1/cmd          ← ON
+myhome/in/lamp1/set          ← 150
+myhome/in/ac_main/cmd        ← HEAT
+myhome/in/multivent/bedroom/set  ← 22
+```
+
+**Использование**: команда выполняется на **всех контроллерах**, у которых одинаковое имя контроллера (bcst).
+
+#### Индивидуальные
+```
+root/id-устройства/item[/subitem]/suffix
+```
+
+**Примеры** (при id-устройства="lighthub01"):
+```
+myhome/lighthub01/lamp1/cmd  ← ON
+myhome/lighthub01/lamp1/set  ← 150
+```
+
+**Использование**: команда выполняется на **конкретном контроллере**.
+
+### 2. Статусные топики (OUTPUT) — контроллер публикует
+
+```
+root/out/item[/subitem]/suffix
+```
+
+**Примеры** (при out="s_out"):
+```
+myhome/s_out/lamp1/set          → 255 (текущая яркость, 0-255; общий топик s_out/lamp1 — 0-100)
+myhome/s_out/lamp1/cmd          → ON (последняя команда)
+myhome/s_out/ac_main/mode       → <0-4> (число; текстовый режим «HEAT» публикуется в s_out/ac_main/cmd)
+myhome/s_out/ac_main/set        → 22 (установленная T)
+myhome/s_out/multivent/bedroom/set  → 21.0 (статус зоны — в суффикс ввода: /set, /fan, /cmd; /val нет)
+```
+
+**Свойства**:
+- Публикуются с флагом **PERSISTENT** (помощь при отключении-подключении)
+- При старте контроллер **восстанавливает состояние** из этих топиков
+- При локальном изменении (через входы) тоже обновляются
+
+### 3. Служебные топики (SERVICE)
+
+**Формат**: `root/id-устройства/$command` и `root/id-устройства/$stats`
+
+#### `$command`
+```
+myhome/lighthub01/$command
+```
+В payload записываются **CLI команды** (как если бы через последовательный порт):
+- `reboot`
+- `save`
+- `get`
+- `load` и др.
+
+#### `$stats` (два retained-топика, публикуются каждые 30 сек)
+```
+myhome/lighthub01/$stats/uptime    → 12345     (uptime, сек)
+myhome/lighthub01/$stats/freeheap  → 2500      (свободная RAM, байт)
+```
+При подключении в `myhome/lighthub01/$stats` публикуется список доступных метрик: `uptime,freeheap`.
+
+#### `$state` (публикуется контроллером)
+```
+myhome/lighthub01/$state  → "ready" или "disconnected"
+```
+
+#### Homie-топики
+
+Контроллер публикует также (retained) homie-топики: `$homie`, `$name`, `$state`, `$nodes`, `$fw/*` и `<item>/cmd/$datatype` для каждого item — для совместимости с Homie-клиентами.
+
+---
+
+## Примеры конфигурации MQTT
+
+### Базовая конфигурация
+
+```json
+{
+  "mqtt": ["LHexample03", "test.mosquitto.org", 1883, "user", "password"],
+  "topics": {"root": "myhome", "bcst": "in", "out": "s_out"}
+}
+```
+
+### Результирующие топики
+
+**Командные широковещательные**:
+```
+myhome/in/<item>
+myhome/in/<item>/set
+myhome/in/<item>/cmd
+myhome/in/<item>/<суффикс>
+```
+
+**Командные индивидуальные**:
+```
+myhome/LHexample03/<item>
+myhome/LHexample03/<item>/set
+myhome/LHexample03/<item>/cmd
+myhome/LHexample03/<item>/<суффикс>
+```
+
+**Статусные**:
+```
+myhome/s_out/<item>
+myhome/s_out/<item>/set
+myhome/s_out/<item>/cmd
+myhome/s_out/<item>/<суффикс>
+```
+
+---
+
+## Команды и инструкции (Payload)
+
+### Базовые команды (совместимы с OpenHab)
+
+| Команда | Описание | Пример |
+|---------|---------|--------|
+| `ON` | Включить (восстанавливает последнее значение) | `myhome/in/lamp1/cmd → ON` |
+| `OFF` | Выключить | `myhome/in/lamp1/cmd → OFF` |
+| `TOGGLE` | Переключить | `myhome/in/lamp1/cmd → TOGGLE` |
+| `0..255` | Установить яркость/значение. `/set` всегда 0-255; шкала 0-100 — только в общем топике без суффикса | `myhome/in/lamp1/set → 50` |
+
+### Числовые команды
+
+| Формат | Описание | Пример |
+|--------|---------|--------|
+| `<0..100>` | Яркость (OpenHab стиль) | `myhome/in/lamp → 50` |
+| `<0..255>` | Яркость/PWM/температура/значение счетчика/... (новый стиль) | `myhome/in/lamp/set → 128` |
+| `<H>,<S>,<V>` | HSV формат (суффикс ЗАГЛАВНЫЙ `/HSV`) | `myhome/in/led/HSV → 240,100,200` |
+| `<H>,<S>` | HSV без изменения яркости | `myhome/in/led/HSV → 240,100` |
+| `#RRGGBB` | RGB hex (Home Remote) — **не работает** в текущей сборке (hex не парсится) | — |
+| `<H>,<S>,<V>[,<CT>]` | Строка в общем топике (без суффикса) трактуется как **HSV(+colorTemp)**, а не RGB/RGBW | `myhome/in/led → 255,0,0,100` = HSV+CT |
+
+### Расширенные команды
+
+| Команда | Описание | Применимость |
+|---------|---------|--------------|
+| `HALT` | Выключить | Все |
+| `REST` | Включить (если был выключен HALT) | Все |
+| `XON` | Включить (если не DISABLE) | Все |
+| `XOFF` | Выключить (если был включен XON) | Все |
+| `INCREASE N` или `%+N` | Увеличить на N пунктов | Диммеры, PWM |
+| `DECREASE N` или `%-N` | Уменьшить на N пунктов | Диммеры, PWM |
+| `ENABLE` | Разрешить управление (XON, DISABLE) | PID, все |
+| `DISABLE` | Запретить управление (XON, DISABLE) | PID, все |
+| `FREEZE` | Заблокировать канал (игнорирует команды) | Все |
+| `UNFREEZE` | Разблокировать канал | Все |
+
+### Команды AC и Thermostat
+
+| Команда | Описание | Применимость |
+|---------|---------|--------------|
+| `AUTO` | Автоматический режим | AC, Thermostat, Multivent |
+| `HEAT` | Нагрев | AC, Thermostat, Multivent  |
+| `HEAT_COOL` | Нагрев/охлаждение (автоматически по температуре) | AC, Multivent |
+| `COOL` | Охлаждение | AC, Multivent  |
+| `DRY` | Осушение | AC, Multivent, Sprinkler  |
+| `FAN_ONLY` | Только вентилятор (команды FAN не существует) | AC, Multivent  |
+| `HIGH`, `MEDIUM`, `LOW` | Скорость вентилятора (MED — неверно) | AC, MULTIVENT |
+| `RESET` | Сброс параметров канала | Все |
+
+### Команды с задержкой
+
+**Синтаксис**: `КОМАНДА ВРЕМЯ_МС` (в топик с суффиксом `/del`)
+
+```
+myhome/in/lamp/del → "ON 5000"        (включить через 5 сек)
+myhome/in/lamp/del → "TOGGLE 2000"    (переключить через 2 сек)
+myhome/in/lamp/del → "OFF 10000"      (выключить через 10 сек)
+```
+
+### Команды, включаемые на время
+
+**Синтаксис**: `КОМАНДА ВРЕМЯ_МС` (в топик с суффиксом `/cmd`)
+
+Команда выполняется, а через указанное время выполняется **обратная команда**.
+
+**Пример**:
+```
+myhome/in/light/cmd → "ON 3000"
+  # Включит свет на 3 секунды, затем выключит
+```
+
+**Взаимно-обратные команды**:
+
+- `ON` ↔ `OFF`
+- `TOGGLE` ↔ `TOGGLE`
+- `REST` ↔ `HALT`
+- `XON` ↔ `XOFF`
+- `ENABLE` ↔ `DISABLE`
+- `FREEZE` ↔ `UNFREEZE`
+- `INCREASE` ↔ `DECREASE`
+
+---
+
+## Важные моменты
+
+### Восстановление состояния при старте
+
+1. Контроллер подписывается на **статусные топики** на **8 секунд** после старта (TIMEOUT_RETAIN = 8000 мс)
+2. Брокер отправляет **последний актуальный статус**
+3. Контроллер восстанавливает все значения: яркость, цвет, температуру и т.д.
+
+### Интерпретация команд
+
+Контроллер **интерпретирует** полученные команды:
+
+**Пример**:
+- Получена команда: `ON` на RGB канал
+- Контроллер восстанавливает последний цвет (HSV из памяти)
+- Публикует в `s_out/<item>/set` строку `240,100,255` («h,s,v[,ct]») и в `s_out/<item>/cmd` → `ON`
+
+### Различие нового подхода (/set и /cmd) и старого (общий топик, совместимо с шиной OpenHab)
+| Что | новый | openHab |
+|-----|:----:|:----:|
+| Команда управления | в /cmd| в общем топике |
+| Команда установки значения | в /set| в общем топике |
+| Диапазон значений | 0-255 | 0-100 |
+
+
+**Практика**:
+- `/set` используется для установки **значения** (например, яркость 0-255)
+- `/cmd` используется для **команд** (ON, OFF, TOGGLE ...)
+
+---
+
+## HTTP API
+
+### Базовый URL
+
+```
+http://<controller_ip>/item/<item_name>[/subitem][/suffix]
+```
+
+### Методы
+
+| Метод | Действие |
+|-------|----------|
+| `GET` | Прочитать статус item |
+| `POST` | Выполнить команду или установить значение |
+
+### Примеры HTTP запросов
+
+```bash
+# Включить лампу
+curl  --user arduino:password -X POST http://192.168.1.10/item/lamp1/cmd -d "ON" 
+
+# Установить яркость
+curl  --user arduino:password -X POST http://192.168.1.10/item/lamp1/set -d "150"
+
+# Установить цвет (HSV; /rgb не поддерживается)
+curl  --user arduino:password -X POST http://192.168.1.10/item/rgb_light/HSV -d "0,100,255"
+
+# Получить текущий статус
+curl  --user arduino:password -X GET http://192.168.1.10/item/lamp1
+
+# Многозональная вентиляция - установить T в спальне
+curl  --user arduino:password -X POST http://192.168.1.10/item/multivent/bedroom/set -d "22"
+
+# Кондиционер - установить режим
+curl  --user arduino:password -X POST http://192.168.1.10/item/ac_main/mode -d "HEAT"
+```
+
+### Дополнительные endpoints
+
+| Endpoint | Метод | Описание |
+|----------|-------|---------|
+| `/config.json` | GET, POST | Загрузить/сохранить конфигурацию |
+| `/config.bin` | GET, POST | Системная конфигурация |
+| `/sketch` | POST | Загрузить прошивку (OTA) |
+| `/command/<cmd>` | POST | Выполнить CLI команду |
+| `/ram/[item]` | GET | Дамп item-ов из RAM (JSON; без имени — все) |
+| `/` | GET | Переадресация на PWA приложение |
+
+---
+
+## MQTT подписки контроллера
+
+Контроллер автоматически подписывается на:
+
+1. **Командные широковещательные**: `root/bcst/#`
+2. **Командные индивидуальные**: `root/id-устройства/#`
+3. **Статусные** (только при старте, на 8 сек, TIMEOUT_RETAIN = 8000 мс): `root/out/+/+/#`
+4. **Служебные**: `$command` ловится общей подпиской `root/id-устройства/#` (отдельной подписки нет)
+
+---
+
+## Пример полной интеграции
+
+### Конфигурация
+
+```json
+{
+  "mqtt": ["lighthub01", "192.168.1.100", 1883],
+  "topics": {"root": "myhome", "bcst": "in", "out": "s_out"},
+  
+  "items": {
+    "lamp_bedroom": [0, 1],
+    "rgb_light": [1, 10],
+    "ac_main": [10, [1, {
+      "mode": {"emit": "ac/mode"},
+      "temp": {"emit": "ac/temp"}
+    }]]
+  }
+}
+```
+
+### MQTT команды и ответы
+
+```
+# Включить лампу
+→ myhome/in/lamp_bedroom/cmd: ON
+← myhome/s_out/lamp_bedroom/set: 255 (восстановленная яркость, 0-255)
+← myhome/s_out/lamp_bedroom/cmd: ON
+
+# Установить яркость RGB
+→ myhome/in/rgb_light/set: 200
+← myhome/s_out/rgb_light/set: 0,0,200,500 (в статусный топик запишется полный набор параметров канала)
+
+# Установить цвет
+→ myhome/in/rgb_light/hue: 240
+← myhome/s_out/rgb_light/set:  240,100,200,500 (в статусный топик запишется полный набор параметров канала)
+
+# Установить насыщенность 
+→ myhome/in/rgb_light/sat: 50
+← myhome/s_out/rgb_light/set:  240,50,200,500 (в статусный топик запишется полный набор параметров канала)
+
+# Включить кондиционер в режим HEAT
+→ myhome/in/ac_main/cmd: HEAT
+← myhome/s_out/ac_main/cmd: HEAT (запишется в статусный топик)
+
+# Установить температуру
+→ myhome/in/ac_main/set: 22
+← myhome/s_out/ac_main/set: 22 (запишется в статусный топик)
+```
+
+---
+
+## Диагностика MQTT
+
+### Проверка связи
+
+```bash
+# Подписаться на все топики контроллера
+mosquitto_sub -h 192.168.1.100 -t "myhome/#" -v
+
+# Отправить команду
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "ON"
+```
+
+### Проверка статусных топиков
+
+```bash
+# Только статусные топики
+mosquitto_sub -h 192.168.1.100 -t "myhome/s_out/#" -v
+```
+
+---
+
+**Версия документа**: 2.1 (актуально для работа_с_mqtt из wiki.lazyhome.ru)  
+**Источники**: [MQTT wiki](https://www.lazyhome.ru/dokuwiki/doku.php?id=%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0_%D1%81_mqtt), [API wiki](https://www.lazyhome.ru/dokuwiki/doku.php?id=api)
@@ -0,0 +1,302 @@
+# Шпаргалка MQTT LightHub
+
+> Быстрая справка часто используемых MQTT команд для LightHub
+
+---
+
+## Структура топика
+
+```
+root / [id или bcst или out] / item_name / [subitem/] suffix
+└──────┴─────────────────────────┴──────────────────────────┘
+  мyhome       /в/       /lamp1/   /cmd
+```
+
+**Пример для дома `myhome`, устройства `in`, лампы `lamp1`, команды включения**:
+```
+myhome/in/lamp1/cmd
+```
+
+---
+
+## Три типа топиков
+
+| Тип | Направление | Пример |
+|-----|:-----------:|--------|
+| **Команда (broadcast)** | вход | `myhome/in/lamp1/cmd` (выполнить на всех) |
+| **Команда (индивидуальная)** | вход | `myhome/lighthub01/lamp1/cmd` (на конкретном) |
+| **Статус** | выход | `myhome/s_out/lamp1/set` (0-255) + общий `myhome/s_out/lamp1` (0-100) |
+
+---
+
+## Базовые команды управления
+
+### Включение/выключение
+
+```bash
+# Включить лампу (ON)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "ON"
+
+# Выключить лампу (OFF)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "OFF"
+
+# Переключить (TOGGLE)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "TOGGLE"
+```
+
+### Установка яркости
+
+```bash
+# Установить яркость 50 из 255
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/set" -m "50"
+
+# Установить яркость 150 (0-255)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/set" -m "150"
+
+# Увеличить на 10 пунктов
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "INCREASE 10"
+
+# Уменьшить на 10 пунктов
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "DECREASE 10"
+```
+
+---
+
+## Управление RGB светом
+
+### Цвет по HSV (Hue, Saturation, Value)
+
+```bash
+# Оттенок (0-365°):
+#   0° = красный      60° = желтый    120° = зеленый
+#   180° = голубой    240° = синий    300° = магента
+
+# Установить красный цвет
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/rgb/hue" -m "0"
+
+# Установить зеленый
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/rgb/hue" -m "120"
+
+# Установить синий
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/rgb/hue" -m "240"
+
+# Установить насыщенность 0% = белый, 100% = полный цвет
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/rgb/sat" -m "100"
+
+# Установить яркость 200 (0-255)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/rgb/set" -m "200"
+
+# Установить полный HSV одной командой (hue,sat,value), суффикс ЗАГЛАВНЫЙ
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/rgb/HSV" -m "240,100,200"
+```
+
+### Цвет по RGB (не поддерживается)
+
+> Суффикс `/rgb` **не поддерживается** в текущей сборке (S_RGB не обрабатывается).
+> Цвет задаётся через `/HSV` или строкой «h,s,v[,ct]» в общем топике без суффикса.
+
+```bash
+# Красный (HSV: hue=0, sat=100, val=255)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/rgb/HSV" -m "0,100,255"
+
+# Зеленый (hue=120)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/rgb/HSV" -m "120,100,255"
+
+# Общий топик: строка «h,s,v[,ct]» трактуется как HSV(+colorTemp), не RGBW
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/rgb" -m "240,100,200"
+```
+
+---
+
+## Управление кондиционером
+
+```bash
+# Включить кондиционер
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/ac_main/cmd" -m "ON"
+
+# Выключить
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/ac_main/cmd" -m "OFF"
+
+# Режим нагрева (текстовые режимы HEAT, COOL, AUTO, DRY, FAN_ONLY — в /cmd; /mode — число 0-4)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/ac_main/cmd" -m "HEAT"
+
+# Температура
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/ac_main/set" -m "22"
+
+# Скорость вентилятора (LOW, MEDIUM, HIGH, OFF или число)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/ac_main/fan" -m "HIGH"
+
+# Направление воздуха (ON, OFF)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/ac_main/swing" -m "ON"
+
+# Тихий режим (входной subitem «queit» — опечатка в прошивке; статус — /quiet)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/ac_main/queit" -m "ON"
+
+# Блокировка ПДУ
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/ac_main/lock" -m "ON"
+```
+
+---
+
+## Управление теплыми полами (PID)
+
+```bash
+# Включить
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/floor/cmd" -m "ON"
+
+# Выключить
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/floor/cmd" -m "OFF"
+
+# Установить температуру 24°C
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/floor/set" -m "24"
+
+# Режим AUTO (включить, если T < установленной) — режим: команда в /cmd
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/floor/cmd" -m "AUTO"
+
+# Заморозить (игнорировать команды)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/floor/ctrl" -m "FREEZE"
+
+# Разморозить
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/floor/ctrl" -m "UNFREEZE"
+```
+
+---
+
+## Многозональная вентиляция
+
+```bash
+# Установить температуру в спальне
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/multivent/bedroom/set" -m "21"
+
+# Установить температуру на кухне
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/multivent/kitchen/set" -m "22"
+
+# Скорость вентилятора
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/multivent/fan" -m "HIGH"
+
+# Режим зоны (HEAT, AUTO, COOL) — команда в zone/cmd (zone/mode не обрабатывается)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/multivent/bedroom/cmd" -m "AUTO"
+```
+
+---
+
+## Команды с задержкой
+
+```bash
+# Включить на 3 секунды, потом выключить
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "ON 3000"
+
+# Включить через 5 сек 
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/del" -m "ON 5000"
+
+# Импульс гаража на 3 сек
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/gate/cmd" -m "ON 3000"
+```
+
+---
+
+## Расширенные команды
+
+```bash
+# Перевести в режим HALT (запомнить состояние и выключить)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "HALT"
+
+# Восстановить с HALT
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "REST"
+
+# Включить (если не DISABLE)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "XON"
+
+# Выключить (если был включен XON)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "XOFF"
+
+# Разрешить управление (если было DISABLE)
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/ctrl" -m "ENABLE"
+
+# Запретить управление
+mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/ctrl" -m "DISABLE"
+```
+
+---
+
+## Подписка на статусные топики
+
+```bash
+# Подписаться на все топики контроллера
+mosquitto_sub -h 192.168.1.100 -t "myhome/#" -v
+
+# Только статусные топики (ответы)
+mosquitto_sub -h 192.168.1.100 -t "myhome/s_out/#" -v
+
+# Статус конкретной лампы
+mosquitto_sub -h 192.168.1.100 -t "myhome/s_out/lamp1/#" -v
+
+# Служебная статистика
+mosquitto_sub -h 192.168.1.100 -t "myhome/lighthub01/\$stats" -v
+```
+
+---
+
+## HTTP API (альтернатива MQTT)
+
+```bash
+# Включить лампу: /item/<item>[/subitem][/suffix] (GET/POST)
+curl -X POST http://192.168.1.10/item/lamp1/cmd -d "ON"
+
+# Установить яркость
+curl -X POST http://192.168.1.10/item/lamp1/set -d "150"
+
+# Прочитать статус item (GET)
+curl -X GET http://192.168.1.10/item/lamp1
+
+# Передать вход сенсора (текущую температуру)
+curl -X POST http://192.168.1.10/item/thermostat/val -d "21.5"
+
+# AC: установить режим (командой) и температуру
+curl -X POST http://192.168.1.10/item/ac_main/cmd -d "HEAT"
+curl -X POST http://192.168.1.10/item/ac_main/set -d "22"
+
+# CLI-команда: /command/<cmd>
+curl -X POST http://192.168.1.10/command/reboot
+
+# Конфигурация (GET/POST) и дамп RAM
+curl http://192.168.1.10/config.json
+curl http://192.168.1.10/ram/lamp1
+```
+
+---
+
+## Типичные ошибки
+
+| Ошибка | Причина | Решение |
+|--------|---------|--------|
+| Команда не выполняется | Неправильный топик | Проверьте структуру: `root/bcst/item/suffix` |
+| Статус не приходит | Неправильный `out` параметр | Использовать `myhome/s_out/...` |
+| Яркость не меняется | Используется `/cmd` вместо `/set` | Используйте `/set` для значений (0-255) |
+| RGB не меняет цвет | Насыщенность 0% (белый) | Установите `/sat` на 100 для цвета |
+| Нет ответа от MQTT | Контроллер не подключен | Проверьте MQTT конфигурацию в `config.json` |
+
+---
+
+## Таблица суффиксов (краткая)
+
+| Суффикс | Использование | Примеры |
+|---------|--------------|---------|
+| `/cmd` | Команды | ON, OFF, TOGGLE, HALT, REST |
+| `/set` | Значения | 0-255, температура |
+| `/val` | Вход сенсора (THERMO/PID/VENT/SPRINKLER) | Число (T/значение) |
+| `/hue` | Оттенок RGB | 0-365° |
+| `/sat` | Насыщенность RGB | 0-100% |
+| `/HSV` | Полный HSV (ЗАГЛАВНЫЙ) | hue,sat,value |
+| `/rgb` | **Не поддерживается** (S_RGB не обрабатывается) | — |
+| `/fan` | Вентилятор | LOW, MEDIUM, HIGH, OFF или число|
+| `/mode` | Режим работы — число 0-4 (AC); текстовые режимы — через /cmd | 0-4 |
+| `/ctrl` | Управление | ENABLE, DISABLE, FREEZE, UNFREEZE |
+| `/del` | Задержка | "ON 5000" |
+
+---
+
+**Дополнительно**:
+- Полный справочник: [mqtt_api_reference.md](mqtt_api_reference.md)
+- Справочник суффиксов: [suffixes_reference.md](suffixes_reference.md)
+- Примеры конфигураций: [configuration_examples.md](configuration_examples.md)
@@ -0,0 +1,475 @@
+# Справочник суффиксов LightHub
+
+> **Инженерный справочник** всех суффиксов MQTT топиков для управления каналами LightHub.
+> Источник: [wiki.lazyhome.ru — работа с MQTT](https://www.lazyhome.ru/dokuwiki/doku.php?id=%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0_%D1%81_mqtt)
+
+---
+
+## Что такое суффикс?
+
+**Суффикс** — это завершающая часть MQTT топика, которая определяет **какое** свойство объекта меняется.
+
+### Анатомия полного топика
+
+```
+myhome/in/lamp_bedroom/set
+└─────┘ └─┘ └───────────┘ └──┘
+  root  bcst  item_name  suffix
+```
+
+---
+
+## Категории суффиксов
+
+### 1️⃣ Основные суффиксы (для всех типов каналов)
+
+| Суффикс | Вход | Выход | Назначение | Диапазон |
+|---------|:----:|:-----:|-----------|----------|
+| `/cmd` | ✅ | ✅ | Команда управления (ON, OFF, TOGGLE) | Текст (команда) |
+| `/set` | ✅ | ✅ | Установка численного значения | 0-255 (шкала 0-100 — только в общем топике без суффикса) |
+| `/val` | ✅ | ❌ | Вход сенсора (THERMO, PID, MULTIVENT, SPRINKLER) | Число (T / значение) |
+| `/raw` | ✅ | ✅ | «Сырые» данные, передаваемые драйверу без интерпретации | Текст / число |
+| `/del` | ✅ | ❌ | Команда с задержкой. Только команды ON…FAN_ONLY (код ≤ 0x0F); HIGH/MEDIUM/LOW/HEAT_COOL/HEAT/COOL/DRY запланировать нельзя | Текст (команда + время) |
+
+> **Полный список команд** (payload `/cmd`): `ON`, `OFF`, `REST`, `TOGGLE`, `HALT`, `XON`, `XOFF`, `INCREASE`, `DECREASE`, `ENABLE`, `DISABLE`, `UNFREEZE`, `FREEZE`, `AUTO`, `FAN_ONLY`, `HIGH`, `MEDIUM`, `LOW`, `HEAT_COOL`, `HEAT`, `COOL`, `DRY`, `RGB`, `HSV`, `RESET`.
+> `TOGGLE` в `/ctrl` не включает/выключает, а **инвертирует флаг DISABLE**.
+
+### 2️⃣ Цветовые суффиксы (RGB/RGBW/RGBWW)
+
+| Суффикс | Вход | Выход | Назначение | Диапазон |
+|---------|:----:|:-----:|-----------|----------|
+| `/hue` | ✅ | ✅ | Оттенок (HSV) | 0-365° |
+| `/sat` | ✅ | ✅ | Насыщенность (HSV) | 0-100% |
+| `/HSV` | ✅ | ✅ | Полный цвет (hue,sat,val). Суффикс ЗАГЛАВНЫЙ, строчный `/hsv` игнорируется | `H,S,V` |
+| `/rgb` | ❌ | ❌ | **Не поддерживается** в текущей сборке (S_RGB нигде не обрабатывается) | — |
+| `/temp` | ✅ | ✅ | Цветовая температура 153-500 mireds (RGBWW); у AC — текущая T | 153-500 |
+
+**Примеры**:
+```
+# Установить красный цвет (hue=0)
+myhome/in/rgb_light/hue → 0
+
+# Установить насыщенность 50%
+myhome/in/rgb_light/sat → 50
+
+# Установить HSV 240,100,200 (синий максимум)
+myhome/in/rgb_light/HSV → 240,100,200
+
+# Тот же цвет строкой «h,s,v[,ct]» в общем топике (без суффикса)
+myhome/in/rgb_light → 240,100,200
+```
+
+**Особенности HSV**:
+- `0°` — красный
+- `60°` — желтый
+- `120°` — зеленый
+- `180°` — голубой
+- `240°` — синий
+- `300°` — магента
+
+### 3️⃣ Суффиксы кондиционера (AC)
+
+| Суффикс | Вход | Выход | Назначение | Значения |
+|---------|:----:|:-----:|-----------|----------|
+| `/cmd` | ✅ | ✅ | Включить/выключить кондиционер | ON, OFF, TOGGLE |
+| `/mode` | ✅ | ✅ | Режим работы — число 0-4 (текстовые режимы — payload в `/cmd`) | 0-4 |
+| `/set` | ✅ | ✅ | Установленная температура | 16-40 (или диапазон устройства) |
+| `/fan` | ✅ | ✅ | Скорость вентилятора | LOW, MEDIUM, HIGH, OFF или число |
+| `/lock` | ✅ | ✅ | Блокировка ПДУ | ON, OFF |
+| `/swing` | ✅ | ✅ | Направление воздушного потока | ON, OFF |
+| `/quiet` | ✅ | ✅ | Режим "тихой работы". Входной subitem — «queit» (опечатка в прошивке); статус публикуется в `/quiet` | ON, OFF |
+
+**Примеры**:
+```
+# Включить кондиционер
+myhome/in/ac_main/cmd → ON
+
+# Установить режим нагрева (текстовые режимы — в /cmd)
+myhome/in/ac_main/cmd → HEAT
+
+# Установить температуру 22°C
+myhome/in/ac_main/set → 22
+
+# Максимальная скорость вентилятора
+myhome/in/ac_main/fan → HIGH
+
+# Включить тихий режим (входной subitem «queit» — опечатка в прошивке)
+myhome/in/ac_main/queit → ON
+```
+
+**Логика срабатывания AC**:
+- При получении команды на `/cmd` кондиционер сохраняет **последний режим, температуру и скорость вентилятора**
+- При выключении (`OFF`) эти значения **восстанавливаются** при включении (`ON`)
+
+### 4️⃣ Суффиксы воздушного отопления (Multivent)
+
+| Суффикс | Вход | Выход | Назначение | Диапазон |
+|---------|:----:|:-----:|-----------|----------|
+| `/cmd` | ✅ | ✅ | Включить/выключить | ON, OFF, TOGGLE |
+| `/set` | ✅ | ✅ | Установленная температура | Текущее значение |
+| `/fan` | ✅ | ✅ | Скорость вентилятора (HIGH/MEDIUM/LOW → 255/128/64) | HIGH, MEDIUM, LOW |
+| `/mode` | ✅ | ❌ | Только у основного item (обратная связь от AC). У зон S_MODE не обрабатывается — режим зоны задаётся командой в `zone/cmd` | — |
+
+**Структура многозональной вентиляции**:
+
+```json
+{
+  "items": {
+    "multivent": [
+      18,
+      {
+        "bedroom":  {"set": 21.0, "fan": 0, "cmd": 14, "item": "ac_bedroom/set"},
+        "kitchen":  {"set": 22.0, "fan": 0, "cmd": 14, "item": "ac_kitchen/set"},
+        "bathroom": {"set": 21.0, "fan": 0, "cmd": 14, "item": "ac_bathroom/set"}
+      }
+    ]
+  }
+}
+```
+
+**MQTT топики для subitem-ов**:
+```
+# Спальня — установить T
+myhome/in/multivent/bedroom/set → 21
+
+# Кухня — установить T
+myhome/in/multivent/kitchen/set → 22
+
+# Ванная — включить вентилятор
+myhome/in/multivent/bathroom/fan → HIGH
+```
+
+### 5️⃣ Суффиксы термостата (PID контроллер)
+
+| Суффикс | Вход | Выход | Назначение | Диапазон |
+|---------|:----:|:-----:|-----------|----------|
+| `/cmd` | ✅ | ✅ | Включить/выключить регулировку | ON, OFF, TOGGLE |
+| `/set` | ✅ | ✅ | Установленная температура | Температура в °C |
+| `/ctrl` | ✅ | ✅ | Управление состоянием | ENABLE, DISABLE |
+| `/mode` | ❌ | ❌ | Не поддерживается — режим (HEAT, AUTO) задаётся командой в `/cmd` | — |
+
+**Примеры**:
+```
+# Включить теплые полы
+myhome/in/floor/cmd → ON
+
+# Установить температуру 25°C
+myhome/in/floor/set → 25
+
+# Включить автоматический режим (режим — команда в /cmd)
+myhome/in/floor/cmd → AUTO
+
+# Разрешить управление (если было запрещено)
+myhome/in/floor/ctrl → ENABLE
+```
+
+**Состояние-зависимые команды**:
+
+Для сложного сценария можно использовать **subitem** как условие — контроллер только выполнит команду, если item находится в этом состоянии.
+
+```
+# Включить режим HEAT только если установлен режим HEAT
+myhome/in/floor/HEAT/cmd → ON
+
+# Выключить режим OFF только если уже в режиме OFF
+myhome/in/floor/OFF/cmd → OFF
+```
+
+### 6️⃣ Суффиксы для импульсных каналов и ШИМ
+
+| Суффикс | Вход | Выход | Назначение | Диапазон |
+|---------|:----:|:-----:|-----------|----------|
+| `/cmd` | ✅ | ✅ | Включить/выключить (импульсный выход) | ON, OFF, TOGGLE |
+| `/set` | ✅ | ✅ | Скважность ШИМ | 0-255 |
+| `/del` | ✅ | ❌ | через какое время выполнить | `ON ВРЕМЯ_МС` |
+
+**Примеры**:
+```
+# Импульс реле (включить на 3 сек, потом выключить)
+myhome/in/gate/cmd → "ON 3000"
+
+# ШИМ вентилятор 50%
+myhome/in/fan/set → 128
+
+# Активировать сирену через 5 сек 
+myhome/in/siren/del → "ON 5000"
+```
+
+### 7️⃣ Суффиксы для управления состоянием
+
+| Суффикс | Использование | Назначение | Примеры |
+|---------|--------------|-----------|---------|
+| `/ctrl` | Все | Специальное управление состоянием | ENABLE, DISABLE, FREEZE, UNFREEZE, TOGGLE (инвертирует DISABLE) |
+| Условный subitem | Строки состояния | Выполнить команду при условии | `/AUTO`, `/OFF`, `/ON`, `/HEAT`, `/COOL` |
+
+**Примеры управления**:
+```
+# Заморозить (запретить изменения, но не выключать)
+myhome/in/light/ctrl → FREEZE
+
+# Разморозить
+myhome/in/light/ctrl → UNFREEZE
+
+# Выполнить включение только если в режиме OFF
+myhome/in/device/OFF/cmd → ON
+# (не выполнится, если device уже ON)
+
+# Выполнить команду только в режиме HEAT (для AC)
+myhome/in/ac/HEAT/set → 25
+# (установит 25°C только если AC в режиме HEAT)
+```
+
+---
+
+## Таблица применимости суффиксов по типам каналов
+
+### По типам из конфигурации
+
+| Номер | Тип канала | Суффиксы | Примеры |
+|:-----:|-----------|----------|---------|
+| 0 | CH_DIMMER (DMX 1-4 ch) | `/cmd`, `/set` (subitem-адресация игнорируется) | Лампа, светодиод |
+| 1 | CH_RGBW (DMX 4 ch) | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV`, `/temp` | RGBW люстра |
+| 2 | CH_RGB (DMX 3 ch) | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV` | RGB лента, LED |
+| 3 | CH_PWM | `/cmd`, `/set` | PWM вывод |
+| 4 | CH_MODBUS | `/cmd`, `/set` | Modbus диммер |
+| 5 | CH_THERMO | `/cmd`, `/set`, `/val` (вход сенсора), `/ctrl` | Термостат |
+| 6 | CH_RELAY | `/cmd`, `/set`, `/del` | Реле, розетка |
+| 7 | CH_GROUP | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV` | Группа каналов |
+| 8 | CH_VCTEMP | — | Регулятор Vacon (PID) |
+| 9 | CH_VC | — | Привод Vacon (Modbus) |
+| 10 | CH_AC (Haier) | `/cmd`, `/set` (16-40), `/mode` (0-4), `/fan`, `/lock`, `/swing`, `/queit` (статус `/quiet`), `/temp`, `/raw` | Кондиционер |
+| 11 | CH_SPILED | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV` + subitem-пиксели 10-20 | Адресуемая LED лента |
+| 12 | CH_MOTOR | `/cmd`, `/set` | Сервопривод |
+| 13 | CH_PID | `/cmd`, `/set`, `/val` (вход сенсора), `/ctrl` | PID регулятор, теплые полы |
+| 14 | CH_MBUS | `/cmd`, `/set` | Modbus устройство |
+| 15 | CH_UARTBRIDGE | `/cmd`, `/set` | UART-мост |
+| 16 | CH_RELAYX | `/cmd`, `/set`, `/del` | Реле + ШИМ |
+| 17 | CH_RGBWW (DMXRGBWW) | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV`, `/temp` | Теплый+холодный белый |
+| 18 | CH_MULTIVENT | `/cmd`, `/set`, `/fan` + zone-subitem-ы (`set`, `fan`, `cmd`) | Многозональная вентиляция |
+| 19 | CH_ELEVATOR | `/cmd`, `/set`, `/raw` | Лифт |
+| 20 | CH_COUNTER | `/cmd`, `/set` | Счетчик |
+| 21 | CH_HUMIDIFIER | `/cmd` | Увлажнитель |
+| 22 | CH_MERCURY | — | Счетчик электроэнергии |
+| 23 | CH_SPRINKLER | `/cmd`, `/set`, `/val` | Полив (ирригатор) |
+
+---
+
+## Примеры сценариев
+
+### Сценарий 1: Управление RGB лампой
+
+**Конфигурация**:
+```json
+"items": {
+  "rgb_lamp": [2, 1]
+}
+```
+
+**Команды**:
+```
+# Включить белый (полная насыщенность)
+myhome/in/rgb_lamp/sat → 0
+
+# Установить красный цвет
+myhome/in/rgb_lamp/hue → 0
+
+# Установить желтый на 80% яркости
+myhome/in/rgb_lamp/HSV → 60,100,200
+
+# Выключить
+myhome/in/rgb_lamp/cmd → OFF
+```
+
+### Сценарий 2: Система управления кондиционером
+
+**Конфигурация**:
+```json
+"items": {
+  "ac_hallway": [10, 0]
+}
+```
+(portNum = 0)
+
+**Команды**:
+```
+# Включить, установить HEAT, 22°C, вентилятор на максимум
+myhome/in/ac_hallway/cmd → ON
+myhome/in/ac_hallway/cmd → HEAT
+myhome/in/ac_hallway/set → 22
+myhome/in/ac_hallway/fan → HIGH
+
+# Выключить
+myhome/in/ac_hallway/cmd → OFF
+
+# Ответы от контроллера
+myhome/s_out/ac_hallway/cmd → HEAT     (текстовый режим публикуется в /cmd)
+myhome/s_out/ac_hallway/mode → <0-4>   (числовой режим)
+myhome/s_out/ac_hallway/set → 22
+myhome/s_out/ac_hallway/fan → HIGH
+```
+
+### Сценарий 3: Управление теплыми полами (PID)
+
+**Конфигурация**:
+```json
+"items": {
+  "floor_heating": [13, [
+    [1.0, 0.05, 0.02, 5.0],
+    {"item": "heater/set"}
+  ], 22]
+}
+```
+(13 — CH_PID; 2-й аргумент — массив `[kP,kI,kD,dT,…], {выходной execObj}, {каскад}]`; 3-й — стартовый setpoint 22°C)
+
+**Команды**:
+```
+# Включить отопление
+myhome/in/floor_heating/cmd → ON
+
+# Установить температуру 24°C
+myhome/in/floor_heating/set → 24
+
+# Установить режим AUTO (включить, если T < установленной) — режим: команда в /cmd
+myhome/in/floor_heating/cmd → AUTO
+
+# Заморозить (не менять значение)
+myhome/in/floor_heating/ctrl → FREEZE
+
+# Разморозить
+myhome/in/floor_heating/ctrl → UNFREEZE
+```
+
+### Сценарий 4: Многозональная вентиляция
+
+**Конфигурация**:
+```json
+"items": {
+  "multivent": [18, {
+    "bedroom": {"set": 21.0, "fan": 0, "cmd": 14, "item": "ac_bedroom/set"},
+    "kitchen": {"set": 22.0, "fan": 0, "cmd": 14, "item": "ac_kitchen/set"}
+  }]
+}
+```
+
+**Команды**:
+```
+# Спальня: установить 21°C
+myhome/in/multivent/bedroom/set → 21
+
+# Кухня: установить 20°C
+myhome/in/multivent/kitchen/set → 20
+
+# Оба: включить вентилятор на максимум
+myhome/in/multivent/cmd → ON
+myhome/in/multivent/fan → HIGH
+
+# Ответы (статус зоны публикуется в суффикс ввода: /set, /fan, /cmd; периодического /val нет)
+myhome/s_out/multivent/bedroom/set → 21.0
+myhome/s_out/multivent/kitchen/set → 22.0
+```
+
+---
+
+## Диапазоны значений и конвертация
+
+### Различие между /cmd и /set
+
+| Параметр | /cmd | /set |
+|----------|------|------|
+| **Тип данных** | Текст (команда) | Число (значение) |
+| **Диапазон** | Команды | 0-255 |
+| **Диапазон (общий топик, OpenHAB)** | Команды | 0-100 (только в общем топике без суффикса) |
+| **Примеры** | ON, OFF, TOGGLE | 128, 255 |
+| **Когда использовать** | Нужна команда (ON/OFF) | Нужно установить значение |
+
+### Шкалы значений
+
+- `/set` — всегда **0-255**
+- Шкала **0-100** — только в **общем топике без суффикса** (`myhome/in/lamp1`) — совместимость с OpenHAB
+
+### Специальные диапазоны
+
+| Суффикс | Диапазон | Особенность |
+|---------|----------|-----------|
+| `/set` | 0-255 | 0-100 — только в общем топике без суффикса |
+| `/hue` | 0-365 | Градусы в цветовом круге (0=красный) |
+| `/sat` | 0-100 | Проценты (0=белый, 100=полная насыщенность) |
+| `/fan` | LOW, MEDIUM, HIGH, OFF или число | Текстовые значения / число 0-255 |
+| `/mode` | 0-4 (число) | Режимы-тексты — в /cmd |
+
+---
+
+## Связь между суффиксами
+
+### Синергия RGB суффиксов
+
+```
+Команда          Результат
+────────────────────────────────────────
+/cmd → ON        Включить, восстановить последний цвет
+/cmd → OFF       Выключить
+/hue → 240       Поменять оттенок на синий
+/sat → 50        Поменять насыщенность
+/HSV → 240,100,255  Установить полный цвет (синий максимум)
+```
+
+**Публикуемые значения** (статусных /hue, /sat, /val для ламп не существует):
+```
+myhome/s_out/rgb_lamp/set → 240,100,255   (строка «h,s,v[,ct]»)
+myhome/s_out/rgb_lamp/cmd → ON
+```
+
+### Синергия AC суффиксов
+
+```
+Команда                    Состояние
+────────────────────────────────────────
+/cmd → ON                  Включить (восстановить режим/T)
+/cmd → HEAT                Установить режим нагрева (текстовые режимы — в /cmd)
+/set → 22                  Установить 22°C
+/fan → HIGH                Максимальная скорость вентилятора
+/lock → ON                 Заблокировать ПДУ (только кондиционер)
+/swing → ON                Включить направление воздуха
+/queit → ON                Тихий режим (опечатка в прошивке; статус — /quiet)
+```
+
+---
+
+## Видео-примеры и интеграции
+
+### Home Assistant интеграция
+
+```yaml
+switch:
+  - platform: mqtt
+    name: "Лампа спальня"
+    command_topic: "myhome/in/lamp_bedroom/cmd"
+    state_topic: "myhome/s_out/lamp_bedroom/cmd"
+    payload_on: "ON"
+    payload_off: "OFF"
+    
+light:
+  - platform: mqtt
+    name: "RGB лампа"
+    command_topic: "myhome/in/rgb_lamp/cmd"
+    brightness_command_topic: "myhome/in/rgb_lamp/set"
+    brightness_state_topic: "myhome/s_out/rgb_lamp/set"
+    hs_command_topic: "myhome/in/rgb_lamp/HSV"
+    hs_state_topic: "myhome/s_out/rgb_lamp/set"   # строка «h,s,v[,ct]»
+    payload_on: "ON"
+    payload_off: "OFF"
+```
+
+### Иных систем управления
+
+Большинство MQTT систем (OpenHAB, Home Assistant, Node-Red и др.) поддерживают:
+- `/cmd` — переключатели (ON/OFF)
+- `/set` — диммеры (0-255; 0-100 — только в общем топике без суффикса)
+- `/val` — вход сенсора (THERMO, PID, MULTIVENT, SPRINKLER)
+- Цветовые суффиксы `/hue`, `/sat`, `/HSV`
+
+---
+
+**Версия документа**: 2.0 (обновлено для соответствия wiki.lazyhome.ru)  
+**Последнее обновление**: 2024  
+**Источник**: https://www.lazyhome.ru/dokuwiki/doku.php?id=%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0_%D1%81_mqtt
@@ -0,0 +1,436 @@
+# LightHub: Полная техническая таблица типов каналов
+
+> **Инженерный справочник** — полная таблица всех типов каналов (0-23) с параметрами, синтаксисом и примерами кода.
+> Источник: [lighthub/item.h](../../lighthub/item.h), строки 48-72
+
+---
+
+## Быстрая таблица типов
+
+| Код | Тип | Англ. | Рус. описание | Конф. тип | Примеры параметров |
+|-----|-----|-------|---------|-----------|-------------------|
+| 0 | DMX | DMX Dimmer | DMX одного или нескольких каналов | int/array | `1` или `[1,2,3,4]` |
+| 1 | DMXRGBW | DMX RGBW | DMX RGB+White (4 канала) | int | `10` (DMX 10-13) |
+| 2 | DMXRGB | DMX RGB | DMX RGB (3 канала) | int | `15` (DMX 15-17) |
+| 3 | PWM | PWM Output | GPIO PWM (1-5 каналов) | int/array | `9` или `[11,12,13,14]` |
+| 4 | MBUSDIM | Modbus Dimmer | AC диммер Modbus (Legacy) | array | `[96, 0, 0, 255]` |
+| 5 | THERMO | Thermostat | ON/OFF термостат | array | `[24, 33]` (GPIO, T°C) |
+| 6 | RELAY | Relay Output | GPIO реле | int | `23` (GPIO pin) |
+| 7 | GROUP | Group Channel | Логическая группа каналов | array | `["lamp1", "lamp2"]` |
+| 8 | VCTEMP | Vacom Temp | Температура из VC-канала | string | `"fm"` (имя CH_VC канала) |
+| 9 | MBUSVC | Vacom Motor | Vacom мотор регулятор | array | `[96, "a_ext"]` (адрес, имя) |
+| 10 | ACHAIER | AC Haier | Кондиционер Haier (UART) | int | `1` (порт 0-3) |
+| 11 | SPILED | SPI LED | NeoPixel LED лента | array | `[7, 8]` (data-пин 7, 8 светодиодов) |
+| 12 | MOTOR | Motor | Моторная задвижка с обратной связью | array | `[9, 10, 11, 0, 255, 30000]` |
+| 13 | PID | PID Regulator | PID регулятор | array | `[[1.0,0.05,...],{...}]` |
+| 14 | MBUS | Modbus | Universal Modbus v2 | array | `[96, "template", {...}]` |
+| 15 | UARTBRDG | UART Bridge | UART мост | object | `{"serial","baud","ip","port","hd","log","bond"}` |
+| 16 | RELAYX | Relay PWM | Медленный PWM реле | array | `[22, 60]` (GPIO, период_сек) |
+| 17 | DMXRGBWW | DMX RGBWW | DMX RGB+2White (5 каналов) | int | `30` (DMX 30-34) |
+| 18 | VENTS | Multivent | Многозональная вентиляция | object | `{зоны}` (без Modbus-адреса) |
+| 19 | ELEVATOR | Elevator | Лифт (реализован) | object | `{"serial":"8N1","baud":19200}` |
+| 20 | COUNTER | Counter | Счётчик импульсов | int/array | `0` или `[0.02, 1.2]` |
+| 21 | HUM | Humidifier | Увлажнитель (один в системе) | array | `[[13,14,15,120,15,50,5,25], {зоны}]` |
+| 22 | MERCURY | Mercury Meter | Счётчик энергии Mercury | array | `[1, 9600, "8N1", 2, "123456"]` |
+| 23 | SPRINKLR | Irrigation System | Система полива | object/array | `{конфиг}` или `[имя, {зоны}]` |
+
+---
+
+## Определения из item.h
+
+```cpp
+#define CH_DIMMER 0      //DMX 1-4 ch
+#define CH_RGBW   1      //DMX 4 ch
+#define CH_RGB    2      //DMX 3 ch
+#define CH_PWM    3      //PWM output directly to PIN 1-4 CH
+#define CH_MODBUS 4      //Modbus AC Dimmer
+#define CH_THERMO 5      //Simple ON/OFF thermostat
+#define CH_RELAY  6      //ON_OFF relay output
+#define CH_GROUP   7     //Group pseudochannel
+#define CH_VCTEMP  8     //Vacom PID regulator
+#define CH_VC      9     //Vacom modbus motor regulator
+#define CH_AC 10         //AC Haier
+#define CH_SPILED 11
+#define CH_MOTOR  12
+#define CH_PID   13
+#define CH_MBUS  14
+#define CH_UARTBRIDGE  15
+#define CH_RELAYX 16
+#define CH_RGBWW    17
+#define CH_MULTIVENT 18
+#define CH_ELEVATOR 19
+#define CH_COUNTER 20
+#define CH_HUMIDIFIER 21
+#define CH_MERCURY 22
+#define CH_SPRINKLER 23
+#define CH_MAX 23
+```
+
+---
+
+## Детальная таблица (с командами и суффиксами)
+
+### CH_DIMMER (0) — DMX Диммер
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Управление яркостью 1-5 DMX каналов (3=RGB, 4=RGBW, 5=RGBWW) |
+| **Конфигурация** | int (один канал) или array (несколько) |
+| **Формат конфига** | `[0, 1]` или `[0, [1,2,3,4]]` |
+| **Диапазон значений** | 0-255 (яркость) |
+| **Поддерживаемые команды** | ON, OFF, TOGGLE, INCREASE, DECREASE (+ REST, HALT, XON, XOFF) |
+| **Суффиксы** | /cmd, /val, /set |
+| **Начальное значение** | Опционально (элемент 3) |
+| **MQTT примеры** | `myhome/<имя_контроллера>/lamp/cmd ← ON`, `myhome/<имя_контроллера>/lamp/set ← 150` (индивидуальный командный топик) |
+
+### CH_RGBW (1) — DMX RGB+White
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | RGB + White через DMX 512 (4 канала) |
+| **Конфигурация** | int (стартовый DMX канал) |
+| **Формат конфига** | `[1, 10]` (DMX каналы 10-13) |
+| **Диапазон значений** | 0-255 (для каждого канала) |
+| **Суффиксы** | /cmd, /val, /set, /hue, /sat, /temp, /RGB |
+| **MQTT формат RGB** | `255,128,0` (R,G,B) |
+| **MQTT формат RGBW** | `255,128,0,100` (R,G,B,W) |
+| **MQTT команды** | `/HSV`, `/RGB`, `/hue`, `/sat`, `/temp` |
+
+### CH_RGB (2) — DMX RGB
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | RGB через DMX 512 (3 канала) |
+| **Конфигурация** | int (стартовый DMX канал) |
+| **Формат конфига** | `[2, 15]` (DMX каналы 15-17) |
+| **Суффиксы** | /cmd, /val, /set, /hue, /sat, /temp, /RGB |
+
+### CH_PWM (3) — GPIO PWM
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | ШИМ на GPIO пины Arduino/ESP |
+| **Конфигурация** | int (один pin) или array (несколько) |
+| **Формат конфига** | `[3, 9]` или `[3, [11, 12, 13]]` |
+| **GPIO диапазон** | 0-53 (зависит от платы) |
+| **Диапазон PWM** | 0-255 |
+| **Частота** | 4000 Гц (Mega2560, таймеры 3/4); на ESP32 PWM недоступен (stub) |
+| **Суффиксы** | /cmd, /val, /set |
+
+### CH_MODBUS (4) — AC Dimmer (Legacy)
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Управление AC-диммером через Modbus (устаревшее) |
+| **Конфигурация** | array `[addr, reg, mask, max_val]` |
+| **Параметры** | - addr: Modbus адрес (1-247)<br>- reg: регистр (обычно 0)<br>- mask: маска (0, 1, 2 (пропуск 16 бит), 3 (Modbus relay), 4 (swap байтов), -1/отсутствует — без поллинга)<br>- max_val: максимальное значение (обычно 255) |
+| **Примечание** | **Использовать CH_MBUS (14) для новых проектов** |
+
+### CH_THERMO (5) — ON/OFF Термостат
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Простой ON/OFF термостат с гистерезисом |
+| **Конфигурация** | array `[gpio_pin, target_temp_C]` |
+| **GPIO диапазон** | 0-53 (в зависимости от платы) |
+| **Температура** | Уставка ограничена ≤80 °C |
+| **Гистерезис** | Включение при T<уставка−1, выключение при T≥уставка |
+| **MQTT команды** | `/set` (целевая T), `/val` (вход текущей температуры) |
+
+### CH_RELAY (6) — GPIO Реле
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Электромагнитное реле ON/OFF |
+| **Конфигурация** | int (GPIO pin) или array `[gpio, val, cmd]` |
+| **GPIO диапазон** | 0-53 |
+| **Выходное напряжение** | 5V или 3.3V (в зависимости от платы) |
+| **Макс. ток** | 40 мА на pin (требуется транзистор для реле) |
+| **Состояния** | 0 = OFF, 1 = ON |
+
+### CH_GROUP (7) — Группа каналов
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Логическая группа для синхронного управления |
+| **Конфигурация** | array с именами каналов |
+| **Формат конфига** | `[7, ["lamp1", "lamp2", "rgb1"]]` |
+| **Команды** | ON, OFF, TOGGLE, SET (для диммеров) |
+| **Рекурсия** | Поддерживается (группы в группах) |
+
+### CH_VCTEMP (8) — Vacom PID Терморегулятор
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Публикация температуры из VC-канала Vacom |
+| **Конфигурация** | string — имя_канала_VC (itemArg — строка-имя item типа CH_VC (9)) |
+| **Пример** | `[8, "fm"]` |
+
+### CH_VC (9) — Vacom Мотор-регулятор
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Управление мотор-регулятором вентилятора |
+| **Конфигурация** | array `[modbus_адрес, "имя_объекта"]` |
+| **Пример** | `[9, [96, "a_ext"]]` |
+
+### CH_AC (10) — Кондиционер Haier
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Управление кондиционером Haier |
+| **Конфигурация** | `[10, portNum(0-3)]` |
+| **Порт** | Номер serial порта (0-3) |
+| **Режимы** | AUTO, FAN_ONLY, HEAT, COOL, DRY, HEAT_COOL (текст — в payload /cmd; /mode — число); fan: LOW/MEDIUM/HIGH; /set 16-40 |
+| **Требует** | Проприетарный UART-протокол Haier (9600, кадры 13/37 байт) |
+
+### CH_SPILED (11) — SPI LED Лента
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Управление адресуемой NeoPixel LED лентой |
+| **Конфигурация** | array `[data_pin, numLeds (дефолт 43), ledsType]` — CLK-пина нет |
+| **Протокол** | NeoPixel (один data-пин); по умолчанию Adafruit NeoPixel, при FASTLED — TM1809 |
+| **Диапазон пинов** | 0-53 |
+
+### CH_MOTOR (12) — Моторная задвижка с обратной связью
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Управление моторной задвижкой с обратной связью (позиционная, цель 0-255) |
+| **Конфигурация** | array `[pinUp, pinDown, pinFeedback, fbOpen, fbClosed, maxOnTime_ms]` (PWM-пина в конфиге нет) |
+| **pinUp/pinDown** | Пины движения в стороны открытия/закрытия |
+| **pinFeedback** | Аналоговый датчик положения; fbOpen/fbClosed — калибровка обратной связи |
+| **maxOnTime** | Максимальное время движения (мс, дефолт 10000) |
+| **Команды** | ON — к заданной позиции, OFF — в позицию 0, HALT |
+
+### CH_PID (13) — PID Регулятор
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Универсальный PID контроллер |
+| **Конфигурация** | array `[[Kp, Ki, Kd, dT, timeout, alarm, min, max], {...exec}, {...exec}]` |
+| **Kp** | Коэффициент пропорциональности |
+| **Ki** | Коэффициент интеграла |
+| **Kd** | Коэффициент дифференциала |
+| **dT** | Интервал расчёта (сек) |
+| **timeout** | Время до аварии (сек) |
+| **alarm** | Значение аварии |
+| **min/max** | Диапазон выхода |
+
+### CH_MBUS (14) — Universal Modbus
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Универсальный Modbus канал с полной поддержкой |
+| **Конфигурация** | array `[addr, "template", {params}]` |
+| **Addr** | Modbus адрес устройства |
+| **Template** | Имя шаблона из секции "modbus" |
+| **Params** | Привязка параметров к MQTT/items |
+| **Тип данных** | i16, i32, u16, u32, i8h, i8l, u8h, u8l, x10, 100 |
+
+### CH_UARTBRIDGE (15) — UART Мост
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Мост между двумя UART портами |
+| **Конфигурация** | object `{serial, baud, ip, port, hd, log, bond}` (порты фиксированы) |
+| **Отладка** | Может логировать через UDP |
+
+### CH_RELAYX (16) — Медленный PWM через реле
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Медленный PWM для инертных систем |
+| **Конфигурация** | array `[gpio_pin, period_seconds]` |
+| **GPIO pin** | Управление реле |
+| **Период** | Цикл коммутации в секундах (дефолт 5 с, ограничений нет) |
+| **Применение** | Система напольного отопления, тепловые системы |
+
+### CH_RGBWW (17) — DMX RGBWW
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | RGB + Тёплый белый + Холодный белый |
+| **Конфигурация** | int (стартовый DMX) |
+| **Каналов DMX** | 5 (R, G, B, W_warm, W_cold) |
+| **Формат** | DMX 30-34 (5 каналов) |
+
+### CH_MULTIVENT (18) — Многозональная вентиляция
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Каскадная система вентиляции с зонами |
+| **Конфигурация** | объект зон `[18, {zones}]` (Modbus-адреса нет) |
+| **Зоны** | Независимое регулирование T по комнатам |
+| **PID** | Для каждой зоны свои коэффициенты |
+| **itemArg** | объект зон (не массив с адресом) |
+
+### CH_ELEVATOR (19) — Лифт
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Управление лифтом |
+| **Конфигурация** | `[19, {"serial":"8N1","baud":19200,"log":...}]` |
+| **Статус** | Реализован; компилируется с ELEVATOR_ENABLE (включён только в custom-build mega2560-optiboot) |
+
+### CH_COUNTER (20) — Счётчик импульсов
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Счётчик импульсов (кВт·ч, м³, л) |
+| **Конфигурация** | int или array `[коэффициент_импульса, период_сек]` |
+| **Coefficient** | Кол-во единиц на один импульс |
+| **Период** | Период автосуммирования (сек) |
+| **Вход** | Внешние импульсы (GPIO-входа в конфиге нет) |
+
+### CH_HUMIDIFIER (21) — Увлажнитель
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Управление увлажнителем воздуха (только один в системе) |
+| **Конфигурация** | array `[[pumpPin, flushPin, pressurePin, maxPumpTime, idleTime, capacity, minLevel, startLevel], {зоны_краны}, motorExecObj, faultExecObj]` |
+| **Сборка** | Компилируется с HUMIDIFIER_ENABLE (custom lighthub21) |
+
+### CH_MERCURY (22) — Счётчик энергии Mercury
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Счётчик электроэнергии Mercury по RS485 |
+| **Конфигурация** | array `[addr, baud, serial, уровень_доступа, пароль, pollingInterval]` |
+| **Addr** | Modbus адрес счётчика (1-247) |
+| **Baud** | 9600 (стандарт) |
+| **Serial** | "8N1" (стандарт) |
+| **Уровень доступа** | Уровень доступа к счётчику |
+| **Пароль** | Строка из 6 цифр или массив 6 цифр |
+| **PollingInterval** | Интервал опроса (мс, дефолт 10000) |
+
+### CH_SPRINKLER (23) — Система полива
+
+| Параметр | Значение |
+|----------|----------|
+| **Назначение** | Многозональная система автоматического полива (строковое имя типа — SPRINKLR) |
+| **Конфигурация** | `[23, {конфиг}]` или `[23, имя, {зоны}]` |
+| **Корневой объект ("" )** | пины vIn, rDren, rPump, wMax, wMin, fbDren, fbPump, wCtr + onFault(execObj) |
+| **Параметры зоны** | pin (+ автоматически создаваемые cmd/val/set) |
+| **Команды** | ON, OFF, DRY, RESET (+ FREEZE/UNFREEZE/ENABLE/DISABLE ядра) |
+| **События** | Изменение состояния, завершение полива, ошибки |
+| **Интеграция** | MQTT топики для каждой зоны |
+
+---
+
+
+
+Из [item.h](../../lighthub/item.h):
+
+```cpp
+#define S_NOTFOUND  0
+#define S_CMD  1      // /cmd
+#define S_SET  2      // /set
+#define S_VAL  3      // /val
+#define S_DELAYED 4   // /del
+#define S_HSV  5      // /HSV
+#define S_RGB  6      // /RGB
+#define S_FAN  7      // /fan
+#define S_MODE 8      // /mode
+#define S_CTRL 9      // /ctrl
+#define S_HUE  10     // /hue
+#define S_SAT  11     // /sat
+#define S_TEMP 12     // /temp
+#define S_RAW 13      // /raw
+```
+
+---
+
+## Таблица совместимости MQTT суффиксов и типов
+
+| Тип | /cmd | /val | /set | /hue | /sat | /temp | /fan | /mode | /RGB |
+|-----|:----:|:----:|:----:|:----:|:----:|:-----:|:----:|:-----:|:----:|
+| 0 (DMX) | ✓ | ✓ | ✓ | - | - | - | - | - | - |
+| 1 (RGBW) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ |
+| 2 (RGB) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ |
+| 3 (PWM) | ✓ | ✓ | ✓ | - | - | - | - | - | - |
+| 4 (MBUSDIM) | ✓ | ✓ | ✓ | - | - | - | - | - | - |
+| 5 (THERMO) | ✓ | ✓ | ✓ | - | - | - | - | - | - |
+| 6 (RELAY) | ✓ | ✓ | - | - | - | - | - | - | - |
+| 7 (GROUP) | ✓ | ✓ | ✓ | - | - | - | - | - | - |
+| 10 (AC) | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓ | - |
+| 13 (PID) | ✓ | ✓ | ✓ | - | - | - | - | - | - |
+| 14 (MBUS) | ✓ | ✓ | ✓ | - | - | - | - | - | - |
+| 16 (RELAYX) | ✓ | - | ✓ | - | - | - | - | - | - |
+| 23 (SPRINKLR) | ✓ | ✓ | ✓ | - | - | - | - | - | - |
+| 17 (RGBWW) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ |
+| 18 (MULTIVENT) | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓ | - |
+| 20 (COUNTER) | ✓ | ✓ | ✓ | - | - | - | - | - | - |
+
+---
+
+## Константы и флаги
+
+### Флаги управления (CTRL Execution flags)
+
+```cpp
+#define CTRL_DISABLE_RECURSION 1
+#define CTRL_DISABLE_NON_GRP  2
+#define CTRL_SCHEDULED_CALL_RECURSION (CTRL_DISABLE_RECURSION | CTRL_DISABLE_NON_GRP)
+```
+
+### Флаги режима опроса
+
+```cpp
+#define POLLING_SLOW 1
+#define POLLING_FAST 2
+#define POLLING_INT  3
+#define POLLING_1S   4
+```
+
+### Индексы массива Item
+
+```cpp
+#define I_TYPE 0       // Type of item
+#define I_ARG  1       // Channel-type depended argument
+#define I_VAL  2       // Latest preset (int or array)
+#define I_CMD  3       // Latest CMD received
+#define I_EXT  4       // Channel-depended extension
+#define I_TIMESTAMP 5
+```
+
+---
+
+## Примеры JSON конфигурации
+
+```json
+{
+  "items": {
+    "relay1": [6, 23],
+    "dimmer1": [0, 1],
+    "rgb_light": [1, 10],
+    "pwm1": [3, 9],
+    "thermo": [5, 24, 33],
+    "group_lights": [7, ["relay1", "dimmer1", "rgb_light"]],
+    "ac_main": [10, 1],
+    "counter_energy": [20, [0.02, 1.2]],
+    "multivent": [18, {"bedroom": {"set": 22}}]
+  }
+}
+```
+
+---
+
+---
+
+## Доступность типов по целям сборки
+
+| Тип | Цели сборки (build-flags) |
+|-----|---------------------------|
+| SPRINKLER (23) | due, esp32-wifi, esp32c3-wifi, lighthub21, nrf52840 |
+| MERCURY (22) | due, lighthub21, stm32 |
+| ELEVATOR (19) | только custom-build mega2560-optiboot (ELEVATOR_ENABLE) |
+| HUMIDIFIER (21) | только custom-build lighthub21 (HUMIDIFIER_ENABLE) |
+| UARTBRIDGE (15) | закомментирован во всех стандартных build-flags (UARTBRIDGE_ENABLE) |
+
+---
+
+**Версия**: 2.0  
+**Дата**: 2025-01-24  
+**Источник**: [item.h](../../lighthub/item.h) (строки 48-72)
@@ -0,0 +1,896 @@
+# Исчерпывающее руководство по настройке системы полива в Home Assistant
+
+Это руководство шаг за шагом проведёт вас через установку и настройку многоканальной системы полива на базе [lighthub](https://github.com/anklimov/lighthub), интегрированной с Home Assistant через MQTT. В результате вы получите красивую и функциональную панель управления, которая включает:
+
+- визуализацию уровня воды в баке (пусто / наполовину / полный),
+- индикацию работы водопровода, дренажного и основного насосов,
+- управление тремя зонами полива с заданием времени и прогресс-баром,
+- интерактивную корректировку выполненного времени через проценты,
+- историю ключевых параметров по клику на иконки.
+
+---
+
+## 1. Предварительные требования
+
+- Установленный и настроенный [Home Assistant](https://www.home-assistant.io/) (любая версия, поддерживающая Lovelace).
+- Настроенный MQTT-брокер (например, Mosquitto) и интеграция MQTT в Home Assistant.
+- [HACS](https://hacs.xyz/) (Home Assistant Community Store) – для установки кастомных карт.
+
+> **Примечание:** Конфигурация MQTT‑датчиков и устройств уже готова и будет приведена ниже. Предполагается, что ваш контроллер lighthub уже отправляет данные в соответствующие топики.
+
+---
+
+## 2. Установка кастомных карт через HACS
+
+Для корректной работы панели необходимо установить следующие карты. Все они доступны в HACS.
+
+1. Откройте **HACS** → **Frontend** → **Explore & Download Repositories**.
+2. Поочерёдно найдите и установите каждую из перечисленных ниже карт.
+3. После установки **обновите страницу** браузера (или перезагрузите интерфейс Home Assistant).
+
+### Список обязательных карт
+
+| Название                     | Репозиторий (для ручного добавления, если не находится) | Назначение |
+|------------------------------|----------------------------------------------------------|------------|
+| **Vertical Stack In Card**   | `ofekashery/vertical-stack-in-card`                      | Объединение нескольких карточек в одну с общим фоном |
+| **Button Card**              | `custom-cards/button-card`                               | Гибкая карточка с динамическими иконками, анимацией и состояниями |
+| **Bar Card**                 | `spacerokk/bar-card` (активный форк)                     | Прогресс-бар для отображения выполнения полива |
+| **Mushroom Cards**           | `piitaya/lovelace-mushroom`                              | Компактные и стильные карточки для датчиков и переключателей |
+| **Slider Entity Row**        | `thomasloven/lovelace-slider-entity-row`                | Ползунок для настройки времени в more‑info окнах (не обязателен, но используется в стандартном окне `number`) |
+| **Card Mod**                 | `thomasloven/lovelace-card-mod`                         | Позволяет добавлять произвольные CSS‑стили к карточкам |
+
+> **Важно:** Если какая‑то карта не отображается в HACS, добавьте её вручную через **HACS → ⋮ → Пользовательские репозитории**. В поле URL вставьте ссылку на GitHub‑репозиторий, категорию выберите **Lovelace**.
+
+---
+
+## 3. Настройка MQTT‑сущностей
+
+Вся логика обмена данными с контроллером lighthub заложена в MQTT‑конфигурации. Скопируйте приведённый ниже блок в файл `configuration.yaml` (или в отдельный файл, подключённый через `mqtt: !include mqtt.yaml`).
+
+```yaml
+# Пример размещения в configuration.yaml
+mqtt:
+  switch:
+    - name: "Полив"
+      state_topic:  "edem/s_out/sprinkler/cmd"
+      command_topic: "edem/air/sprinkler/cmd"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив север"
+      state_topic:  "edem/s_out/sprinkler/nord/cmd"
+      command_topic: "edem/air/sprinkler/nord/cmd"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив юг"
+      state_topic:  "edem/s_out/sprinkler/south/cmd"
+      command_topic: "edem/air/sprinkler/south/cmd"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив капельный"
+      state_topic:  "edem/s_out/sprinkler/trees/cmd"
+      command_topic: "edem/air/sprinkler/trees/cmd"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив розетки"
+      state_topic:  "edem/s_out/sprinkler/outlets/cmd"
+      command_topic: "edem/air/sprinkler/outlets/cmd"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+  button:
+    - name: "Полив сброс"
+      command_topic: "edem/air/sprinkler/cmd"
+      payload_press: "RESET"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив блокировка"
+      command_topic: "edem/air/sprinkler/cmd"
+      payload_press: "FREEZE"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив разблокировка"
+      command_topic: "edem/air/sprinkler/cmd"
+      payload_press: "UNFREEZE"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив разрешить"
+      command_topic: "edem/air/sprinkler/cmd"
+      payload_press: "ENABLE"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив запретить"
+      command_topic: "edem/air/sprinkler/cmd"
+      payload_press: "DISABLE"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив осушение бака"
+      command_topic: "edem/air/sprinkler/cmd"
+      payload_press: "DRY"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+  number:
+    - name: "Полив юг"
+      state_topic:  "edem/s_out/sprinkler/south/set"
+      command_topic: "edem/air/sprinkler/south/set"
+      min: 0
+      max: 6000
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив север"
+      state_topic:  "edem/s_out/sprinkler/nord/set"
+      command_topic: "edem/air/sprinkler/nord/set"
+      min: 0
+      max: 6000
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив капельный"
+      state_topic:  "edem/s_out/sprinkler/trees/set"
+      command_topic: "edem/air/sprinkler/trees/set"
+      min: 0
+      max: 6000
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив юг выполнено"
+      state_topic:  "edem/s_out/sprinkler/south/val"
+      command_topic: "edem/air/sprinkler/south/val"
+      min: 0
+      max: 60000
+      mode: slider
+      icon: "mdi:timer-sand"
+      unit_of_measurement: 'sec'
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив север выполнено"
+      state_topic:  "edem/s_out/sprinkler/nord/val"
+      command_topic: "edem/air/sprinkler/nord/val"
+      min: 0
+      max: 60000
+      mode: slider
+      icon: "mdi:timer-sand"
+      unit_of_measurement: 'sec'
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив капельный выполнено"
+      state_topic:  "edem/s_out/sprinkler/trees/val"
+      command_topic: "edem/air/sprinkler/trees/val"
+      min: 0
+      max: 60000
+      mode: slider
+      icon: "mdi:timer-sand"
+      unit_of_measurement: 'sec'
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+  sensor:
+    - name: "Полив бак Макс"
+      state_topic:  "edem/s_out/sprinkler/$wMax"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив бак Мin"
+      state_topic:  "edem/s_out/sprinkler/$wMin"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив водопровод"
+      state_topic:  "edem/s_out/sprinkler/$rVIN"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив дренаж вкл"
+      state_topic:  "edem/s_out/sprinkler/$rDren"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив дренаж качает"
+      state_topic:  "edem/s_out/sprinkler/$fbDren"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив насос вкл"
+      state_topic:  "edem/s_out/sprinkler/$rPump"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив насос качает"
+      state_topic:  "edem/s_out/sprinkler/$fbPump"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив состояние"
+      state_topic:  "edem/s_out/sprinkler/$state"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив ошибка"
+      state_topic:  "edem/s_out/sprinkler/$fault"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Поливаем юг"
+      state_topic:  "edem/s_out/sprinkler/south/$state"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Поливаем север"
+      state_topic:  "edem/s_out/sprinkler/nord/$state"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Поливаем капельно"
+      state_topic:  "edem/s_out/sprinkler/trees/$state"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив розетка статус"
+      state_topic:  "edem/s_out/sprinkler/outlets/$state"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+
+    - name: "Полив блокировки"
+      state_topic:  "edem/s_out/sprinkler/ctrl"
+      availability_topic: "edem/air/$state"
+      payload_available: "ready"
+      payload_not_available: "disconnected"
+```
+
+> **Пояснение:**  
+> - `switch` – переключатели для запуска/остановки зон и общий переключатель.  
+> - `button` – кнопки для сброса, блокировки, разрешения и осушения бака.  
+> - `number` – задание времени полива (уставки) и выполненное время (с возможностью ручной корректировки).  
+> - `sensor` – датчики состояния поплавков (`$wMax`, `$wMin`), водопровода, насосов, статуса полива, ошибок и т.д.  
+> - **Важно (switch «Полив»):** общий переключатель читает `.../sprinkler/cmd`; в режиме осушения (DRY) контроллер публикует в этот топик значение `DRY` (а не ON/OFF), поэтому тумблер HA может показать нестандартное значение.  
+> - **Важно (sensor «Полив состояние»):** датчик по `$state` принимает значения `OFF`, `DREN_ON`, `DREN_OPERATE`, `DREN_EMPTY`, `VIN`, `FULL`, `DRYING`, `FAULT_VIN`, `FAULT_DREN`, `UNKNOWN`; текущее состояние гарантированно публикуется при старте контроллера.
+
+После добавления конфигурации **перезагрузите YAML** (Настройки → Сервер → Перезагрузить конфигурацию YAML).
+
+---
+
+## 4. Настройка template‑сущностей
+
+Для работы панели необходимы два типа вычислимых объектов:
+
+- **Уровень бака в процентах** (на основе поплавков).  
+- **Прогресс полива в процентах** для каждой зоны (с возможностью двусторонней синхронизации: проценты ↔ секунды).
+
+Добавьте следующий блок в `configuration.yaml` (если у вас уже есть секция `template:`, объедините её с этим содержимым, сохранив правильные отступы):
+
+```yaml
+template:
+  # Сенсор уровня бака
+  - sensor:
+      - name: "Полив бак уровень"
+        state: >
+          {% if states('sensor.poliv_bak_maks') == 'ON' %}
+            100
+          {% elif states('sensor.poliv_bak_min') == 'ON' %}
+            50
+          {% else %}
+            0
+          {% endif %}
+
+  # Числовые шаблоны прогресса (проценты)
+  - number:
+      - name: "Полив юг прогресс"
+        state: >
+          {% set zadanie = states('number.poliv_iug') | float(0) %}
+          {% set vypolneno = states('number.poliv_iug_vypolneno') | float(0) %}
+          {{ ((vypolneno / zadanie * 100) | round(0)) if zadanie > 0 else 0 }}
+        set_value:
+          - service: number.set_value
+            target:
+              entity_id: number.poliv_iug_vypolneno
+            data:
+              value: >
+                {% set zadanie = states('number.poliv_iug') | float(0) %}
+                {{ ((value | float(0)) * zadanie / 100) | round(0) }}
+        min: 0
+        max: 100
+        step: 1
+        unit_of_measurement: "%"
+        icon: mdi:progress-clock
+
+      - name: "Полив север прогресс"
+        state: >
+          {% set zadanie = states('number.poliv_sever') | float(0) %}
+          {% set vypolneno = states('number.poliv_sever_vypolneno') | float(0) %}
+          {{ ((vypolneno / zadanie * 100) | round(0)) if zadanie > 0 else 0 }}
+        set_value:
+          - service: number.set_value
+            target:
+              entity_id: number.poliv_sever_vypolneno
+            data:
+              value: >
+                {% set zadanie = states('number.poliv_sever') | float(0) %}
+                {{ ((value | float(0)) * zadanie / 100) | round(0) }}
+        min: 0
+        max: 100
+        step: 1
+        unit_of_measurement: "%"
+        icon: mdi:progress-clock
+
+      - name: "Полив капельный прогресс"
+        state: >
+          {% set zadanie = states('number.poliv_kapelnyi') | float(0) %}
+          {% set vypolneno = states('number.poliv_kapelnyi_vypolneno') | float(0) %}
+          {{ ((vypolneno / zadanie * 100) | round(0)) if zadanie > 0 else 0 }}
+        set_value:
+          - service: number.set_value
+            target:
+              entity_id: number.poliv_kapelnyi_vypolneno
+            data:
+              value: >
+                {% set zadanie = states('number.poliv_kapelnyi') | float(0) %}
+                {{ ((value | float(0)) * zadanie / 100) | round(0) }}
+        min: 0
+        max: 100
+        step: 1
+        unit_of_measurement: "%"
+        icon: mdi:progress-clock
+```
+
+**Как это работает:**  
+- `state` динамически вычисляет процент выполнения на основе заданного времени (`number.poliv_...`) и выполненного (`number.poliv_..._vypolneno`).  
+- `set_value` при ручном изменении процента (через ползунок или ввод) пересчитывает его в секунды и отправляет команду в контроллер через `number.set_value` для выполненного времени. Таким образом, можно вручную скорректировать прогресс, и значение сразу уйдёт в MQTT.  
+- Бак определяется по поплавкам: если активен `$wMax` → 100%, если только `$wMin` → 50%, иначе 0%.
+
+Снова **перезагрузите YAML‑конфигурацию**.
+
+---
+
+## 5. Создание панели управления (Dashboard)
+
+### 5.1. Создание новой панели
+
+1. Перейдите в **Настройки** → **Панели** (Dashboards).
+2. Нажмите **Создать панель** (Add Dashboard).
+   - Название: `💧 Полив`
+   - Режим панели: **Панель (одна карточка)** – *Panel (1 card)*.
+3. Нажмите **Создать**.
+
+### 5.2. Переход в редактор YAML
+
+Сразу после создания панель откроется в графическом редакторе.  
+Нажмите на три точки **⋮** в правом верхнем углу и выберите **Редактор YAML**.
+
+### 5.3. Вставка финального YAML
+
+Удалите всё содержимое (обычно там `type: panel\npath: ""\ncards: []`) и вставьте следующий код:
+
+```yaml
+views:
+  - type: panel
+    path: ''
+    cards:
+      - type: custom:vertical-stack-in-card
+        title: 💧 Система полива
+        cards:
+          # ── Общее состояние ──
+          - type: horizontal-stack
+            cards:
+              - type: custom:mushroom-entity-card
+                entity: sensor.poliv_sostoianie
+                name: Статус
+                primary_info: state
+                icon: mdi:state-machine
+              - type: custom:mushroom-entity-card
+                entity: sensor.poliv_blokirovki
+                name: Режим
+                primary_info: state
+                icon: mdi:lock
+
+          # ── Бак ──
+          - type: custom:mushroom-template-card
+            primary: Бак воды
+            secondary: |
+              {% set lvl = states('sensor.poliv_bak_uroven') %}
+              {% if lvl == '100' %} Полный
+              {% elif lvl == '50' %} Наполовину
+              {% else %} Пустой {% endif %}
+            icon: mdi:battery
+            icon_color: |
+              {% set lvl = states('sensor.poliv_bak_uroven') %}
+              {% if lvl == '100' %} green
+              {% elif lvl == '50' %} orange
+              {% else %} grey {% endif %}
+            tap_action:
+              action: more-info
+              entity: sensor.poliv_bak_uroven
+            card_mod:
+              style: |
+                ha-card {
+                  --mush-icon-size: 24px;
+                  height: 60px;
+                }
+
+          - type: divider
+
+          # ── Водопровод ──
+          - type: custom:mushroom-template-card
+            primary: Водопровод
+            secondary: |
+              {% if states('sensor.poliv_vodoprovod') == 'ON' %} Вкл
+              {% else %} Выкл {% endif %}
+            icon: mdi:water-pump
+            icon_color: |
+              {% if states('sensor.poliv_vodoprovod') == 'ON' %} blue
+              {% else %} grey {% endif %}
+            tap_action:
+              action: more-info
+              entity: sensor.poliv_vodoprovod
+            card_mod:
+              style: |
+                ha-card {
+                  --mush-icon-size: 24px;
+                  height: 60px;
+                }
+
+          # ── Насосы ──
+          - type: horizontal-stack
+            cards:
+              - type: custom:mushroom-template-card
+                primary: Дренаж
+                secondary: |
+                  {% set pwr = states('sensor.poliv_drenazh_vkl') %}
+                  {% set pump = states('sensor.poliv_drenazh_kachaet') %}
+                  {% if pwr == 'ON' and pump == 'ON' %} Качает
+                  {% elif pwr == 'ON' %} Вкл
+                  {% else %} Выкл {% endif %}
+                icon: mdi:pump
+                icon_color: |
+                  {% set pwr = states('sensor.poliv_drenazh_vkl') %}
+                  {% set pump = states('sensor.poliv_drenazh_kachaet') %}
+                  {% if pwr == 'ON' and pump == 'ON' %} red
+                  {% elif pwr == 'ON' %} green
+                  {% else %} grey {% endif %}
+                tap_action:
+                  action: more-info
+                  entity: sensor.poliv_drenazh_kachaet
+                card_mod:
+                  style: |
+                    ha-card {
+                      --mush-icon-size: 24px;
+                      height: 65px;
+                    }
+
+              - type: custom:mushroom-template-card
+                primary: Помпа
+                secondary: |
+                  {% set pwr = states('sensor.poliv_nasos_vkl') %}
+                  {% set pump = states('sensor.poliv_nasos_kachaet') %}
+                  {% if pwr == 'ON' and pump == 'ON' %} Качает
+                  {% elif pwr == 'ON' %} Вкл
+                  {% else %} Выкл {% endif %}
+                icon: mdi:pump
+                icon_color: |
+                  {% set pwr = states('sensor.poliv_nasos_vkl') %}
+                  {% set pump = states('sensor.poliv_nasos_kachaet') %}
+                  {% if pwr == 'ON' and pump == 'ON' %} red
+                  {% elif pwr == 'ON' %} green
+                  {% else %} grey {% endif %}
+                tap_action:
+                  action: more-info
+                  entity: sensor.poliv_nasos_kachaet
+                card_mod:
+                  style: |
+                    ha-card {
+                      --mush-icon-size: 24px;
+                      height: 65px;
+                    }
+
+          - type: divider
+
+          # ── Управление циклом ──
+          - type: entities
+            title: Управление циклом
+            show_header_toggle: false
+            entities:
+              - entity: switch.poliv
+                name: Полив
+                icon: mdi:sprinkler
+              - entity: switch.poliv_rozetki
+                name: Водяная розетка
+                icon: mdi:pipe-valve
+              - entity: button.poliv_sbros
+                name: Запуск всех зон
+                icon: mdi:play
+              - entity: button.poliv_blokirovka
+                name: Заморозить
+                icon: mdi:snowflake
+              - entity: button.poliv_razblokirovka
+                name: Разморозить
+                icon: mdi:snowflake-melt
+              - entity: button.poliv_zapretit
+                name: Запретить полив
+                icon: mdi:cancel
+              - entity: button.poliv_razreshit
+                name: Разрешить полив
+                icon: mdi:check-circle
+              - entity: button.poliv_osushenie_baka
+                name: Осушение бака
+                icon: mdi:hair-dryer
+
+          - type: divider
+
+          # ── Северная зона ──
+          - type: custom:vertical-stack-in-card
+            title: 🌿 Северная зона
+            cards:
+              - type: horizontal-stack
+                cards:
+                  # Выключатель
+                  - type: custom:mushroom-entity-card
+                    entity: switch.poliv_sever
+                    show_name: false
+                    show_icon: false
+                    show_state: false
+                    layout: horizontal
+                  # Время
+                  - type: custom:mushroom-entity-card
+                    entity: number.poliv_sever
+                    name: Время
+                    icon: mdi:timer-edit
+                    layout: horizontal
+                    card_mod:
+                      style: |
+                        ha-card {
+                          --mush-icon-size: 24px;
+                          height: 48px;
+                          flex: 1 1 0;
+                        }
+              - type: conditional
+                conditions:
+                  - entity: number.poliv_sever
+                    state_not: '0'
+                card:
+                  type: custom:vertical-stack-in-card
+                  title: ''
+                  cards:
+                    - type: horizontal-stack
+                      cards:
+                        - type: custom:button-card
+                          entity: sensor.polivaem_sever
+                          show_name: false
+                          show_state: false
+                          icon: mdi:sprinkler
+                          tap_action:
+                            action: more-info
+                            entity: sensor.polivaem_sever
+                          state:
+                            - value: 'ON'
+                              color: green
+                              styles:
+                                icon:
+                                  - animation: pulse 1.5s infinite
+                            - value: 'OFF'
+                              color: grey
+                              styles:
+                                icon:
+                                  - animation: none
+                          styles:
+                            card:
+                              - height: 40px
+                              - width: 40px
+                            icon:
+                              - width: 24px
+                              - height: 24px
+                        - type: custom:mushroom-template-card
+                          primary: ''
+                          secondary: >
+                            Выполнено: {{ states('number.poliv_sever_vypolneno')
+                            }} / {{ states('number.poliv_sever') }} с
+                          icon: ''
+                          tap_action:
+                            action: more-info
+                            entity: number.poliv_sever_progress
+                          card_mod:
+                            style: |
+                              ha-card {
+                                height: 40px;
+                                margin-top: 0px;
+                              }
+                    - type: custom:bar-card
+                      entities:
+                        - entity: number.poliv_sever_progress
+                          name: Прогресс
+                          icon: mdi:progress-clock
+                          max: 100
+                          severity:
+                            - from: 0
+                              to: 25
+                              color: red
+                            - from: 26
+                              to: 75
+                              color: orange
+                            - from: 76
+                              to: 100
+                              color: green
+                          unit_of_measurement: '%'
+
+          - type: divider
+
+          # ── Южная зона ──
+          - type: custom:vertical-stack-in-card
+            title: 🌿 Южная зона
+            cards:
+              - type: horizontal-stack
+                cards:
+                  - type: custom:mushroom-entity-card
+                    entity: switch.poliv_iug
+                    show_name: false
+                    show_icon: false
+                    show_state: false
+                    layout: horizontal
+                  - type: custom:mushroom-entity-card
+                    entity: number.poliv_iug
+                    name: Время
+                    icon: mdi:timer-edit
+                    layout: horizontal
+                    card_mod:
+                      style: |
+                        ha-card {
+                          --mush-icon-size: 24px;
+                          height: 48px;
+                          flex: 1 1 0;
+                        }
+              - type: conditional
+                conditions:
+                  - entity: number.poliv_iug
+                    state_not: '0'
+                card:
+                  type: custom:vertical-stack-in-card
+                  title: ''
+                  cards:
+                    - type: horizontal-stack
+                      cards:
+                        - type: custom:button-card
+                          entity: sensor.polivaem_iug
+                          show_name: false
+                          show_state: false
+                          icon: mdi:sprinkler
+                          tap_action:
+                            action: more-info
+                            entity: sensor.polivaem_iug
+                          state:
+                            - value: 'ON'
+                              color: green
+                              styles:
+                                icon:
+                                  - animation: pulse 1.5s infinite
+                            - value: 'OFF'
+                              color: grey
+                              styles:
+                                icon:
+                                  - animation: none
+                          styles:
+                            card:
+                              - height: 40px
+                              - width: 40px
+                            icon:
+                              - width: 24px
+                              - height: 24px
+                        - type: custom:mushroom-template-card
+                          primary: ''
+                          secondary: >
+                            Выполнено: {{ states('number.poliv_iug_vypolneno')
+                            }} / {{ states('number.poliv_iug') }} с
+                          icon: ''
+                          tap_action:
+                            action: more-info
+                            entity: number.poliv_iug_progress
+                          card_mod:
+                            style: |
+                              ha-card {
+                                height: 40px;
+                                margin-top: 0px;
+                              }
+                    - type: custom:bar-card
+                      entities:
+                        - entity: number.poliv_iug_progress
+                          name: Прогресс
+                          icon: mdi:progress-clock
+                          max: 100
+                          severity:
+                            - from: 0
+                              to: 25
+                              color: red
+                            - from: 26
+                              to: 75
+                              color: orange
+                            - from: 76
+                              to: 100
+                              color: green
+                          unit_of_measurement: '%'
+
+          - type: divider
+
+          # ── Капельная зона ──
+          - type: custom:vertical-stack-in-card
+            title: 🌿 Капельная зона
+            cards:
+              - type: horizontal-stack
+                cards:
+                  - type: custom:mushroom-entity-card
+                    entity: switch.poliv_kapelnyi
+                    show_name: false
+                    show_icon: false
+                    show_state: false
+                    layout: horizontal
+                  - type: custom:mushroom-entity-card
+                    entity: number.poliv_kapelnyi
+                    name: Время
+                    icon: mdi:timer-edit
+                    layout: horizontal
+                    card_mod:
+                      style: |
+                        ha-card {
+                          --mush-icon-size: 24px;
+                          height: 48px;
+                          flex: 1 1 0;
+                        }
+              - type: conditional
+                conditions:
+                  - entity: number.poliv_kapelnyi
+                    state_not: '0'
+                card:
+                  type: custom:vertical-stack-in-card
+                  title: ''
+                  cards:
+                    - type: horizontal-stack
+                      cards:
+                        - type: custom:button-card
+                          entity: sensor.polivaem_kapelno
+                          show_name: false
+                          show_state: false
+                          icon: mdi:watering-can
+                          tap_action:
+                            action: more-info
+                            entity: sensor.polivaem_kapelno
+                          state:
+                            - value: 'ON'
+                              color: green
+                              styles:
+                                icon:
+                                  - animation: pulse 1.5s infinite
+                            - value: 'OFF'
+                              color: grey
+                              styles:
+                                icon:
+                                  - animation: none
+                          styles:
+                            card:
+                              - height: 40px
+                              - width: 40px
+                            icon:
+                              - width: 24px
+                              - height: 24px
+                        - type: custom:mushroom-template-card
+                          primary: ''
+                          secondary: >
+                            Выполнено: {{
+                            states('number.poliv_kapelnyi_vypolneno') }} / {{
+                            states('number.poliv_kapelnyi') }} с
+                          icon: ''
+                          tap_action:
+                            action: more-info
+                            entity: number.poliv_kapelnyi_progress
+                          card_mod:
+                            style: |
+                              ha-card {
+                                height: 40px;
+                                margin-top: 0px;
+                              }
+                    - type: custom:bar-card
+                      entities:
+                        - entity: number.poliv_kapelnyi_progress
+                          name: Прогресс
+                          icon: mdi:progress-clock
+                          max: 100
+                          severity:
+                            - from: 0
+                              to: 25
+                              color: red
+                            - from: 26
+                              to: 75
+                              color: orange
+                            - from: 76
+                              to: 100
+                              color: green
+                          unit_of_measurement: '%'
+```
+
+Нажмите **Сохранить** – панель готова к использованию.
+
+---
+
+## 6. Как пользоваться панелью
+
+![sprinkler_1.jpeg](../reference/images/sprinkler_1.jpeg)
+![sprinkler_2.jpeg](../reference/images/sprinkler_2.jpeg)
+- **Общее состояние:** Отображает статус системы и режим (заморозка/разрешено/запрещено). Ошибка не показывается, но иконка станет красной при неисправности.
+- **Бак:** Иконка батарейки меняет цвет и текст в зависимости от уровня воды (пусто/наполовину/полный). Нажатие открывает историю уровня.
+- **Водопровод и насосы:** Показывают текущий статус (Выкл/Вкл/Качает) с цветовой индикацией. Клик – история соответствующего датчика.
+- **Управление циклом:** Общий переключатель «Полив», кнопки запуска всех зон, заморозки, запрета, осушения бака. Работают как обычные MQTT‑команды.
+- **Зоны полива:**
+  1. **Включение зоны** – крайний левый переключатель (тумблер).
+  2. **Время** – поле с кнопками +/- для задания уставки полива в секундах.
+  3. Если время > 0, под строкой появятся:
+     - Индикатор полива (спринклер/лейка) – цветной, с анимацией пульсации при работе. Нажатие открывает историю активности зоны.
+     - Строка «Выполнено: X / Y с» – абсолютное значение. Нажатие открывает окно редактирования прогресса в процентах.
+     - Прогресс-бар – визуальное отображение процента выполнения (красный → оранжевый → зелёный).
+- **Корректировка прогресса:** Кликните на строку «Выполнено…» → появится слайдер 0-100%. Измените процент, и соответствующее количество секунд сразу отправится в контроллер (автоматический пересчёт).
+
+---
+
+## 7. Возможные проблемы и их решение
+
+| Проблема | Вероятная причина | Решение |
+|----------|-------------------|---------|
+| Не отображаются прогресс‑бары | Отсутствует `bar-card` или не созданы `template number` | Проверьте HACS, установите карту. Убедитесь, что template‑числа добавлены и конфигурация перезагружена. |
+| Иконка полива не меняет цвет | Неправильное имя датчика `sensor.polivaem_...` | Проверьте точное название в разделе **Состояния**. Поправьте в YAML панели. |
+| Тумблер включения зоны не видим | Не установлена карта `mushroom-entity-card` или перекрыт стилями | Убедитесь, что `mushroom-cards` установлены. В нашем финальном YAML тумблер видим всегда. |
+| Ошибка «expected float» при движении слайдера прогресса | Используется `slider-entity-row` в активном режиме, а динамический `max` задан некорректно | В нашем решении прогресс‑бар только визуальный (`bar-card`), ручная корректировка – через `template number` с собственным `set_value`. Ошибки быть не должно. |
+| Бак всегда показывает «Пустой» | Неправильно работают поплавки или датчики `$wMax`/`$wMin` не обновляются | Проверьте в MQTT‑топиках фактические значения. Убедитесь, что поплавки подключены и отправляют ON/OFF. |
+
+---
+
+## 8. Дополнительная информация
+
+- Все команды управления (вкл/выкл зон, сброс, заморозка и т.д.) отправляются напрямую в контроллер lighthub через MQTT.
+- Система использует `availability_topic` для отслеживания связи с контроллером. При пропадании сигнала все элементы станут недоступны (серые).
+- При желании можно расширить панель новыми зонами, копируя структуру существующих и добавляя соответствующие `number`, `switch` и `sensor` в MQTT‑конфигурацию и `template`.
+
+---
+
+## Приложение: полный финальный YAML панели
+
+Код уже приведён в разделе 5.3. Используйте его как окончательную версию.
+
+---
+
+Теперь ваша система полива полностью интегрирована в Home Assistant. Вы можете управлять поливом с мобильного телефона, отслеживать историю и быть уверенными, что всё под контролем!
@@ -0,0 +1,375 @@
+# LightHub: Модуль многоканальной системы полива (out_sprinkler)
+Данный модуль реализует многозональную систему полива
+
+## Система состоит из следующих компонент:
+
+* Накопительный водяной бак. Снабжен двумя поплавками. Максимум воды и минимум воды. Заведены на входы wMax и wMin 
+* Насос полива высокого давления. Запитан из бака. Включается реле, подключенным к выходу rPump. Датчик тока для контроля того, что насос включен, заведен на вход fbPump
+* Набор клапанов зон полива. Подключены через оптореле к выходам, заданным в параметре pin соответствующей зоны полива.
+* Клапан налива из водопровода. Подключен через оптореле к выходу vIn
+* Насос дренажного колодца. Приоритетный источник для наполнения бака полива. Когда система полива находится в ждущем или активном режиме, бак пытается максимально наполнится из дренажного колодца. Насос дренажа имеет поплавковый выключатель, отключающий насос при осушении дренажного колодца. Насос включается реле, которое подключено к выходу rDren. Для контроля того, что насос включен и момента осушения колодца, используется датчик тока, который подключен в входу fbDren
+* Опциональный водосчетчик. Контакты подключены к входу wCtr
+
+## Система налива воды реализована при помощи конечного автомата со следующими состояниями:
+
+* SP\_UNKNOWN
+* SP\_OFF
+* SP\_DREN\_ON - дренажный насос включен
+* SP\_DREN\_OPERATE - дренажный насос работает
+* SP\_DREN\_EMPTY - дренажный насос выключился встроенным поплавком - колодец пуст
+* SP\_VIN - включено наполнение из водопровода
+* SP\_FULL - бак наполнен
+* SP\_DRYING - режим осушения системы: налив перекрыт, работает насос полива для слива бака (SP\_DRYING=7, out_sprinkler.h:34)
+
+Строковые значения, публикуемые в топик `$state` (out_sprinkler.cpp:263-308): `OFF`, `DREN_ON`, `DREN_OPERATE`, `DREN_EMPTY`, `VIN`, `FULL`, `DRYING`, `FAULT_VIN`, `FAULT_DREN`, `UNKNOWN`.
+
+граф переходов конечного автомата системы налива воды
+
+Состояние SP\_* | Условие перехода | перейти в состояние | выполнить при переходе |
+|------|--------|-------|---------|
+INIT			|  		true				| OFF                  | выключить клапана и насосы |
+OFF          | vMax && !FREEZE             | FULL                 | выключить vIN, rDren|
+OFF          | ! vMax && !FREEZE    | DREN\_ON|включить rDren|
+DREN\_ON|fbDren (насос дренажа реально работает)|DREN\_OPERATE|
+DREN\_ON|таймаут 10 сек|DREN\_EMPTY| насос так и не заработал - видимо в колодце пусто
+DREN\_EMPTY|включен цикл полива и бак не полон|VIN|включить клапан vIN для набора бака из водопровода|
+DREN\_OPERATE| ! fbDren (насос дренажа более не работает)|DREN\_EMPTY||
+VIN|fbDren|DREN\_OPERATE|вылючить клапан vIN для набора бака из водопровода - заработал дренажный насос|
+VIN, DREN\_OPERATE|vMax|FULL                 | выключить vIN, rDren  - бак полон|
+VIN|таймаут 1200 сек	| FAULT\_VIN| выключить vIN - бак так и не наполнился|
+DREN\_OPERATE|fbPump (качает основной насос)|DREN\_OPERATE|сброс таймера (@timer = now) — не считать ошибку, пока качает основной насос (L562)|
+DREN\_OPERATE|таймаут 4000 сек	|FAULT_DREN|выключить rDren  - не смотря на продолжительную работу насоса бак не наполнен|
+FULL|! wMax|DREN\_ON|дренаж перезапускается при опустошении бака (L609-617)|
+FAULT\_VIN, FAULT\_DREN|wMax|FULL|сброс ошибки при наполнении бака (L619-635)|
+
+
+
+## Конфигурирование:
+
+
+```
+
+"items":
+{
+         "sprinkler":[23,
+   {
+   "":{
+			"vIn":3,
+			"wMax":44,
+			"wMin":46,
+			"rDren":23,
+			"fbDren":63,
+			"rPump":24,	
+			"fbPump":62,
+			"wCtr":49	
+   		},
+   "nord":{"pin":6,"set":60,"cmd":1},
+   "south":{"pin":7,"set":100,"cmd":1},
+   "trees":{"pin":10,"set":60,"cmd":2},
+   "outlets:{} 
+
+ 	}]
+}
+
+```
+
+В корневом (`""`) объекте, помимо выходов/входов, можно задать EXEC-объект `onFault` — при срабатывании ошибки автомата налива вместо публикации в `$fault` исполняется он с кодом ошибки аргументом (L260-262, L311-314).
+
+## Алгоритм работы
+в настройки зон полива задаем интенсивность для каждой зоны.
+
+Это можно сделать как в конфиге так динамически, (стандартными механизмами управления по MQTT, HTTP, CAN)
+
+Рассмотрим на примере MQTT:
+
+**топик** ```root/name/sprinkler/garden/set -> 60```
+
+Задаем обьем полива 60 отсчетов счетчика воды (если счетчик не сконфигурирован - 60 секунд)
+
+Контроллер должен передать это значение в выходной топик ```root/name/s_out/sprinkrer/garden/set``` и оно будет восстановлено при перезагрузке контроллера
+
+
+отработанный обьем воды или время будет сохраняться в параметре "val" каждой зоны (параметр будет автоматически увеличиваться при работе зоны, передаваться в соответствующий зоне топик для мониторинга и восстановления в случае перезагрузки контроллера)
+
+**Пример топика:** ```root/s_out/sprinkler/garden/val```
+
+Когда данный параметр достигнет значения (или времени), заданного в параметре "set" контроллер завершит полив данной зоны и перейдет к следующей.
+
+Важно: если set=0 (по умолчанию) то время работы зоны не лимитируется. Если такая зона включена - система полива не будет отключаться после окончания полива прочих зон и насос не будет обесточиваться. Это удобно, если в системе полива есть водяная розетка для подключения поливочного шланга, которая всегда должна находиться под давлением. Такую зону конфигурируйте последней в списке.
+
+Для сброса счетчиков можно использовать как непосредственную установку значения параметра "val" для каждой зоны так и команду RESET, отправленную в нужную зону или в объект sprinkler через суффикс /cmd. 
+
+**Пример:** ```root/name/sprinkler/cmd -> RESET```
+
+В последнем случае, контроллер итерационно сбросит счетчики в значение 0 для каждой зоны полива.
+Это инициирует старт программы полива, если система находится в состоянии ON
+
+Команда RESET не отработает если обьект полива находится в состоянии DISABLE или FREEZE
+
+Также, в этих режимах, в принципе,  не отработает запуск полива какой-либо зоны (команды set/RESET), если для нее задано время/обьем полива.
+
+Если обьем полива не задан (set==0) - это например водяная розетка для мытья машины, то такая зона запустится даже в режиме DISABLE 
+
+Если в процессе полива придет команда DISABLE (начался дождь) - полив прекратится, программа полива возобновится после ENABLE 
+
+
+
+
+
+
+
+## Управление
+
+### Включение/выключение  полива конкретной зоны:
+
+**Включить** ```root/name/sprinkler/garden/cmd -> ON```
+
+**Выключить** ```root/name/sprinkler/garden/cmd -> OFF```
+
+
+
+### Включение/выключение  цикла полива:
+
+**Включить** ```root/name/sprinkler/cmd -> ON```
+Система начнет или продолжит цикл полива, переходя от зоны к зоне по мере завершения работы с каждой предыдущей зоной. После завершения работы со всеми зонами, sprinkler НЕ перейдет в состояние OFF автоматически, но полив прекратится для тех зон, где показатель val достиг параметра set
+
+Если не будет ни одной активной зоны - насос обесточится.
+
+Перед включением полива, система убедится что бак готов: полив стартует при `state==FULL || wMax || wMin || fbPump` (L638) — то есть и при минимальном уровне / работающей помпе, иначе система до-наполнит бак до максимума из водопровода.
+
+
+
+**Выключить** ```root/name/sprinkler/cmd -> OFF```
+Система немедленно остановит текущий цикл полива (закроет клапаны зон, выключит насос полива)
+
+
+Аналогично, будут работать команды XON и XOFF, с одним исключением, что команда XON может быть запрещена и игнорироваться если активирован режим DISABLE. Это базовая функция контроллера и не относится к функционалу данного модуля. Но может быть использована, например, для запрета полива на определенное время после выпадения осадков
+
+**Пример** 
+
+```
+root/name/sprinkler/ctrl -> DISABLE
+root/name/sprinkler/cmd -> XON  //Будет проигнорировано
+
+root/name/sprinkler/ctrl -> ENABLE
+root/name/sprinkler/cmd -> XON  //А вот теперь сработает
+
+```
+
+Даже в выключенном состоянии (OFF) , система полива работает в дежурном режиме, поддерживая максимальный уровень воды в баке за счет немедленной перекачки из дренажного колодца
+
+При попытке включения системы после завершения дневного задания по поливу всех зон (параметр val для всех зон достиг параметра set) авто-перехода в OFF не происходит: item остаётся в состоянии ON и просто простаивает, не запуская активного полива (автоматическое выключение закомментировано, L712-722) — что согласуется с описанием выше: команда ON не переводит систему в OFF автоматически.
+
+
+ 
+### Полная блокировка системы полива (в зимнее время)
+Ддя перевода канала полива в полностью заблокированное состояние и обратно  импользуется системная команда FREEZE/UNFREEZE соответственно
+
+В режиме FREEZE полностью заблокирована обработка всех команд, кроме UNFREEZE, заблокирован автомат пополнения бака из дренажного насоса и выключены насосы и все клапана.
+
+Если одновременно выставлены флаги FREEZE и DISABLE, то в /ctrl публикуется FREEZE — приоритет над DISABLE (item.cpp:2174-2176).
+
+Рекомендуется задать флаг FREEZE в конфигурации канала (см документ ...) , чтобы избежать разблокировки при утере значений топика /clrl и перезагрузки системы
+
+Также, на вход /val обЪекта sprinkler можно подать значение уличной  температуры. И если значения будут ниже нуля, система автоматически перейдет в режим FREEZE	
+
+**Пример** 
+
+```
+root/name/sprinkler/ctrl -> FREEZE
+root/name/sprinkrer/cmd -> ON  //Будет проигнорировано
+
+root/name/sprinkler/ctrl -> UNFREEZE
+root/name/sprinkrer/cmd -> ON  //А вот теперь сработает
+
+root/name/sprinkler/val -> -1 //система перейдет в режим FREEZE
+
+
+```
+
+Так как команда FREEZE блокирует запуск каких либо насосов и открытие клапанов, это делает невозможным слив системы в процессе подготовки к зиме
+
+Когда требуется слить систему, необходимо отключить дренажный насос, перекрыть водопроводный кран
+
+Данный режим реализован при помощи команды DRY
+
+Дополнительно к перекрытию поступления воды в бак (заблокирован автомат пополнения бака из дренажного насоса и водопровода) данная команда включает помпу.
+
+- DRY переопределяет ON: если система находится в режиме `@state==SP_DRYING` и приходит команда ON, она исполняется как CMD_DRY, а не ON (out_sprinkler.cpp:837-841).
+- Режим DRY персистентен: `@state=SP_DRYING` хранится в конфиге и переживает перезагрузку контроллера; реле восстанавливаются из `@lastVals`, после рестарта в топик публикуется `DRYING`.
+
+Далее, требуется слить бак включением выбранных зон полива или через водяные розетки. 
+Только после осушения бака (насос выключится) - систему необходимо перевести в режим FREEZE
+Перевод в этот редим сбрасывает режим DRY (а также, состояния ошибки автомата наполнения бака)
+
+ 
+### Передача статусных значений 
+
+При старте (первый Poll) контроллер принудительно публикует все ключевые статусы: `$wMax`/`$wMin`/`$fbDren`/`$fbPump`/`$rPump`/`$rDren`/`$rVIN` + `$state`/`$fault` (L474-487). Повторно `$state`/`$fault` публикуются при командах ON/OFF (L842, L848).
+
+**Ошибки (onFault / $fault):** при каждом переходе состояния публикуется код ошибки в топик `$fault`: 0 — без ошибки, 1 — FAULT_VIN, 2 — FAULT_DREN (L311-315). Вместо публикации в `$fault` можно задать EXEC-объект `onFault` в корневом (`""`) объекте — в этом случае при срабатывании ошибки исполняется он с кодом ошибки аргументом (L260-262, L311-314).
+
+**Примеры выдачи в топики:** 
+
+```
+root/s_out/sprinkler/$fbPump - ON/OFF признак того, что включен основной насос (от датчика тока)
+root/s_out/sprinkler/$fbDren - ON/OFF признак того, что включен дренажный насос (от датчика тока)
+root/s_out/sprinkler/$state - состояние конечного автомата Системы налива воды
+root/s_out/sprinkler/$fault - код ошибки: 0 / 1=FAULT_VIN / 2=FAULT_DREN
+root/s_out/sprinkler/$wMax - ON/OFF достигнут максимум воды в баке (от поплавкового датчика)
+root/s_out/sprinkler/$wMin - ON/OFF достигнут минимум воды в баке (от поплавкового датчика)
+root/s_out/sprinkler/$rDren - ON/OFF включено реле дренажного насоса
+root/s_out/sprinkler/$rPump - ON/OFF включено реле основного насоса
+root/s_out/sprinkler/set - значение счетчика воды (восстанавливается при перезагрузке из данного топика)
+root/s_out/sprinkler/$rVIN - ON/OFF - признак открытия клапана налива бака из водопровода
+
+root/s_out/sprinkler/garden/set - требуемый обьем (или время) полива зоны
+root/s_out/sprinkler/garden/cmd - ON или OFF - признак включения полива зоны 
+root/s_out/sprinkler/garden/$state - ON или OFF - признак того что зона поливается в настоящее время
+root/s_out/sprinkler/garden/val - текущее время или обьем полива данной зоны
+
+```
+
+### Пример конфигурации Home Assistant
+```
+sensor:
+  - name: "Полив бак Макс"
+    state_topic:  "root/s_out/sprinkler/$wMax"
+    
+  - name: "Полив бак Мin"
+    state_topic:  "root/s_out/sprinkler/$wMin"    
+    
+  - name: "Полив водопровод"
+    state_topic:  "root/s_out/sprinkler/$rVIN"    
+    
+  - name: "Полив дренаж вкл"
+    state_topic:  "root/s_out/sprinkler/$rDren"    
+
+  - name: "Полив дренаж качает"
+    state_topic:  "root/s_out/sprinkler/$fbDren"    
+    
+  - name: "Полив насос вкл"
+    state_topic:  "root/s_out/sprinkler/$rPump"    
+
+  - name: "Полив насос качает"
+    state_topic:  "root/s_out/sprinkler/$fbPump"       
+    
+  - name: "Полив состояние"
+    state_topic:  "root/s_out/sprinkler/$state"  
+    
+  - name: "Полив ошибка"
+    state_topic:  "root/s_out/sprinkler/$fault"
+    
+  - name: "Полив юг выполнено"
+    state_topic:  "root/s_out/sprinkler/south/val"   
+
+  - name: "Полив север выполнено"
+    state_topic:  "root/s_out/sprinkler/nord/val"   
+
+  - name: "Полив капельный выполнено"
+    state_topic:  "edem/s_out/sprinkler/trees/val"   
+   
+  - name: "Поливаем юг"
+    state_topic:  "root/s_out/sprinkler/south/$state"   
+
+  - name: "Поливаем север"
+    state_topic:  "root/s_out/sprinkler/nord/$state"   
+
+  - name: "Поливаем капельно"
+    state_topic:  "root/s_out/sprinkler/trees/$state"   
+   
+  - name: "Полив розетка статус"
+    state_topic:  "root/s_out/sprinkler/outlets/$state"   
+   
+  - name: "Полив блокировки"
+    state_topic:  "root/s_out/sprinkler/ctrl"   
+    
+switch:
+
+  - name: "Полив"
+    state_topic:  "root/s_out/sprinkler/cmd"
+    command_topic: "root/air/sprinkler/cmd"
+    availability_topic: "root/air/$state"
+    payload_available: "ready"
+    payload_not_available: "disconnected" 
+
+  - name: "Полив север"
+    state_topic:  "root/s_out/sprinkler/nord/cmd"
+    command_topic: "root/air/sprinkler/nord/cmd"
+    availability_topic: "root/air/$state"
+    payload_available: "ready"
+    payload_not_available: "disconnected" 
+
+  - name: "Полив юг"
+    state_topic:  "root/s_out/sprinkler/south/cmd"
+    command_topic: "root/air/sprinkler/south/cmd"
+    availability_topic: "root/air/$state"
+    payload_available: "ready"
+    payload_not_available: "disconnected" 
+
+  - name: "Полив капельный"
+    state_topic:  "root/s_out/sprinkler/trees/cmd"
+    command_topic: "root/air/sprinkler/trees/cmd"
+    availability_topic: "root/air/$state"
+    payload_available: "ready"
+    payload_not_available: "disconnected" 
+
+  - name: "Полив розетки"
+    state_topic:  "root/s_out/sprinkler/outlets/cmd"
+    command_topic: "root/air/sprinkler/outlets/cmd"
+    availability_topic: "root/air/$state"
+    payload_available: "ready"
+    payload_not_available: "disconnected" 
+    
+button:
+ - name: "Полив сброс"
+   command_topic: "root/air/sprinkler/cmd"
+   payload_press: "RESET"
+   
+ - name: "Полив блокировка"
+   command_topic: "root/air/sprinkler/cmd"
+   payload_press: "FREEZE"
+
+ - name: "Полив разблокировка"
+   command_topic: "root/air/sprinkler/cmd"
+   payload_press: "UNFREEZE"   
+   
+ - name: "Полив разрешить"
+   command_topic: "root/air/sprinkler/cmd"
+   payload_press: "ENABLE"
+
+ - name: "Полив запретить"
+   command_topic: "root/air/sprinkler/cmd"
+   payload_press: "DISABLE"  
+
+ - name: "Полив осушение бака"
+   command_topic: "root/air/sprinkler/cmd"
+   payload_press: "DRY"
+#Такую проверку можно добавить везде, при ее наличии обьекты станут недоступными если контроллер оффлайн   
+   availability_topic: "root/air/$state"
+   payload_available: "ready"
+   payload_not_available: "disconnected"       
+
+number:
+
+ - name: "Полив юг"
+   state_topic:  "root/s_out/sprinkler/south/set"   
+   command_topic: "root/air/sprinkler/south/set"   
+   min: 0
+   max: 6000
+   
+ - name: "Полив север"
+   state_topic:  "root/s_out/sprinkler/nord/set"   
+   command_topic: "root/air/sprinkler/nord/set"   
+   min: 0
+   max: 6000   
+   
+ - name: "Полив капельный"
+   state_topic:  "root/s_out/sprinkler/trees/set"   
+   command_topic: "root/air/sprinkler/trees/set"   
+   min: 0
+   max: 6000
+   
+          
+
+```
@@ -0,0 +1,745 @@
+# LightHub: Модуль многоканального кондиционера и вентиляции (out_Multivent)
+
+> Документ описывает назначение, архитектуру и конфигурирование модуля управления многозональными системами кондиционирования и вентиляции LightHub.
+> Предназначен для инженеров HVAC-систем, интеграторов и разработчиков.
+
+---
+
+## 1. Назначение модуля
+
+### 1.1 Область применения
+
+Модуль `out_Multivent` предназначен для управления системами кондиционирования и вентиляции с **центральной установкой** и **множеством независимых зон/комнат**.
+
+### 1.2 Типовые сценарии
+
+#### Сценарий 1: Многозональный кондиционер
+- Центральная сплит-система или компактная установка (1 компрессор, 1 вентилятор)
+- Несколько помещений с электромоторными задвижками (воздушными затворами)
+- Каждое помещение требует своего микроклимата
+
+#### Сценарий 2: Многозональная приточная вентиляция
+- Центральная приточная установка с одним вентилятором
+- Несколько независимых воздуховодов с регулируемыми задвижками
+- Распределение воздушного потока в зависимости от потребностей зон
+
+#### Сценарий 3: Комбинированная система (климат + вентиляция)
+- Центральный кондиционер + приточная вентиляция
+- Управление как охлаждением/нагревом, так и циркуляцией воздуха
+
+### 1.3 Ключевые возможности
+
+✅ **Балансировка воздушного потока** — автоматическое распределение производительности между зонами
+
+✅ **PID-регулирование температуры** — независимая стабилизация для каждой зоны
+
+✅ **Интеллектуальное переключение режимов** — автоматическое определение HEAT/COOL по текущей температуре
+
+✅ **Агрегация команд** — управление центральной установкой на основе суммарного спроса от зон
+
+✅ **Каскадное управление** — возможность передачи команд на внешние системы (например, отображение режимов на стеновых панеляж управления)
+
+✅ **Отслеживание прямого управления основным кондиционером** — система понимает, явились ли изменения режима работы основного кондиционера причиной ее управляющих воздействий. И если обнаруживает, что режим поменялся вручную, при помощи пульта управления центральной установкой, принимает это изменение как инструкцию к действию. А именно: при выключении основного блока с пульта - все виртуальные зоны выключаются. (чтобы предотвратить немедленное автоматическое обратное включение) При обратном включении - их состояние восстанавливается. Также, можно определить какую либо из виртуальных зон для управления с пульта главного кондиционера.
+
+❌ **Ограничения**: ?
+
+---
+
+## 2. Архитектура и принцип работы
+
+### 2.1 Компоненты системы
+
+```
+┌────────────────────────────────────────────┐
+│      Центральная установка (AC)            │
+│  (компрессор, вентилятор, датчик temp)     │
+│                                            │
+│  Управляется через S_MODE и S_FAN          │
+└──────────────┬─────────────────────────────┘
+               │
+         ┌─────┴─────┐
+         │           │
+    ┌────▼─────┐  ┌─▼─────────┐
+    │ Зона 1   │  │  Зона N   │
+    │ Задвижка1│  │ ЗадвижкаN │
+    │ Датчик1  │  │ ДатчикN   │
+    └──────────┘  └───────────┘
+```
+
+### 2.2 Логика работы
+
+#### Фаза 1: Опрос и сбор информации
+1. Модуль считывает текущий режим центральной установки (`mode`)
+2. Определяет текущую функцию (HEAT, COOL, FAN)
+3. Собирает команды от всех зон
+
+#### Фаза 2: PID-расчёты
+Если в зоне определён PID-контроллер:
+- Вход PID: текущая температура зоны (`val`)
+- Установка: требуемая температура зоны (`set`)
+- Выход PID: регулировочный сигнал (`po`, от 0 до 255)
+
+#### Фаза 3: Балансировка
+```
+balance = Σ(po_zone) где cmd=HEAT
+balance = Σ(-po_zone) где cmd=COOL
+```
+
+#### Фаза 4: Управление центральной установкой
+- **|balance| > boost** (по умолчанию 230) → boost: уставка AC принудительно поднимается до 30 °C (HEAT) / опускается до 17 °C (COOL)
+- **|balance| < 10** (deadband) → активность PID сбрасывается — запрос от активных зон отсутствует (L387-392)
+- **FAN/AUTO** — отправляются только при запросе зоны и lastACfan > 0, иначе команда AC не шлётся (L401-403)
+- **else** → OFF
+
+#### Фаза 5: Распределение производительности
+Для каждой зоны пересчитывается выходной сигнал задвижки:
+
+$$out = \frac{(V_{requested} \times 255) \times V_{max}}{V \times P_{max}}$$
+
+где:
+
+- $V_{requested}$ — требуемый объём воздуха для зоны
+- $V$ — номинальный объём воздуха зоны
+- $V_{max}$ — объём максимально требующей зоны
+- $P_{max}$ — максимальный процент открытия требующей зоны
+
+---
+
+## 3. Структура JSON-конфигурации
+
+### 3.1 Формат item типа 18 (Multivent)
+
+```json
+"item_name": [
+  18,
+  {
+    "zone_1": { ... },
+    "zone_2": { ... },
+    "": { ... }
+  }
+]
+```
+
+- Объект маршрутизации содержит **именованные зоны** + **пустую строку** `""` для центральной установки и общих настроек
+
+### 3.2 Структура зоны
+
+```json
+"zone_name": {
+  "fan": 0,
+  "cmd": 2,
+  "out": 255,
+  "V": 60,
+  "pid": [1.0, 0.1, 0.05, 5.0],
+  "set": 21.0,
+  "val": 21.0,
+  "cas":{
+                                    "fan":{"item":"panel1${sfx},"emit":"f_room1${sfx}","map":{"cmd":"fan"}}, 
+                                    "set":{"item":"panel1${sfx}},
+                                    "cmd":{"item":"panel1${sfx}}}}
+}
+```
+
+#### Поля зоны:
+
+| Поле | Тип | Назначение |
+|------|-----|-----------|
+| `fan` | int (0-255) | Текущий запрос в воздухе для зоны. Этот параметр устанавливается как встроенным PID регулятором  так и при помощи суффикса /fan данной зоны (изменение запускает процесс пере-балансировки зон, в результате формируется параметр out, который уже подается на задвижки  |
+| `cmd` | int | Текущая команда (OFF/ON/HEAT/COOL и т.д. в числовом виде) |
+| `out` | int (0-255) | Финальный выходной сигнал задвижки (пересчитанный) |
+| `V` | int | Номинальный объём воздуха для этой зоны (м³/ч) |
+| `pid` | массив ≥3 | Коэффициенты PID: [kP, kI, kD, dT(сек)] (позиционные) |
+| `set` | float | Требуемая температура (установка) |
+| `val` | float | Текущая температура зоны. Передается через суффикс /val данной зоны |
+| `cas` | object | Каскадирование полученной команды на другие обьекты. Полезно, если изменение статуса зоны надо, наример, отразить на климатической панели. Или если скорость вентилятора надо преобразовать в дискретный вид (LOW,MEDIUM,HIGH) и передать в отдельный топик (как в примере) для отображения в интерфейсе Home Assistant. У обьекта cas может быть три под-обьекта: fan, set, cmd которые могут отдельно транслировать скорость вентилятора, команду (режим) зоны и уставку температуры. Следует заметить, что даже без использования данной настройки, изменения зоны передаются в статусный топик зоны (для восстановления состояния при перезапуске и отражения в интерфейсе HA, так что дублировать это в данной настройке не требуется. Но данная настройка крайне полезна именно для дублирования состояния на внешние устройства а также на внутренние обьекты контроллера (отрабатывается весь синтаксис EXEC обьекта, включая возможность передачи по MQTT, CAN, локальные items)   |
+
+### 3.3 Центральная установка (пустая зона `""`)
+
+```
+"":{"item":"ac_2",
+	"turnbyfan":0,
+	"boost":200,
+	"supress":7,
+	"onextcmd":{"emit":"${sout}/vac/extcmd","item":"vac/zal"}
+	}
+```
+
+#### Поля:
+
+| Поле | Назначение |
+|------|-----------|
+|`turnbyfan`|Команда (CMD\_), генерируемая при подаче ненулевого /fan в зону, если зона в CMD\_OFF (L527, L676-683); при /fan=0 зона автоматически переводится в CMD\_OFF (L686-691). 0 — отключено |
+|`boost`|Порог |balance| (по умолчанию 230, AC\_BOOST\_TRESHOLD). При превышении модуль принудительно поднимает/опускает уставку AC (set) до 30/17 °C, чтобы усилить нагрев/охлаждение (L387-388, L1102-1123) |
+|`supress`|Битмаска подавления повторной отправки на AC: 1=FAN, 2=SET, 4=CMD (по умолчанию 0xF, AC\_SUPPRESS\_\*). **Прим.: в коде ключ «supress» (одна s)** |
+|`overridecmd`|Подмена уходящей на AC команды любой другой, кроме CMD\_OFF (L1044-1045) |
+|`onextcmd`|EXEC-объект, исполняемый при ручном (внешнем) изменении команды/уставки AC с пульта |
+| `set` | Уставка температуры AC (float); сохраняется при получении /set с AC (L582-591), читается при boost (L1106) |
+| `val` | Температура воздуха от AC (или текущее состояние) |
+| `mode` | Текущий режим AC (CMD\_HEAT/CMD\_COOL/CMD\_FAN/CMD\_OFF) |
+| `@lastCmd` | Последняя отправленная команда (служебное) |
+| `@lastFan` | Последнее отправленное значение вентилятора AC (служебное) |
+| `@lastSet` | Последнее отправленное значение уставки AC (служебное) |
+| `@preCmd` | Режим AC до останова вентилятора, восстанавливается при повторном запуске (L1078-1084) |
+| `@preset` | Уставка AC, сохранённая перед boost, восстанавливается при resetBoost (L1107, L1118) |
+| `roomtemp` | Дополнительный датчик комнатной температуры (**не читается** — обработчик S\_TEMP закомментирован, L620-623) |
+
+---
+\
+## 4. Детальная конфигурация компонентов
+
+### 4.1 PID-контроллер
+
+#### Включение PID
+
+```json
+"pid": [1.0, 0.1, 0.05, 5.0]
+```
+
+**Формат**: `[kP, kI, kD, dT]` — массив из ≥3 позиционных элементов (L61-69). Параметры аларма `AlarmTime` (сек, по умолчанию 120) и `AlarmValue` (по умолчанию 0.0) задаются **отдельными полями объекта зоны**, а не внутри `pid` (L71-72).
+
+- **kP** (пропорциональный коэффициент): 0.5—2.0
+
+- **kI** (интегральный коэффициент): 0.0—0.2
+  - Устраняет постоянное отклонение
+
+- **kD** (дифференциальный коэффициент): 0.01—0.1
+  - Снижает колебания
+
+- **dT** (период сэмплирования, сек): по умолчанию 5 сек
+
+
+#### Пример для зоны, заданный в виде массива:
+
+```json
+"pid": [1.0, 0.05, 0.02, 5.0]
+```
+
+#### Пример для зоны, заданный в виде обьекта (AlarmTime/AlarmValue — поля зоны, а не pid):
+
+```json
+"zone_name": {
+  "pid": {"kP":-1.0,"kI":0.05,"kD":0.02,"dT":50},
+  "AlarmTime":240,
+  "AlarmValue":128
+}
+```
+
+## 4.2 Объём воздуха (V)
+
+Указывается в **относительных единицах** (не обязательно м³/ч):
+
+```json
+"V": 60
+```
+
+Используется для **пропорционального распределения** между зонами.
+
+**Рекомендуемые значения:**
+- Спальня: 30—50
+- Гостиная: 60—100
+- Офис: 40—80
+- Кухня: 80—150 (если есть вентиляция)
+
+### 4.3 Маршрутизация MQTT
+
+tbd
+
+### 4.4 Каскадные команды
+
+Возможность передачи команды на другие устройства (например, открыть задвижку, вывести на панель):
+
+```json
+  "cas":{
+                                    "fan":{"item":"panel1${sfx},"emit":"f_room1${sfx}","map":{"cmd":"fan"}}, 
+                                    "set":{"item":"panel1${sfx}},
+                                    "cmd":{"item":"panel1${sfx}}}}
+```
+
+---
+
+## 5. Режимы работы модуля
+
+### 5.1 Режимы команд для зон
+
+| CMD | Назначение |
+|-----|-----------|
+| `OFF` | Задвижка закрыта, зона отключена |
+| `ON` | Зона активна (используется последний процент) |
+| `HEAT` | Зона требует нагрева (минимум 30% вентилятора: при fan < 20 принудительно выставляется 30, L805-810) |
+| `COOL` | Зона требует охлаждения |
+| `FAN` | Только вентиляция (без нагрева/охлаждения) |
+| `AUTO` | Пассивный режим (зависит от AC) |
+| `HEATCOOL` | Автоматическое переключение по PID |
+| `DRY` | Осушение |
+| `FREEZE` | Заморозка зоны: блокирует /fan, ON и OFF (L763-769; проверка в L661, L717, L735) |
+| `UNFREEZE` | Разморозка зоны (L767-769) |
+| `HIGH`/`MEDIUM`/`LOW` | Уровни вентилятора через /fan: HIGH→255, MEDIUM→128, LOW→64 (L533-546) |
+
+### 5.2 Режимы работы центральной установки
+
+Модуль автоматически определяет режим AC по текущей температуре воздуха в канале кондиционера, которую надо направить в /val:
+
+```
+AC temp < 15°C → CMD_COOL (переоборудование в холод)
+15°C ≤ AC temp ≤ 30°C → CMD_FAN (вентиляция)
+AC temp > 30°C → CMD_HEAT (переоборудование в тепло)
+```
+
+Если температура от AC не поступила (NaN), режим берётся из текущего режима AC (`mode`) (L228).
+
+Важно: при обнаружении холода или тепла автоматичесуки активируются PID регуляторы зон. Их выходы направляются на вход блока балансировки зон. Таким образом, система ререходит в режим нагрева или охлаждения зон с контролем температуры.  А прямое управление по входу /fan зон блокируется, (но последее переданное в зону значение запоминается). После того как система обнаруживает переход установки из режима нагрева либо охлаждения в режим вентиляции, она использует последнее полученное на вход /fan зоны значение для балансировки воздушного потока в каждую зону. И система переходит в режим вентиляции. В этом режиме, используются поступающие извне на вход /fan сигналы запросов воздуха в каждую зону (например, от PID регулятора уровня CO2)
+
+### 5.3 PID-режимы
+
+#### DIRECT (Kp > 0)
+- Выход растёт при увеличении отклонения (set > val)
+- Используется для режима HEAT
+
+#### REVERSE (Kp < 0)
+- Выход растёт при уменьшении отклонения (set < val)
+- Используется для режима COOL
+
+режим работы регуляторв переключается автоматически в зависимости от температуры воздуха в канале. При нагреве включается прямой режим. При охлаждении - обратный.
+
+**Автоматическое переключение в режиме CMD_AUTO:**
+```
+AC в HEAT → PID в DIRECT
+AC в COOL → PID в REVERSE
+```
+
+---
+
+## 6. Примеры конфигурации
+
+### 6.1 Простая двухзональная система
+
+**Сценарий**: кондиционер на два помещения, каждое с вентилятором и датчиком температуры.
+
+```json
+{
+  "mqtt": ["lh1", "192.168.1.10"],
+  "topics": {"root": "home"},
+  
+  "items": {
+    "ac_multizone": [
+      [18, 5],
+      {
+        "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"}
+        },
+        "living_room": {
+          "fan": {"emit": "home/living/fan"},
+          "cmd": {"emit": "home/living/cmd"},
+          "out": {"emit": "home/living/out"},
+          "V": 80,
+          "pid": [1.0, 0.05, 0.02, 5.0],
+          "set": {"emit": "home/living/setpoint"},
+          "val": {"emit": "home/living/temp"}
+        },
+        "": {
+          "val": {"emit": "home/ac/indoor_temp"},
+          "mode": {"emit": "home/ac/mode"}
+        }
+      }
+    ]
+  }
+}
+```
+
+### 6.2 Трёхзональная система с разными объёмами
+
+```json
+{
+  "mqtt": ["lh2", "broker.local"],
+  "topics": {"root": "climate"},
+  
+  "items": {
+    "ventilation": [
+      [18, 5],
+      {
+        "zone_a": {
+          "fan": {"emit": "climate/a/fan"},
+          "cmd": {"emit": "climate/a/cmd"},
+          "out": {"emit": "climate/a/out"},
+          "V": 50,
+          "pid": [-1.5, 0.08, 0.03, 5.0],
+          "set": 22.0,
+          "val": {"emit": "climate/a/temp"}
+        },
+        "zone_b": {
+          "fan": {"emit": "climate/b/fan"},
+          "cmd": {"emit": "climate/b/cmd"},
+          "out": {"emit": "climate/b/out"},
+          "V": 100,
+          "pid": [-1.5, 0.08, 0.03, 5.0],
+          "set": 24.0,
+          "val": {"emit": "climate/b/temp"}
+        },
+        "zone_c": {
+          "fan": {"emit": "climate/c/fan"},
+          "cmd": {"emit": "climate/c/cmd"},
+          "out": {"emit": "climate/c/out"},
+          "V": 30,
+          "pid": [-1.5, 0.08, 0.03, 5.0],
+          "set": 20.0,
+          "val": {"emit": "climate/c/temp"}
+        },
+        "": {
+          "val": {"emit": "climate/central/temp"},
+          "mode": {"emit": "climate/central/mode"}
+        }
+      }
+    ]
+  }
+}
+```
+
+### 6.3 Система с каскадным управлением задвижками
+
+```json
+"zone_main": {
+  "fan": {"emit": "hvac/main/fan"},
+  "cmd": {"emit": "hvac/main/cmd"},
+  "out": {"emit": "hvac/main/out"},
+  "V": 60,
+  "pid": [0.8, 0.04, 0.01, 5.0],
+  "set": {"emit": "hvac/main/setpoint"},
+  "val": {"emit": "hvac/main/temp"},
+  "cas": {
+    "emit": "hvac/main/damper_cmd"
+  }
+}
+```
+
+### 6.4 Реальная система: Haier с четырьмя зонами
+
+**Сценарий**: кондиционер Haier с управлением через Modbus, 4 комнаты с независимыми задвижками и датчиками 1-Wire.
+
+```json
+{
+  "mqtt": ["ac", "192.168.1.4"],
+  "syslog": ["192.168.1.4"],
+  "topics": {"root": "home"},
+  
+  "ow": {
+    "283A3F81E3503CC8": {"emit": "t_ac2", "item": "vac"},
+    "286C3381E3823CBC": {"emit": "t_zal", "item": "vac/zal"},
+    "28B41581E3563CDE": {"emit": "t_bedr21", "item": "vac/bedr21"},
+    "28C1A581E3563C2D": {"emit": "t_bedr22", "item": "vac/bedr22"}
+  },
+  
+  "modbus": {
+    "haier": {
+      "baud": 9600,
+      "serial": "8N1",
+      "poll": {
+        "regs": [[0, 3]],
+        "irs": [[0, 1]],
+        "coils": [0],
+        "delay": 10000
+      },
+      "par": {
+        "pwr": {
+          "coil": 0,
+          "map": {"cmd": [1, ["OFF", 0]], "val": null, "def": "acmode"},
+          "id": 1
+        },
+        "acmode": {
+          "reg": 1,
+          "map": {
+            "cmd": [
+              ["FAN_ONLY", 4],
+              ["HEAT", 2],
+              ["COOL", 1],
+              ["DRY", 3],
+              ["AUTO", 5]
+            ],
+            "val": null
+          },
+          "id": 1
+        },
+        "$temp": {"ir": 0},
+        "set": {"reg": 0, "id": 2},
+        "fan": {
+          "reg": 2,
+          "id": 7,
+          "map": {
+            "cmd": [
+              ["LOW", 1],
+              ["HIGH", 3],
+              ["MEDIUM", 2],
+              ["AUTO", 4]
+            ],
+            "val": [1, 255, 1, 3]
+          }
+        }
+      }
+    }
+  },
+  
+  "items": {
+    "ac_2": [
+      14,
+      [
+        "haier",
+        {
+          "pwr": {"emit": "home/ac/cmd", "item": "vac/mode", "@V": null},
+          "$temp": {"emit": "home/ac/temp", "item": "vac/temp", "@S": null},
+          "set": {"emit": "home/ac/setpoint", "item": "vac/set"},
+          "acmode": {"emit": "home/ac/mode", "@V": null},
+          "fan": {"emit": "home/ac/fan", "@V": null}
+        }
+      ]
+    ],
+    
+    "vac": [
+      [18, 5],
+      {
+        "": {"item": "ac_2"},
+        "zal": {
+          "pid": [490, 100, 9879, 40],
+          "set": 21.0,
+          "fan": 0,
+          "cmd": 14,
+          "item": "acgzal/set"
+        },
+        "bedr21": {
+          "pid": [490, 100, 9879, 40],
+          "set": 21.0,
+          "fan": 0,
+          "cmd": 14,
+          "item": "acgbedr21/set"
+        },
+        "bedr22": {
+          "pid": [490, 100, 9879, 40],
+          "set": 21.0,
+          "fan": 0,
+          "cmd": 14,
+          "item": "acgbedr22/set"
+        }
+      }
+    ],
+    
+    "acgzal": [7, ["ig2", "og1"]],
+    "acgbedr22": [7, ["ig1", "og2"]],
+    "acgbedr21": [7, ["ig4", "og3"]],
+    
+    "og1": [12, [4, 33, 58, 629, 289, 5000]],
+    "og2": [12, [5, 32, 59, 631, 296, 5000]],
+    "og3": [12, [6, 31, 60, 627, 289, 5000]],
+    
+    "ig1": [12, [8, 29, 62, 623, 286, 5000]],
+    "ig2": [12, [7, 30, 63, 634, 296, 5000]],
+    "ig4": [12, [11, 27, 65, 620, 289, 5000]]
+  }
+}
+```
+
+**Пояснение примера:**
+
+- **AC (ac_2)**: контроллер Haier, управляется через Modbus (скорость 9600, опрос каждые 10 сек)
+- **Зоны** (zal, bedr21, bedr22): каждая имеет PID [490, 100, 9879, 40] — агрессивные коэффициенты для точного контроля
+- **1-Wire датчики**: подключены четыре датчика температуры
+- **Задвижки**: управляются через цифровые выходы (og1-og3) с припасовкой через item [12, ...]
+- **Входы**: чтение датчиков через item [12, ...] для каждой зоны
+
+---
+
+## 7. Протокол управления через MQTT
+
+### 7.1 Отправка значений на контроллер
+
+#### Установка команды для зоны
+```
+Публикуй в: home/bedroom/cmd
+Сообщение: 1 (CMD_ON)
+```
+
+#### Установка процента вентилятора
+```
+Публикуй в: home/bedroom/fan
+Сообщение: 128
+```
+
+#### Установка требуемой температуры
+```
+Публикуй в: home/bedroom/setpoint
+Сообщение: 22.5
+```
+
+#### Установка текущей температуры (от датчика)
+```
+Публикуй в: home/bedroom/temp
+Сообщение: 21.8
+```
+
+### 7.2 Получение значений от контроллера
+
+#### Выходной сигнал задвижки
+```
+Подпишись на: home/bedroom/out
+Значение: 0—255 (0=закрыто, 255=открыто)
+```
+
+#### Режим работы центральной установки
+```
+Подпишись на: home/ac/mode
+Значения: коды команд из itemCmd.h — ON=1, OFF=2, FAN_ONLY=15, HEAT=20, COOL=21; фактические значения в топике зависят от modbus-мапы (пример §6.4: HEAT=2, COOL=1, FAN_ONLY=4, DRY=3, AUTO=5)
+```
+
+---
+
+## 8. Алгоритм балансировки воздушного потока
+
+### 8.1 Принцип работы
+
+Модуль обеспечивает **пропорциональное распределение** воздуха между зонами в зависимости от их требований.
+
+### 8.2 Пример расчёта
+
+**Исходные данные:**
+- Зона 1: V=40 м³/ч, fan=100%, po=200 → требуемый поток = 40×100% = 40
+- Зона 2: V=80 м³/ч, fan=80%, po=180 → требуемый поток = 80×80% = 64
+- Макс требуемый поток: 64 (зона 2)
+
+**Расчёт выходов:**
+- Зона 1: $out_1 = \frac{40 \times 255 \times 80}{40 \times 80} = 255$
+- Зона 2: $out_2 = \frac{64 \times 255 \times 80}{80 \times 80} = 204$
+
+**Результат:**
+- Зона 1: открыта на 255 (100%)
+- Зона 2: открыта на 204 (80%)
+
+---
+
+## 9. Специальные параметры и флаги
+
+### 9.1 Служебные поля
+
+```json
+"@lastCmd": -1,      // Последняя отправленная AC команда
+"roomtemp": 0.0,     // Дополнительный датчик комнаты (не читается — S_TEMP закомментирован)
+"po": -2.0,          // Выход PID (внутренне)
+"fan_in": 0,         // Последнее внешнее значение /fan, восстанавливается после выхода из пассивного режима (L667)
+"@pasv": 0,          // Флаг пассивного режима зоны (L284)
+"@precmd": 15,       // Предыдущий режим зоны до OFF, восстанавливается при ON (L723, L736)
+"@preHaltcmd": 0     // Команда зоны до глобального останова (stopAllzones), восстанавливается при повторном включении AC (L177, L196)
+```
+
+### 9.2 Таймаут неактивности
+
+Если текущая температура от AC не обновлялась 60 секунд, модуль очищает её.
+
+---
+
+## 10. Интеграция с внешними системами
+
+### 10.1 Подключение задвижек
+
+```json
+"zone_name": {
+  "out": {
+    "emit": "building/room1/damper_position"
+  }
+}
+```
+
+Затем в другом item'е (например, цифровой выход):
+
+```json
+"damper": [
+  3,
+  ["GPIO_PIN_5", {"emit": "building/room1/damper_position"}]
+]
+```
+
+### 10.2 Подключение датчиков температуры
+
+```json
+"zone_name": {
+  "val": {
+    "emit": "sensors/room1/temperature"
+  }
+}
+```
+
+### 10.3 Управление центральным AC через Modbus
+
+```json
+"": {
+  "val": {
+    "emit": "ac_unit/room_temp"
+  },
+  "mode": {
+    "emit": "ac_unit/operation_mode"
+  }
+}
+```
+
+---
+
+## 11. Рекомендации по эксплуатации
+
+### 11.1 Настройка PID-контроллеров
+
+1. **Начальные значения:** Kp=1.0, Ki=0.05, Kd=0.02, dT=5сек
+2. **Тестирование:** постепенно увеличивайте Kp до появления колебаний
+3. **Стабилизация:** добавляйте Ki для устранения постоянного смещения
+4. **Демпфирование:** добавляйте Kd для снижения колебаний
+
+### 11.2 Распределение объёмов (V)
+
+- Убедитесь, что сумма V соответствует производительности центральной установки
+- Для равномерного распределения: V ≈ площадь помещения
+- Для приоритизации: увеличьте V критичным зонам
+
+### 11.3 Мониторинг системы
+
+- Отслеживайте `balance` в логах (должен быть близко к нулю в установившемся режиме)
+- Проверяйте `out` для каждой зоны (не должны быть постоянно на 0 или 255)
+- Контролируйте переходы режимов (HEAT↔COOL) — не должны быть частыми
+
+### 11.4 Диагностика проблем
+
+| Проблема | Причина | Решение |
+|----------|---------|---------|
+| Задвижки не реагируют | `out` зоны = 0 | Повысить fan или cmd |
+| Колебания температуры | PID слишком агрессивен | Снизить Kp |
+| Не достигается setpoint | PID недостаточен | Увеличить Ki |
+| AC часто переключается | balance скачет | Увеличить dT в PID |
+
+---
+
+## 12. Ограничения и известные особенности
+
+⚠️ **Важно:**
+
+1. **Автономный dT:** у каждого PID-регулятора зон свой период сэмплирования dT (L69), задаётся отдельно для каждой зоны через SetSampleTime (L75)
+2. **Порядок обработки:** сначала зоны, потом центральная установка
+3. **Гистерезис режимов:** автоматическое переключение AC может быть медленным (до 60 сек при отсутствии данных)
+4. **Отсутствие истории:** модуль не сохраняет историю команд между перезагрузками
+
+---
+
+## 13. Заключение
+
+Модуль `out_Multivent` предоставляет **промышленную-grade** решение для управления многозональными системами климатизации.
+
+Ключевые преимущества:
+
+- ✅ Интеллектуальная балансировка воздушного потока
+- ✅ Независимое PID-регулирование для каждой зоны
+- ✅ Автоматическая агрегация команд
+- ✅ Каскадное управление внешними системами
+
+---
+
+**Версия документа:** 1.0  
+**Дата:** 2026-01-21  
+**Статус:** Утверждено