andry/lighthub
1
0
Fork 0
mirror of https://github.com/anklimov/lighthub synced 2026-10-28 11:15:00 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
e442001ec913d8a3b8541b7d69ba779d35d43757
lighthub/documentation/modules_description.md
T

33 KiB
Raw 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_Sprinkler — Система полива

Описание

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

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

  • Управление несколькими зонами полива независимо
  • Установка длительности полива для каждой зоны
  • Таймеры и расписания для автоматизации
  • Мониторинг прогресса выполнения
  • Поддержка ручного управления и автоматических режимов
  • Контроль состояния клапанов и электромагнитных выключателей

Тип в JSON

[23, ["device_name", {zones_configuration}]]

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

"irrigation_system": [
  23,
  [
    "main_sprinkler",
    {
      "": {
        "cmd": {"emit": "sprinkler/cmd"},
        "val": {"emit": "sprinkler/state"}
      },
      "north_zone": {
        "enabled": {"emit": "sprinkler/north/enabled"},
        "time": {"emit": "sprinkler/north/time"},
        "progress": {"emit": "sprinkler/north/progress"},
        "cycle": {"emit": "sprinkler/north/cycle"}
      },
      "south_zone": {
        "enabled": {"emit": "sprinkler/south/enabled"},
        "time": {"emit": "sprinkler/south/time"},
        "progress": {"emit": "sprinkler/south/progress"},
        "cycle": {"emit": "sprinkler/south/cycle"}
      },
      "drip_zone": {
        "enabled": {"emit": "sprinkler/drip/enabled"},
        "time": {"emit": "sprinkler/drip/time"},
        "progress": {"emit": "sprinkler/drip/progress"},
        "cycle": {"emit": "sprinkler/drip/cycle"}
      }
    }
  ]
]

Компоненты системы

Компонент Выход/Вход Назначение
Бак полива wMax, wMin Поплавки макс/мин уровня воды
Основной насос rPump, fbPump Реле включения, датчик тока
Клапаны зон pin (для каждой зоны) Оптореле открытия клапана
Клапан налива vIn Оптореле подачи воды из водопровода
Дренажный насос rDren, fbDren Реле включения, датчик тока
Водосчётчик wCtr (опционально) Счётчик объёма воды

Параметры конфигурации

Параметр Тип Описание
vIn int GPIO клапана налива из водопровода
wMax int GPIO поплавка максимума в баке
wMin int GPIO поплавка минимума в баке
rDren int GPIO реле дренажного насоса
fbDren int GPIO датчика дренажного насоса
rPump int GPIO реле основного насоса полива
fbPump int GPIO датчика основного насоса
wCtr int GPIO счётчика воды (опционально)

Параметры зоны полива

Параметр Тип Описание
pin int GPIO клапана зоны
set int Требуемый объём полива или время (сек). 0 = неограниченно
cmd int Начальное состояние (0=OFF, 1=ON, 2=другое)

Состояния системы налива

Состояние Описание
SP_UNKNOWN Неизвестное состояние
SP_OFF Система выключена
SP_DREN_ON Дренажный насос включен
SP_DREN_OPERATE Дренажный насос работает
SP_DREN_EMPTY Дренажный колодец пуст
SP_VIN Наполнение из водопровода
SP_FULL Бак наполнен
SP_FAULT_VIN Ошибка: бак не наполнился из водопровода
SP_FAULT_DREN Ошибка: бак не наполнился из дренажа

MQTT топики управления

Управление циклом полива (команды)

root/name/sprinkler/cmd ← ON          # Запустить цикл полива
root/name/sprinkler/cmd ← OFF         # Остановить цикл полива
root/name/sprinkler/cmd ← XON         # Включить (может быть заблокировано DISABLE)
root/name/sprinkler/cmd ← XOFF        # Выключить
root/name/sprinkler/cmd ← RESET       # Сбросить счётчики всех зон
root/name/sprinkler/cmd ← FREEZE      # Блокировка на зиму
root/name/sprinkler/cmd ← UNFREEZE    # Разблокировка
root/name/sprinkler/cmd ← DRY         # Режим осушения системы

Управление конкретной зоной (например, "north")

root/name/sprinkler/north/cmd ← ON    # Включить полив зоны
root/name/sprinkler/north/cmd ← OFF   # Выключить полив зоны
root/name/sprinkler/north/set ← 60    # Требуемый объём/время полива (секунды или единицы счётчика)

Режимы системы (установка в /ctrl)

root/name/sprinkler/ctrl ← ENABLE     # Разрешить полив
root/name/sprinkler/ctrl ← DISABLE    # Запретить полив (например, после дождя)
root/name/sprinkler/ctrl ← FREEZE     # Полная блокировка на зиму
root/name/sprinkler/ctrl ← UNFREEZE   # Снять блокировку зимы

Автоматическая блокировка по температуре

root/name/sprinkler/val ← -1          # При температуре < 0 система автоматически переходит в FREEZE

MQTT топики мониторинга (статус)

root/s_out/sprinkler/$state          # Состояние системы налива воды (SP_*)
root/s_out/sprinkler/$fault          # Код ошибки (если есть)
root/s_out/sprinkler/$wMax           # ON/OFF - бак полный (поплавок макс)
root/s_out/sprinkler/$wMin           # ON/OFF - бак пуст (поплавок мин)
root/s_out/sprinkler/$rPump          # ON/OFF - реле основного насоса включено
root/s_out/sprinkler/$fbPump         # ON/OFF - основной насос работает (датчик тока)
root/s_out/sprinkler/$rDren          # ON/OFF - реле дренажного насоса включено
root/s_out/sprinkler/$fbDren         # ON/OFF - дренажный насос работает (датчик тока)
root/s_out/sprinkler/$rVIN           # ON/OFF - клапан налива из водопровода открыт
root/s_out/sprinkler/set             # Текущее значение счётчика воды

root/s_out/sprinkler/north/$state    # ON/OFF - зона поливается в настоящее время
root/s_out/sprinkler/north/cmd       # ON/OFF - состояние команды включения зоны
root/s_out/sprinkler/north/set       # Требуемый объём/время полива
root/s_out/sprinkler/north/val       # Текущий выполненный объём/время полива зоны

root/s_out/sprinkler/south/$state    # ON/OFF - зона поливается
root/s_out/sprinkler/south/cmd       # ON/OFF - состояние команды
root/s_out/sprinkler/south/set       # Требуемый объём/время
root/s_out/sprinkler/south/val       # Выполненный объём/время

# Аналогично для остальных зон (например, "trees", "outlets" и т.д.)

Особенности

Особенность Описание
Динамическое управление Все параметры можно изменять через MQTT в реальном времени
Восстановление состояния Значения set и val восстанавливаются из топиков s_out при перезагрузке
Водяная розетка Зона с set=0 работает неограниченно (используется для розеток с шлангом)
Приоритет дренажа Система сначала пытается наполнить бак из дренажного колодца, затем из водопровода
Автозащита от мороза Значение /val < 0 автоматически активирует режим FREEZE
Двухступенчатая блокировка DISABLE блокирует команды, FREEZE полностью заморозит систему

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_Sprinkler 23 Система полива GPIO + MQTT
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
Статус: Утверждено

Reference in New Issue View Git Blame Copy Permalink