lighthub/documentation/mqtt_api_reference.md

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/val (где 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/val

4. subitem (опционально) — подпараметр

Для каналов с множественными элементами (например, адресуемая LED лента, многозональная вентиляция).

Пример для многозональной вентиляции:

myhome/in/multivent/bedroom/set      (установить T в спальне)
myhome/in/multivent/kitchen/fan      (управление вентилятором кухни)

Пример для LED ленты (пиксели 10-20):

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	Основная команда управления (ON, OFF, TOGGLE и др.)	Все типы
/set	Parameter	Установка параметра (яркость, температура и др.)	Диммеры, регуляторы, термостаты
/val	Status	Текущее значение (в статусных топиках)	Все типы
/hue	Color	Оттенок (0-365°, HSV формат)	RGB/RGBW/RGBWW
/sat	Color	Насыщенность (0-100%, HSV формат)	RGB/RGBW/RGBWW
/hsv	Color	Полный цвет (hue,saturation,volume)	RGB/RGBW/RGBWW
/rgb	Color	Цвет в RGB/RGBW нотации	RGB/RGBW/RGBWW
/fan	Control	Скорость вентилятора (HIGH, MEDIUM, LOW)	AC, Multivent
/mode	Control	Режим работы (HEAT, COOL, DRY, FAN, AUTO)	AC, Thermostat, Multivent
/lock	Control	Блокировка (ON, OFF)	AC
/swing	Control	Направление воздушного потока (ON, OFF)	AC
/quiet	Control	Тихий режим (ON, OFF)	AC
/ctrl	Control	Управление состоянием (FREEZE, UNFREEZE, ENABLE, DISABLE)	Специальное
/del	Delayed	Команда с задержкой	Все команды

---

Три типа топиков

1. Командные топики (INPUT) — контроллер получает

Широковещательные (broadcast)

root/bcst/item[/subitem]/suffix

Примеры (при bcst="in"):

myhome/in/lamp1/cmd          ← ON
myhome/in/lamp1/set          ← 150
myhome/in/ac_main/mode       ← 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/val          → 100 (текущая яркость)
myhome/s_out/lamp1/cmd          → ON (последняя команда)
myhome/s_out/ac_main/mode       → HEAT (текущий режим)
myhome/s_out/ac_main/set        → 22 (установленная T)
myhome/s_out/multivent/bedroom/val  → 21 (текущая T в спальне)

Свойства:

• Публикуются с флагом PERSISTENT (помощь при отключении-подключении)
• При старте контроллер восстанавливает состояние из этих топиков
• При локальном изменении (через входы) тоже обновляются

3. Служебные топики (SERVICE)

Формат: root/id-устройства/$command и root/id-устройства/$stats

$command

myhome/lighthub01/$command

В payload записываются CLI команды (как если бы через последовательный порт):

• reboot
• save
• get
• load и др.

$stats (публикуется контроллером каждые 30 сек)

myhome/lighthub01/$stats

Содержит:

{
  "uptime": "12345000",
  "free_ram": "2500"
}

$state (публикуется контроллером)

myhome/lighthub01/$state  → "ready" или "disconnected"

---

Примеры конфигурации 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..100 или 0..255	Установить яркость/значение	myhome/in/lamp1/set → 50

Числовые команды

Формат	Описание	Пример
<0..100>	Яркость (OpenHab стиль)	myhome/in/lamp/set → 50
<0..255>	Яркость/PWM (новый стиль)	myhome/in/lamp/set → 128
<H>,<S>,<V>	HSV формат	myhome/in/rgb/hsv → 240,100,200
<H>,<S>	HSV без изменения яркости	myhome/in/rgb/hsv → 240,100
#RRGGBB	RGB hex (Home Remote)	myhome/in/rgb/cmd → #FF0000
<R>,<G>,<B>	RGB формат	myhome/in/rgb/rgb → 255,0,0
<R>,<G>,<B>,<W>	RGBW формат	myhome/in/rgb/rgb → 255,0,0,100

Расширенные команды

Команда	Описание	Применимость
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
HEAT	Нагрев	AC, Thermostat
COOL	Охлаждение	AC
DRY	Осушение	AC
FAN_ONLY	Только вентилятор	AC
HIGH, MED, LOW	Скорость вентилятора	AC

Команды с задержкой

Синтаксис: КОМАНДА ВРЕМЯ_МС (в топик с суффиксом /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. Контроллер подписывается на статусные топики на 5 секунд после старта
2. Брокер отправляет последний актуальный статус
3. Контроллер восстанавливает все значения: яркость, цвет, температуру и т.д.

Интерпретация команд

Контроллер интерпретирует полученные команды:

Пример:

• Получена команда: ON на RGB канал
• Контроллер восстанавливает последний цвет (HSV из памяти)
• Публикует в статусный топик: hue=240, sat=100, val=200 (вместо просто ON)

Различие /set и /cmd (с версии 3.0.0)

Что	/cmd	/set
Команда управления	✓	-
Диапазон значений	0-255	0-255 (новый) или 0-100 (старый)
Для OpenHab совместимости	Используется конец топика	0-100
Для новых систем	-	0-255

Практика:

• /set используется для установки значения (яркость 0-255)
• /cmd используется для команд (ON, OFF, TOGGLE)

---

HTTP API

Базовый URL

http://<controller_ip>/item/<item_name>[/subitem][/suffix]

Методы

Метод	Действие
GET	Прочитать статус item
POST	Выполнить команду или установить значение

Примеры HTTP запросов

# Включить лампу
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"

# Установить цвет RGB
curl -X POST http://192.168.1.10/item/rgb_light/rgb -d "255,0,0"

# Получить текущий статус
curl -X GET http://192.168.1.10/item/lamp1/val

# Многозональная вентиляция - установить T в спальне
curl -X POST http://192.168.1.10/item/multivent/bedroom/set -d "22"

# Кондиционер - установить режим
curl -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 команду
/	GET	Переадресация на PWA приложение

---

MQTT подписки контроллера

Контроллер автоматически подписывается на:

1. Командные широковещательные: root/bcst/#
2. Командные индивидуальные: root/id-устройства/#
3. Статусные (при старте на 5 сек): root/out/#
4. Служебные: root/id-устройства/$command

---

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

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

{
  "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/val: 100 (восстановленная яркость)
← myhome/s_out/lamp_bedroom/cmd: ON

# Установить яркость RGB
→ myhome/in/rgb_light/set: 200
← myhome/s_out/rgb_light/val: 200

# Установить цвет
→ myhome/in/rgb_light/hue: 240
← myhome/s_out/rgb_light/hue: 240

# Включить кондиционер в режим HEAT
→ myhome/in/ac_main/cmd: ON
← myhome/s_out/ac_main/cmd: ON
→ myhome/in/ac_main/mode: HEAT
← myhome/s_out/ac_main/mode: 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.0 (актуально для работа_с_mqtt из wiki.lazyhome.ru)
Источники: MQTT wiki, API wiki