lighthub/documentation/modules_description.md

# LightHub: Описание модулей и компонентов

> Полное инженерное описание всех основных модулей LightHub с примерами конфигурации и протоколами управления.
> Предназначено для разработчиков, интеграторов и системных инженеров.

---

## Содержание

1. [Выходные модули (Out)](#выходные-модули)
   - [out_Multivent](#out_multivent---многоканальный-кондиционер-вентиляция)
   - [out_AC](#out_ac---управление-кондиционером)
   - [out_PID](#out_pid---пид-регулятор)
   - [out_Relay](#out_relay---электромагнитное-реле)
   - [out_PWM](#out_pwm---широтно-импульсная-модуляция)
   - [out_DMX](#out_dmx---dmx512-управление-светом)
   - [out_Motor](#out_motor---управление-двигателем)
   - [out_Elevator](#out_elevator---управление-лифтом)
   - [out_Humidifier](#out_humidifier---управление-увлажнителем)
   - [out_Counter](#out_counter---счётчик-импульсов)
   - [out_SPILed](#out_spiled---управление-светодиодами)
   - [out_Mercury](#out_mercury---счётчик-меркурий)
   - [out_UARTBridge](#out_uartbridge---uart-мост)

2. [Входные модули (In)](#входные-модули)
   - [in_CCS811_HDC1080](#in_ccs811_hdc1080---датчик-качества-воздуха)

---

# Выходные модули

## out_Multivent — Многоканальный кондиционер/вентиляция

### Описание

Модуль управления многозональными системами кондиционирования воздуха и центральной вентиляции.

**Основные функции:**
- Управление центральной установкой (компрессор, вентилятор)
- Независимое регулирование температуры для каждой зоны/комнаты
- PID-контроллеры для стабилизации микроклимата
- Автоматическая балансировка воздушного потока между зонами
- Каскадное управление задвижками и затворами

### Тип в JSON
```
[14, ["device_name", {zones_and_settings}]]
```

### Формат конфигурации

```json
"multizone_ac": [
  14,
  [
    "haier",
    {
      "": {
        "val": {"emit": "home/ac/temp"},
        "mode": {"emit": "home/ac/mode"}
      },
      "bedroom": {
        "fan": {"emit": "home/bedroom/fan"},
        "cmd": {"emit": "home/bedroom/cmd"},
        "out": {"emit": "home/bedroom/out"},
        "V": 40,
        "pid": [1.0, 0.05, 0.02, 5.0],
        "set": {"emit": "home/bedroom/setpoint"},
        "val": {"emit": "home/bedroom/temp"}
      }
    }
  ]
]
```

### Ключевые параметры

| Параметр | Тип | Описание |
|----------|-----|---------|
| `V` | int | Номинальный объём воздуха (м³/ч) |
| `pid` | [Kp, Ki, Kd, dT] | Коэффициенты PID-регулятора |
| `set` | float | Требуемая температура |
| `val` | float | Текущая температура |
| `fan` | int (0-255) | Открытие вентилятора |
| `cmd` | int | Команда (OFF, ON, HEAT, COOL, FAN, etc.) |
| `out` | int (0-255) | Выход задвижки |

### Режимы команд

- `CMD_OFF` (0) — отключено
- `CMD_ON` (1) — включено
- `CMD_HEAT` (2) — нагрев
- `CMD_COOL` (3) — охлаждение
- `CMD_FAN` (4) — вентиляция
- `CMD_DRY` (5) — осушение

### Примеры

Полное описание с примерами: [multivent_module_description.md](multivent_module_description.md)

---

## out_AC — Управление кондиционером

### Описание

Управление одиночным кондиционером через Modbus или прямое управление через протокол AC (18-100 байт).

**Основные функции:**
- Управление режимом (HEAT, COOL, FAN, DRY, AUTO)
- Управление скоростью вентилятора (LOW, MEDIUM, HIGH, AUTO)
- Управление температурой
- Поддержка качания жалюзей (SWING)
- Блокировка пульта
- Режим QUIET (тихий режим)

### Тип в JSON
```
[128, ["device_name", {parameters}]]
```

### Формат конфигурации

```json
"air_conditioner": [
  128,
  [
    "haier",
    {
      "pwr": {"emit": "home/ac/power"},
      "acmode": {"emit": "home/ac/mode"},
      "set": {"emit": "home/ac/setpoint"},
      "fan": {"emit": "home/ac/fan_speed"},
      "swing": {"emit": "home/ac/swing"},
      "lock": {"emit": "home/ac/lock"},
      "$temp": {"emit": "home/ac/temp"}
    }
  ]
]
```

### Параметры управления

| Параметр | Значение | Описание |
|----------|----------|---------|
| `pwr` | ON/OFF | Питание компрессора |
| `acmode` | COOL/HEAT/FAN/DRY/AUTO | Режим |
| `set` | 16-32°C | Установка температуры |
| `fan` | LOW/MED/HIGH/AUTO | Скорость вентилятора |
| `swing` | ON/OFF | Качание жалюзей |
| `$temp` | читаемый | Текущая температура воздуха |

---

## out_PID — PID-регулятор

### Описание

Универсальный PID-контроллер для стабилизации любых процессов (температура, влажность, давление и т.д.).

**Основные функции:**
- Независимое PID-регулирование с тремя коэффициентами
- Регулируемый период сэмплирования
- Будильник при выходе за пределы диапазона
- Защита от интегральной раскрутки

### Тип в JSON
```
[17, ["input_topic", "setpoint", "output_topic"]]
```

### Формат конфигурации

```json
"temperature_controller": [
  17,
  [
    {"emit": "sensors/room/temp"},
    21.5,
    {"emit": "heating/power"}
  ]
]
```

### JSON с полными параметрами

```json
"pid_climate": [
  17,
  {
    "in": {"emit": "sensors/temp"},
    "set": 22.0,
    "out": {"emit": "hvac/power"},
    "Kp": 1.0,
    "Ki": 0.05,
    "Kd": 0.02,
    "dT": 5,
    "alarm": 2.0,
    "alarmTimeout": 300
  }
]
```

### Параметры

| Параметр | Тип | Диапазон | Описание |
|----------|-----|----------|---------|
| `Kp` | float | 0.1—10.0 | Пропорциональный коэффициент |
| `Ki` | float | 0.0—1.0 | Интегральный коэффициент |
| `Kd` | float | 0.0—1.0 | Дифференциальный коэффициент |
| `dT` | int | 1—60 | Период сэмплирования (сек) |
| `alarm` | float | - | Порог срабатывания будильника |
| `alarmTimeout` | int | - | Время до срабатывания будильника (сек) |

---

## out_Relay — Электромагнитное реле

### Описание

Управление электромагнитными реле через цифровой выход микроконтроллера.

**Основные функции:**
- Включение/отключение нагрузки
- Поддержка инвертированной логики
- Управление периодом переключения

### Тип в JSON
```
[1, [pin, {settings}]]
```

### Формат конфигурации

```json
"pump_relay": [
  1,
  [
    33,
    {
      "inverted": false
    }
  ]
]
```

### Параметры

| Параметр | Тип | Описание |
|----------|-----|---------|
| `pin` | int | Номер GPIO-пина |
| `inverted` | bool | Инвертировать логику (false = HIGH=ON) |
| `period` | int | Период срабатывания (мс) |

### Управление

```
Отправить: home/pump_relay
Значение: 0 (OFF) или 1 (ON)
```

---

## out_PWM — Широтно-импульсная модуляция

### Описание

Управление PWM для регулирования яркости светодиодов, скорости двигателей, интенсивности нагрузок.

**Основные функции:**
- Регулирование от 0% до 100%
- Поддержка RGB-управления (в base-классе colorChannel)
- Частотные настройки

### Тип в JSON
```
[9, [channel, freq, {settings}]]
```

### Формат конфигурации

```json
"led_brightness": [
  9,
  [
    5,
    1000,
    {}
  ]
]
```

### Управление

```
Отправить: home/led/brightness
Значение: 0-255 (0=0%, 255=100%)
```

---

## out_DMX — DMX512 управление светом

### Описание

Управление световыми приборами по протоколу DMX512 (театральное и архитектурное освещение).

**Основные функции:**
- Поддержка до 512 каналов
- Управление цветом и интенсивностью
- Синхронизированное обновление

### Тип в JSON
```
[11, [channel_list, {settings}]]
```

### Формат конфигурации

```json
"stage_lighting": [
  11,
  [
    [1, 2, 3, 4],
    {}
  ]
]
```

### Управление

```
Отправить: home/lighting/color
Значение: {"r":255, "g":128, "b":0}
```

---

## out_Motor — Управление двигателем

### Описание

Управление моторами с обратной связью по положению (рольставни, жалюзи, шторы).

**Основные функции:**
- Управление направлением (вверх/вниз)
- Обратная связь по положению
- Защита от перегрузки по времени
- Плавное позиционирование

### Тип в JSON
```
[3, [pin_up, pin_down, pin_feedback, {settings}]]
```

### Формат конфигурации

```json
"roller_blind": [
  3,
  [
    32,
    33,
    34,
    {
      "maxOnTime": 120000,
      "feedbackOpen": 0,
      "feedbackClosed": 1023,
      "inverted": false
    }
  ]
]
```

### Параметры

| Параметр | Тип | Описание |
|----------|-----|---------|
| `pinUp` | int | GPIO для движения вверх |
| `pinDown` | int | GPIO для движения вниз |
| `pinFeedback` | int | GPIO обратной связи (аналоговый) |
| `maxOnTime` | int | Макс. время работы (мс), 120000 = 2 мин |
| `feedbackOpen` | int | Значение обратной связи (открыто) |
| `feedbackClosed` | int | Значение обратной связи (закрыто) |

### Команды

| Команда | Значение | Описание |
|---------|----------|---------|
| UP | -1 | Поднять |
| DOWN | 1 | Опустить |
| STOP | 0 | Остановить |
| Позиция | 0-255 | Установить позицию (0=открыто, 255=закрыто) |

---

## out_Elevator — Управление лифтом

### Описание

Управление лифтом через UART или интерфейс вызова. Синхронизация между контроллерами через сетевой мост.

**Основные функции:**
- Управление вызовом лифта
- Передача команды на нужный этаж
- Контроль состояния лифта
- Дублирование по UART

### Тип в JSON
```
[ELEVATOR_TYPE, ["uart_port", {settings}]]
```

### Формат конфигурации

```json
"elevator": [
  50,
  [
    "Serial1",
    {
      "baud": 9600,
      "floors": 5
    }
  ]
]
```

### Параметры UART

| Параметр | Значение | Описание |
|----------|----------|---------|
| `baud` | 9600-115200 | Скорость UART |
| `serialParam` | 8N1 | Параметры кадра |

---

## out_Humidifier — Управление увлажнителем

### Описание

Управление промышленным ультразвуковым или парогенерирующим увлажнителем с контролем давления и защитой от отказов.

**Основные функции:**
- Контроль давления в баке
- Управление электромагнитными клапанами
- Защита от перепада давления
- Автоматическая очистка (FLUSH)
- Состояния готовности и отказа

### Тип в JSON
```
[HUMIDIFIER_TYPE, [pump_pin, valve_pin, pressure_pin, {settings}]]
```

### Формат конфигурации

```json
"mist_humidifier": [
  40,
  [
    25,
    26,
    35,
    {
      "minPressure": 400,
      "maxPressure": 600,
      "flushInterval": 125000
    }
  ]
]
```

### Состояния

| Состояние | Код | Описание |
|-----------|-----|---------|
| H_UNKNOWN | 0 | Неизвестное |
| H_READY | 1 | Готов к работе |
| H_PREPARE_FOR_START | 2 | Подготовка к пуску |
| H_MOTOR_ON | 4 | Мотор работает |
| H_OPERATE | 5 | В режиме увлажнения |
| H_FLUSH | 8 | Промывка системы |
| H_FAULT_PRESSURE | -1 | Ошибка давления |
| H_FAULT_OVERPRESSURE | -3 | Перепад давления |

---

## out_Counter — Счётчик импульсов

### Описание

Счётчик импульсов для контроля расхода (воды, газа) или подсчета событий.

**Основные функции:**
- Подсчет импульсов
- Накопление значений
- Фильтрация дребезга контактов
- Калибровка по расходу

### Тип в JSON
```
[6, [input_pin, {settings}]]
```

### Формат конфигурации

```json
"water_meter": [
  6,
  [
    14,
    {
      "pulsePerLiter": 10,
      "debounce": 100
    }
  ]
]
```

### Параметры

| Параметр | Тип | Описание |
|----------|-----|---------|
| `pulsePerLiter` | int | Кол-во импульсов на 1 литр (для расчета) |
| `debounce` | int | Фильтрация дребезга (мс) |

---

## out_SPILed — Управление светодиодами

### Описание

Управление адресуемыми RGB-светодиодами (WS2812, APA102) через SPI или GPIO.

**Основные функции:**
- Независимое управление каждым светодиодом
- RGB-цветовая палитра
- Эффекты и анимации
- Поддержка Adafruit и FastLED библиотек

### Тип в JSON
```
[10, [pin, numLeds, ledsType, {settings}]]
```

### Формат конфигурации

```json
"led_strip": [
  10,
  [
    13,
    30,
    0,
    {}
  ]
]
```

### Параметры

| Параметр | Тип | Описание |
|----------|-----|---------|
| `pin` | int | GPIO пин (данные) |
| `numLeds` | int | Количество светодиодов |
| `ledsType` | int | Тип: 0=WS2812 (NeoPixel), 1=APA102 |

### Управление

```
Отправить: home/leds/color
Значение: {"r":255, "g":0, "b":128}

Отправить: home/leds/brightness
Значение: 0-255
```

---

## out_Mercury — Счётчик Меркурий

### Описание

Управление и опрос электросчётчиков серии Меркурий через UART Modbus RTU.

**Основные функции:**
- Чтение энергопотребления (активная/реактивная)
- Получение тарифных данных
- Многозонное чтение (пиковое, полупиковое, ночное)
- Контроль связи и состояния счётчика

### Тип в JSON
```
[MERCURY_TYPE, ["device_address", {settings}]]
```

### Формат конфигурации

```json
"electricity_meter": [
  45,
  [
    "1",
    {
      "baud": 9600,
      "pollingInterval": 60000
    }
  ]
]
```

### Параметры Modbus

| Параметр | Значение | Описание |
|----------|----------|---------|
| `baud` | 9600 | Скорость UART |
| `pollingInterval` | мс | Интервал опроса |

### Получаемые значения

```
home/meter/total_power     - Общее потребление (кВт·ч)
home/meter/peak_power      - Пиковое потребление
home/meter/halfpeak_power  - Полупиковое потребление
home/meter/night_power     - Ночное потребление
```

---

## out_UARTBridge — UART мост

### Описание

Создание прозрачного двунаправленного моста между двумя UART портами с сохранением данных и логированием.

**Основные функции:**
- Прозрачная маршрутизация UART↔UART
- Буферизация пакетов (до 64 байт)
- Логирование трафика
- Поддержка разных скоростей на каждом порту

### Тип в JSON
```
[UARTBRIDGE_TYPE, ["portA", "portB", {settings}]]
```

### Формат конфигурации

```json
"uart_gateway": [
  55,
  [
    "Serial1",
    "Serial2",
    {
      "baudA": 9600,
      "baudB": 19200,
      "paramA": "8N1",
      "paramB": "8N1"
    }
  ]
]
```

### Параметры

| Параметр | Тип | Описание |
|----------|-----|---------|
| `baudA/B` | int | Скорость портов (9600-115200) |
| `paramA/B` | string | Формат кадра (8N1, 8E1, 8O1) |

---

# Входные модули

## in_CCS811_HDC1080 — Датчик качества воздуха

### Описание

Комбинированный датчик для измерения качества воздуха с использованием:
- **HDC1080** — датчик температуры и влажности (I2C)
- **CCS811** — датчик CO₂ и TVOC (I2C)

**Основные функции:**
- Измерение температуры (-40...125°C)
- Измерение влажности (0-100%)
- Измерение eCO₂ (400-8192 ppm)
- Измерение TVOC (0-1187 ppb)
- Температурная компенсация

### Тип в JSON
```
[SENSOR_TYPE, ["i2c_address", {settings}]]
```

### Формат конфигурации

```json
"air_quality": [
  100,
  [
    "0x5A",
    {
      "tempOffset": 0.0,
      "humidityOffset": 0.0,
      "co2Offset": 0,
      "pollInterval": 10000
    }
  ]
]
```

### Выводимые параметры

| Параметр | Единица | Диапазон | Описание |
|----------|---------|----------|---------|
| `temperature` | °C | -40...125 | Температура воздуха |
| `humidity` | % | 0...100 | Относительная влажность |
| `eCO2` | ppm | 400...8192 | Эквивалентный CO₂ |
| `TVOC` | ppb | 0...1187 | Летучие органические соединения |

### Адреса I2C

| Устройство | Адрес | Описание |
|-----------|-------|---------|
| CCS811 | 0x5A | По умолчанию (WAK на GND) |
| CCS811 | 0x5B | Альтернативный (WAK на VDD) |
| HDC1080 | 0x40 | Всегда фиксирован |

### MQTT маршрутизация

```json
{
  "temp": {"emit": "home/sensors/air/temperature"},
  "humidity": {"emit": "home/sensors/air/humidity"},
  "co2": {"emit": "home/sensors/air/co2"},
  "tvoc": {"emit": "home/sensors/air/tvoc"}
}
```

### Примеры использования

#### Простой мониторинг качества воздуха

```json
"room_air_sensor": [
  100,
  [
    "0x5A",
    {
      "emit": "home/sensors/living_room/air"
    }
  ]
]
```

#### С калибровкой смещений

```json
"calibrated_sensor": [
  100,
  [
    "0x5A",
    {
      "tempOffset": -2.5,
      "humidityOffset": 5.0,
      "co2Offset": 50,
      "pollInterval": 30000,
      "emit": "sensors/hvac/inlet"
    }
  ]
]
```

---

## Сводная таблица типов модулей

| Модуль | Тип | Назначение | Управление |
|--------|-----|-----------|-----------|
| out_Multivent | 14 | Многоканальный кондиционер | PID + MQTT |
| out_AC | 128 | Одиночный кондиционер | Modbus/прямой протокол |
| out_PID | 17 | PID-регулятор | MQTT |
| out_Relay | 1 | Электромагнитное реле | GPIO |
| out_PWM | 9 | ШИМ-управление | GPIO-PWM |
| out_DMX | 11 | DMX512 освещение | DMX512 |
| out_Motor | 3 | Управление двигателем | GPIO-пары |
| out_Elevator | 50 | Управление лифтом | UART |
| out_Humidifier | 40 | Управление увлажнителем | GPIO + датчики |
| out_Counter | 6 | Счётчик импульсов | GPIO-счёт |
| out_SPILed | 10 | Адресуемые светодиоды | SPI/GPIO |
| out_Mercury | 45 | Электросчётчик | Modbus RTU |
| out_UARTBridge | 55 | UART-мост | UART↔UART |
| in_CCS811_HDC1080 | 100 | Качество воздуха | I2C |

---

## Общие принципы конфигурации

### 1. Подключение MQTT

Все параметры с полем `emit` автоматически публикуются в MQTT:

```json
"parameter": {
  "emit": "home/device/parameter"
}
```

### 2. Управление из MQTT

Отправка значения:
```
mqtt publish home/device/parameter 128
```

### 3. Использование массивов

Для нескольких параметров:
```json
[
  {"emit": "topic1"},
  {"emit": "topic2"},
  {"emit": "topic3"}
]
```

### 4. Служебные параметры

- `@V` (null) — не публиковать значения
- `@S` (null) — не публиковать при сохранении
- `@C` — служебное, не использовать

---

## Диагностика проблем

### Модуль не инициализируется

Проверить:
1. Конфигурация JSON синтаксически корректна
2. GPIO-пины не конфликтуют
3. I2C/UART устройства подключены
4. Библиотеки установлены

### Нет связи с устройством

1. Проверить скорость UART (baud)
2. Проверить подключение TX/RX
3. Проверить адрес Modbus/I2C
4. Посмотреть лог сообщений

### Неустойчивые значения PID

1. Снизить Kp (коэффициент пропорциональности)
2. Увеличить dT (период сэмплирования)
3. Добавить Kd (демпфирование)

---

**Версия документа:** 1.0  
**Дата:** 2026-01-21  
**Статус:** Утверждено