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
f787a1627088d5b52839e2fd64c160692022a059
lighthub/documentation/core/mqtt_api_reference.md
T
andry f787a16270 docs review
2026-10-11 01:27:15 +03:00

20 KiB
Raw Blame History

LightHub: Справочник MQTT API и топиков

Инженерный справочник структуры MQTT топиков и HTTP API контроллера LightHub. Источник: wiki.lazyhome.ru - работа с MQTT и 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 конфигурации.

"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

Базовая конфигурация

{
  "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 запросов

# Включить лампу
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-устройства/# (отдельной подписки нет)

Пример полной интеграции

Конфигурация

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

Проверка связи

# Подписаться на все топики контроллера
mosquitto_sub -h 192.168.1.100 -t "myhome/#" -v

# Отправить команду
mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "ON"

Проверка статусных топиков

# Только статусные топики
mosquitto_sub -h 192.168.1.100 -t "myhome/s_out/#" -v

Версия документа: 2.1 (актуально для работа_с_mqtt из wiki.lazyhome.ru)
Источники: MQTT wiki, API wiki

Reference in New Issue View Git Blame Copy Permalink