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

docs: audit references and examples against source code

Browse Source 
Cross-checked all channel types, suffixes, commands, JSON config formats,
HTTP/MQTT API examples and driver docs with the actual code; fixed the
discrepancies (channel numbers 0..23, real command set, real suffix handling,
CAN 50 kbit/s, DRY/Freeze sprinkler semantics, AC subitems, multivent zones,
Mercury/Motor/Counter configs, etc.)
This commit is contained in:
andry
2026-10-03 00:41:16 +03:00
parent 6a10d85c55
commit b90325bfef
12 changed files with 7567 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/core/mqtt_api_reference.md
+475
View File
@@ -0,0 +1,475 @@
# LightHub: Справочник MQTT API и топиков
> **Инженерный справочник** структуры MQTT топиков и HTTP API контроллера LightHub.
> Источник: [wiki.lazyhome.ru - работа с MQTT](https://www.lazyhome.ru/dokuwiki/doku.php?id=%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0_%D1%81_mqtt) и [api](https://www.lazyhome.ru/dokuwiki/doku.php?id=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` конфигурации.
```json
"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
### Базовая конфигурация
```json
{
"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 запросов
```bash
# Включить лампу
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-устройства/#` (отдельной подписки нет)
---
## Пример полной интеграции
### Конфигурация
```json
{
"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
### Проверка связи
```bash
# Подписаться на все топики контроллера
mosquitto_sub -h 192.168.1.100 -t "myhome/#" -v
# Отправить команду
mosquitto_pub -h 192.168.1.100 -t "myhome/in/lamp1/cmd" -m "ON"
```
### Проверка статусных топиков
```bash
# Только статусные топики
mosquitto_sub -h 192.168.1.100 -t "myhome/s_out/#" -v
```
---
**Версия документа**: 2.1 (актуально для работа_с_mqtt из wiki.lazyhome.ru)
**Источники**: [MQTT wiki](https://www.lazyhome.ru/dokuwiki/doku.php?id=%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0_%D1%81_mqtt), [API wiki](https://www.lazyhome.ru/dokuwiki/doku.php?id=api)