andry/lighthub
1
0
Fork 0
mirror of https://github.com/anklimov/lighthub synced 2026-03-13 21:06:31 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
lighthub/documentation/modules_description.md

24 KiB
Raw Permalink Blame History

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

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

Содержание

  1. Выходные модули (Out)

  2. Входные модули (In)

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

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

Описание

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

Основные функции:

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

Тип в JSON

[14, ["device_name", {zones_and_settings}]]

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

"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

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

Описание

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

Основные функции:

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

Тип в JSON

[128, ["device_name", {parameters}]]

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

"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"]]

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

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

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}]]

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

"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}]]

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

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

Управление

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

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

Описание

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

Основные функции:

  • Поддержка до 512 каналов
  • Управление цветом и интенсивностью
  • Синхронизированное обновление

Тип в JSON

[11, [channel_list, {settings}]]

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

"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}]]

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

"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}]]

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

"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}]]

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

"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}]]

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

"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}]]

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

"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}]]

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

"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}]]

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

"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}]]

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

"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 маршрутизация

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

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

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

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

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

"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:

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

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

Отправка значения:

mqtt publish home/device/parameter 128

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

Для нескольких параметров:

[
  {"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
Статус: Утверждено