mirror of
https://github.com/anklimov/lighthub
synced 2026-10-28 11:15:00 +00:00
476 lines
20 KiB
Markdown
476 lines
20 KiB
Markdown
# Справочник суффиксов LightHub
|
||
|
||
> **Инженерный справочник** всех суффиксов MQTT топиков для управления каналами 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)
|
||
|
||
---
|
||
|
||
## Что такое суффикс?
|
||
|
||
**Суффикс** — это завершающая часть MQTT топика, которая определяет **какое** свойство объекта меняется.
|
||
|
||
### Анатомия полного топика
|
||
|
||
```
|
||
myhome/in/lamp_bedroom/set
|
||
└─────┘ └─┘ └───────────┘ └──┘
|
||
root bcst item_name suffix
|
||
```
|
||
|
||
---
|
||
|
||
## Категории суффиксов
|
||
|
||
### 1️⃣ Основные суффиксы (для всех типов каналов)
|
||
|
||
| Суффикс | Вход | Выход | Назначение | Диапазон |
|
||
|---------|:----:|:-----:|-----------|----------|
|
||
| `/cmd` | ✅ | ✅ | Команда управления (ON, OFF, TOGGLE) | Текст (команда) |
|
||
| `/set` | ✅ | ✅ | Установка численного значения | 0-255 (шкала 0-100 — только в общем топике без суффикса) |
|
||
| `/val` | ✅ | ❌ | Вход сенсора (THERMO, PID, MULTIVENT, SPRINKLER) | Число (T / значение) |
|
||
| `/raw` | ✅ | ✅ | «Сырые» данные, передаваемые драйверу без интерпретации | Текст / число |
|
||
| `/del` | ✅ | ❌ | Команда с задержкой. Только команды ON…FAN\_ONLY (код ≤ 0x0F); HIGH/MEDIUM/LOW/HEAT\_COOL/HEAT/COOL/DRY запланировать нельзя | Текст (команда + время) |
|
||
|
||
> **Полный список команд** (payload `/cmd`): `ON`, `OFF`, `REST`, `TOGGLE`, `HALT`, `XON`, `XOFF`, `INCREASE`, `DECREASE`, `ENABLE`, `DISABLE`, `UNFREEZE`, `FREEZE`, `AUTO`, `FAN_ONLY`, `HIGH`, `MEDIUM`, `LOW`, `HEAT_COOL`, `HEAT`, `COOL`, `DRY`, `RGB`, `HSV`, `RESET`.
|
||
> `TOGGLE` в `/ctrl` не включает/выключает, а **инвертирует флаг DISABLE**.
|
||
|
||
### 2️⃣ Цветовые суффиксы (RGB/RGBW/RGBWW)
|
||
|
||
| Суффикс | Вход | Выход | Назначение | Диапазон |
|
||
|---------|:----:|:-----:|-----------|----------|
|
||
| `/hue` | ✅ | ✅ | Оттенок (HSV) | 0-365° |
|
||
| `/sat` | ✅ | ✅ | Насыщенность (HSV) | 0-100% |
|
||
| `/HSV` | ✅ | ✅ | Полный цвет (hue,sat,val). Суффикс ЗАГЛАВНЫЙ, строчный `/hsv` игнорируется | `H,S,V` |
|
||
| `/rgb` | ❌ | ❌ | **Не поддерживается** в текущей сборке (S\_RGB нигде не обрабатывается) | — |
|
||
| `/temp` | ✅ | ✅ | Цветовая температура 153-500 mireds (RGBWW); у AC — текущая T | 153-500 |
|
||
|
||
**Примеры**:
|
||
```
|
||
# Установить красный цвет (hue=0)
|
||
myhome/in/rgb_light/hue → 0
|
||
|
||
# Установить насыщенность 50%
|
||
myhome/in/rgb_light/sat → 50
|
||
|
||
# Установить HSV 240,100,200 (синий максимум)
|
||
myhome/in/rgb_light/HSV → 240,100,200
|
||
|
||
# Тот же цвет строкой «h,s,v[,ct]» в общем топике (без суффикса)
|
||
myhome/in/rgb_light → 240,100,200
|
||
```
|
||
|
||
**Особенности HSV**:
|
||
- `0°` — красный
|
||
- `60°` — желтый
|
||
- `120°` — зеленый
|
||
- `180°` — голубой
|
||
- `240°` — синий
|
||
- `300°` — магента
|
||
|
||
### 3️⃣ Суффиксы кондиционера (AC)
|
||
|
||
| Суффикс | Вход | Выход | Назначение | Значения |
|
||
|---------|:----:|:-----:|-----------|----------|
|
||
| `/cmd` | ✅ | ✅ | Включить/выключить кондиционер | ON, OFF, TOGGLE |
|
||
| `/mode` | ✅ | ✅ | Режим работы — число 0-4 (текстовые режимы — payload в `/cmd`) | 0-4 |
|
||
| `/set` | ✅ | ✅ | Установленная температура | 16-40 (или диапазон устройства) |
|
||
| `/fan` | ✅ | ✅ | Скорость вентилятора | LOW, MEDIUM, HIGH, OFF или число |
|
||
| `/lock` | ✅ | ✅ | Блокировка ПДУ | ON, OFF |
|
||
| `/swing` | ✅ | ✅ | Направление воздушного потока | ON, OFF |
|
||
| `/quiet` | ✅ | ✅ | Режим "тихой работы". Входной subitem — `/quiet` (legacy «queit» принимается); статус публикуется в `/quiet` | ON, OFF |
|
||
|
||
**Примеры**:
|
||
```
|
||
# Включить кондиционер
|
||
myhome/in/ac_main/cmd → ON
|
||
|
||
# Установить режим нагрева (текстовые режимы — в /cmd)
|
||
myhome/in/ac_main/cmd → HEAT
|
||
|
||
# Установить температуру 22°C
|
||
myhome/in/ac_main/set → 22
|
||
|
||
# Максимальная скорость вентилятора
|
||
myhome/in/ac_main/fan → HIGH
|
||
|
||
# Включить тихий режим (legacy «queit» также принимается)
|
||
myhome/in/ac_main/quiet → ON
|
||
```
|
||
|
||
**Логика срабатывания AC**:
|
||
- При получении команды на `/cmd` кондиционер сохраняет **последний режим, температуру и скорость вентилятора**
|
||
- При выключении (`OFF`) эти значения **восстанавливаются** при включении (`ON`)
|
||
|
||
### 4️⃣ Суффиксы воздушного отопления (Multivent)
|
||
|
||
| Суффикс | Вход | Выход | Назначение | Диапазон |
|
||
|---------|:----:|:-----:|-----------|----------|
|
||
| `/cmd` | ✅ | ✅ | Включить/выключить | ON, OFF, TOGGLE |
|
||
| `/set` | ✅ | ✅ | Установленная температура | Текущее значение |
|
||
| `/fan` | ✅ | ✅ | Скорость вентилятора (HIGH/MEDIUM/LOW → 255/128/64) | HIGH, MEDIUM, LOW |
|
||
| `/mode` | ✅ | ❌ | Только у основного item (обратная связь от AC). У зон S\_MODE не обрабатывается — режим зоны задаётся командой в `zone/cmd` | — |
|
||
|
||
**Структура многозональной вентиляции**:
|
||
|
||
```json
|
||
{
|
||
"items": {
|
||
"multivent": [
|
||
18,
|
||
{
|
||
"bedroom": {"set": 21.0, "fan": 0, "cmd": 14, "item": "ac_bedroom/set"},
|
||
"kitchen": {"set": 22.0, "fan": 0, "cmd": 14, "item": "ac_kitchen/set"},
|
||
"bathroom": {"set": 21.0, "fan": 0, "cmd": 14, "item": "ac_bathroom/set"}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**MQTT топики для subitem-ов**:
|
||
```
|
||
# Спальня — установить T
|
||
myhome/in/multivent/bedroom/set → 21
|
||
|
||
# Кухня — установить T
|
||
myhome/in/multivent/kitchen/set → 22
|
||
|
||
# Ванная — включить вентилятор
|
||
myhome/in/multivent/bathroom/fan → HIGH
|
||
```
|
||
|
||
### 5️⃣ Суффиксы термостата (PID контроллер)
|
||
|
||
| Суффикс | Вход | Выход | Назначение | Диапазон |
|
||
|---------|:----:|:-----:|-----------|----------|
|
||
| `/cmd` | ✅ | ✅ | Включить/выключить регулировку | ON, OFF, TOGGLE |
|
||
| `/set` | ✅ | ✅ | Установленная температура | Температура в °C |
|
||
| `/ctrl` | ✅ | ✅ | Управление состоянием | ENABLE, DISABLE |
|
||
| `/mode` | ❌ | ❌ | Не поддерживается — режим (HEAT, AUTO) задаётся командой в `/cmd` | — |
|
||
|
||
**Примеры**:
|
||
```
|
||
# Включить теплые полы
|
||
myhome/in/floor/cmd → ON
|
||
|
||
# Установить температуру 25°C
|
||
myhome/in/floor/set → 25
|
||
|
||
# Включить автоматический режим (режим — команда в /cmd)
|
||
myhome/in/floor/cmd → AUTO
|
||
|
||
# Разрешить управление (если было запрещено)
|
||
myhome/in/floor/ctrl → ENABLE
|
||
```
|
||
|
||
**Состояние-зависимые команды**:
|
||
|
||
Для сложного сценария можно использовать **subitem** как условие — контроллер только выполнит команду, если item находится в этом состоянии.
|
||
|
||
```
|
||
# Включить режим HEAT только если установлен режим HEAT
|
||
myhome/in/floor/HEAT/cmd → ON
|
||
|
||
# Выключить режим OFF только если уже в режиме OFF
|
||
myhome/in/floor/OFF/cmd → OFF
|
||
```
|
||
|
||
### 6️⃣ Суффиксы для импульсных каналов и ШИМ
|
||
|
||
| Суффикс | Вход | Выход | Назначение | Диапазон |
|
||
|---------|:----:|:-----:|-----------|----------|
|
||
| `/cmd` | ✅ | ✅ | Включить/выключить (импульсный выход) | ON, OFF, TOGGLE |
|
||
| `/set` | ✅ | ✅ | Скважность ШИМ | 0-255 |
|
||
| `/del` | ✅ | ❌ | через какое время выполнить | `ON ВРЕМЯ_МС` |
|
||
|
||
**Примеры**:
|
||
```
|
||
# Импульс реле (включить на 3 сек, потом выключить)
|
||
myhome/in/gate/cmd → "ON 3000"
|
||
|
||
# ШИМ вентилятор 50%
|
||
myhome/in/fan/set → 128
|
||
|
||
# Активировать сирену через 5 сек
|
||
myhome/in/siren/del → "ON 5000"
|
||
```
|
||
|
||
### 7️⃣ Суффиксы для управления состоянием
|
||
|
||
| Суффикс | Использование | Назначение | Примеры |
|
||
|---------|--------------|-----------|---------|
|
||
| `/ctrl` | Все | Специальное управление состоянием | ENABLE, DISABLE, FREEZE, UNFREEZE, TOGGLE (инвертирует DISABLE) |
|
||
| Условный subitem | Строки состояния | Выполнить команду при условии | `/AUTO`, `/OFF`, `/ON`, `/HEAT`, `/COOL` |
|
||
|
||
**Примеры управления**:
|
||
```
|
||
# Заморозить (запретить изменения, но не выключать)
|
||
myhome/in/light/ctrl → FREEZE
|
||
|
||
# Разморозить
|
||
myhome/in/light/ctrl → UNFREEZE
|
||
|
||
# Выполнить включение только если в режиме OFF
|
||
myhome/in/device/OFF/cmd → ON
|
||
# (не выполнится, если device уже ON)
|
||
|
||
# Выполнить команду только в режиме HEAT (для AC)
|
||
myhome/in/ac/HEAT/set → 25
|
||
# (установит 25°C только если AC в режиме HEAT)
|
||
```
|
||
|
||
---
|
||
|
||
## Таблица применимости суффиксов по типам каналов
|
||
|
||
### По типам из конфигурации
|
||
|
||
| Номер | Тип канала | Суффиксы | Примеры |
|
||
|:-----:|-----------|----------|---------|
|
||
| 0 | CH\_DIMMER (DMX 1-4 ch) | `/cmd`, `/set` (subitem-адресация игнорируется) | Лампа, светодиод |
|
||
| 1 | CH\_RGBW (DMX 4 ch) | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV`, `/temp` | RGBW люстра |
|
||
| 2 | CH\_RGB (DMX 3 ch) | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV` | RGB лента, LED |
|
||
| 3 | CH\_PWM | `/cmd`, `/set` | PWM вывод |
|
||
| 4 | CH\_MODBUS | `/cmd`, `/set` | Modbus диммер |
|
||
| 5 | CH\_THERMO | `/cmd`, `/set`, `/val` (вход сенсора), `/ctrl` | Термостат |
|
||
| 6 | CH\_RELAY | `/cmd`, `/set`, `/del` | Реле, розетка |
|
||
| 7 | CH\_GROUP | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV` | Группа каналов |
|
||
| 8 | CH\_VCTEMP | — | Регулятор Vacon (PID) |
|
||
| 9 | CH\_VC | — | Привод Vacon (Modbus) |
|
||
| 10 | CH\_AC (Haier) | `/cmd`, `/set` (16-40), `/mode` (0-4), `/fan`, `/lock`, `/swing`, `/quiet` (legacy `queit`), `/temp`, `/raw` | Кондиционер |
|
||
| 11 | CH\_SPILED | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV` + subitem-пиксели 10-20 | Адресуемая LED лента |
|
||
| 12 | CH\_MOTOR | `/cmd`, `/set` | Сервопривод |
|
||
| 13 | CH\_PID | `/cmd`, `/set`, `/val` (вход сенсора), `/ctrl` | PID регулятор, теплые полы |
|
||
| 14 | CH\_MBUS | `/cmd`, `/set` | Modbus устройство |
|
||
| 15 | CH\_UARTBRIDGE | `/cmd`, `/set` | UART-мост |
|
||
| 16 | CH\_RELAYX | `/cmd`, `/set`, `/del` | Реле + ШИМ |
|
||
| 17 | CH\_RGBWW (DMXRGBWW) | `/cmd`, `/set`, `/hue`, `/sat`, `/HSV`, `/temp` | Теплый+холодный белый |
|
||
| 18 | CH\_MULTIVENT | `/cmd`, `/set`, `/fan` + zone-subitem-ы (`set`, `fan`, `cmd`) | Многозональная вентиляция |
|
||
| 19 | CH\_ELEVATOR | `/cmd`, `/set`, `/raw` | Лифт |
|
||
| 20 | CH\_COUNTER | `/cmd`, `/set` | Счетчик |
|
||
| 21 | CH\_HUMIDIFIER | `/cmd` | Увлажнитель |
|
||
| 22 | CH\_MERCURY | — | Счетчик электроэнергии |
|
||
| 23 | CH\_SPRINKLER | `/cmd`, `/set`, `/val` | Полив (ирригатор) |
|
||
|
||
---
|
||
|
||
## Примеры сценариев
|
||
|
||
### Сценарий 1: Управление RGB лампой
|
||
|
||
**Конфигурация**:
|
||
```json
|
||
"items": {
|
||
"rgb_lamp": [2, 1]
|
||
}
|
||
```
|
||
|
||
**Команды**:
|
||
```
|
||
# Включить белый (полная насыщенность)
|
||
myhome/in/rgb_lamp/sat → 0
|
||
|
||
# Установить красный цвет
|
||
myhome/in/rgb_lamp/hue → 0
|
||
|
||
# Установить желтый на 80% яркости
|
||
myhome/in/rgb_lamp/HSV → 60,100,200
|
||
|
||
# Выключить
|
||
myhome/in/rgb_lamp/cmd → OFF
|
||
```
|
||
|
||
### Сценарий 2: Система управления кондиционером
|
||
|
||
**Конфигурация**:
|
||
```json
|
||
"items": {
|
||
"ac_hallway": [10, 0]
|
||
}
|
||
```
|
||
(portNum = 0)
|
||
|
||
**Команды**:
|
||
```
|
||
# Включить, установить HEAT, 22°C, вентилятор на максимум
|
||
myhome/in/ac_hallway/cmd → ON
|
||
myhome/in/ac_hallway/cmd → HEAT
|
||
myhome/in/ac_hallway/set → 22
|
||
myhome/in/ac_hallway/fan → HIGH
|
||
|
||
# Выключить
|
||
myhome/in/ac_hallway/cmd → OFF
|
||
|
||
# Ответы от контроллера
|
||
myhome/s_out/ac_hallway/cmd → HEAT (текстовый режим публикуется в /cmd)
|
||
myhome/s_out/ac_hallway/mode → <0-4> (числовой режим)
|
||
myhome/s_out/ac_hallway/set → 22
|
||
myhome/s_out/ac_hallway/fan → HIGH
|
||
```
|
||
|
||
### Сценарий 3: Управление теплыми полами (PID)
|
||
|
||
**Конфигурация**:
|
||
```json
|
||
"items": {
|
||
"floor_heating": [13, [
|
||
[1.0, 0.05, 0.02, 5.0],
|
||
{"item": "heater/set"}
|
||
], 22]
|
||
}
|
||
```
|
||
(13 — CH\_PID; 2-й аргумент — массив `[kP,kI,kD,dT,…], {выходной execObj}, {каскад}]`; 3-й — стартовый setpoint 22°C)
|
||
|
||
**Команды**:
|
||
```
|
||
# Включить отопление
|
||
myhome/in/floor_heating/cmd → ON
|
||
|
||
# Установить температуру 24°C
|
||
myhome/in/floor_heating/set → 24
|
||
|
||
# Установить режим AUTO (включить, если T < установленной) — режим: команда в /cmd
|
||
myhome/in/floor_heating/cmd → AUTO
|
||
|
||
# Заморозить (не менять значение)
|
||
myhome/in/floor_heating/ctrl → FREEZE
|
||
|
||
# Разморозить
|
||
myhome/in/floor_heating/ctrl → UNFREEZE
|
||
```
|
||
|
||
### Сценарий 4: Многозональная вентиляция
|
||
|
||
**Конфигурация**:
|
||
```json
|
||
"items": {
|
||
"multivent": [18, {
|
||
"bedroom": {"set": 21.0, "fan": 0, "cmd": 14, "item": "ac_bedroom/set"},
|
||
"kitchen": {"set": 22.0, "fan": 0, "cmd": 14, "item": "ac_kitchen/set"}
|
||
}]
|
||
}
|
||
```
|
||
|
||
**Команды**:
|
||
```
|
||
# Спальня: установить 21°C
|
||
myhome/in/multivent/bedroom/set → 21
|
||
|
||
# Кухня: установить 20°C
|
||
myhome/in/multivent/kitchen/set → 20
|
||
|
||
# Оба: включить вентилятор на максимум
|
||
myhome/in/multivent/cmd → ON
|
||
myhome/in/multivent/fan → HIGH
|
||
|
||
# Ответы (статус зоны публикуется в суффикс ввода: /set, /fan, /cmd; периодического /val нет)
|
||
myhome/s_out/multivent/bedroom/set → 21.0
|
||
myhome/s_out/multivent/kitchen/set → 22.0
|
||
```
|
||
|
||
---
|
||
|
||
## Диапазоны значений и конвертация
|
||
|
||
### Различие между /cmd и /set
|
||
|
||
| Параметр | /cmd | /set |
|
||
|----------|------|------|
|
||
| **Тип данных** | Текст (команда) | Число (значение) |
|
||
| **Диапазон** | Команды | 0-255 |
|
||
| **Диапазон (общий топик, OpenHAB)** | Команды | 0-100 (только в общем топике без суффикса) |
|
||
| **Примеры** | ON, OFF, TOGGLE | 128, 255 |
|
||
| **Когда использовать** | Нужна команда (ON/OFF) | Нужно установить значение |
|
||
|
||
### Шкалы значений
|
||
|
||
- `/set` — всегда **0-255**
|
||
- Шкала **0-100** — только в **общем топике без суффикса** (`myhome/in/lamp1`) — совместимость с OpenHAB
|
||
|
||
### Специальные диапазоны
|
||
|
||
| Суффикс | Диапазон | Особенность |
|
||
|---------|----------|-----------|
|
||
| `/set` | 0-255 | 0-100 — только в общем топике без суффикса |
|
||
| `/hue` | 0-365 | Градусы в цветовом круге (0=красный) |
|
||
| `/sat` | 0-100 | Проценты (0=белый, 100=полная насыщенность) |
|
||
| `/fan` | LOW, MEDIUM, HIGH, OFF или число | Текстовые значения / число 0-255 |
|
||
| `/mode` | 0-4 (число) | Режимы-тексты — в /cmd |
|
||
|
||
---
|
||
|
||
## Связь между суффиксами
|
||
|
||
### Синергия RGB суффиксов
|
||
|
||
```
|
||
Команда Результат
|
||
────────────────────────────────────────
|
||
/cmd → ON Включить, восстановить последний цвет
|
||
/cmd → OFF Выключить
|
||
/hue → 240 Поменять оттенок на синий
|
||
/sat → 50 Поменять насыщенность
|
||
/HSV → 240,100,255 Установить полный цвет (синий максимум)
|
||
```
|
||
|
||
**Публикуемые значения** (статусных /hue, /sat, /val для ламп не существует):
|
||
```
|
||
myhome/s_out/rgb_lamp/set → 240,100,255 (строка «h,s,v[,ct]»)
|
||
myhome/s_out/rgb_lamp/cmd → ON
|
||
```
|
||
|
||
### Синергия AC суффиксов
|
||
|
||
```
|
||
Команда Состояние
|
||
────────────────────────────────────────
|
||
/cmd → ON Включить (восстановить режим/T)
|
||
/cmd → HEAT Установить режим нагрева (текстовые режимы — в /cmd)
|
||
/set → 22 Установить 22°C
|
||
/fan → HIGH Максимальная скорость вентилятора
|
||
/lock → ON Заблокировать ПДУ (только кондиционер)
|
||
/swing → ON Включить направление воздуха
|
||
/quiet → ON Тихий режим (legacy «queit» принимается; статус — /quiet)
|
||
```
|
||
|
||
---
|
||
|
||
## Видео-примеры и интеграции
|
||
|
||
### Home Assistant интеграция
|
||
|
||
```yaml
|
||
switch:
|
||
- platform: mqtt
|
||
name: "Лампа спальня"
|
||
command_topic: "myhome/in/lamp_bedroom/cmd"
|
||
state_topic: "myhome/s_out/lamp_bedroom/cmd"
|
||
payload_on: "ON"
|
||
payload_off: "OFF"
|
||
|
||
light:
|
||
- platform: mqtt
|
||
name: "RGB лампа"
|
||
command_topic: "myhome/in/rgb_lamp/cmd"
|
||
brightness_command_topic: "myhome/in/rgb_lamp/set"
|
||
brightness_state_topic: "myhome/s_out/rgb_lamp/set"
|
||
hs_command_topic: "myhome/in/rgb_lamp/HSV"
|
||
hs_state_topic: "myhome/s_out/rgb_lamp/set" # строка «h,s,v[,ct]»
|
||
payload_on: "ON"
|
||
payload_off: "OFF"
|
||
```
|
||
|
||
### Иных систем управления
|
||
|
||
Большинство MQTT систем (OpenHAB, Home Assistant, Node-Red и др.) поддерживают:
|
||
- `/cmd` — переключатели (ON/OFF)
|
||
- `/set` — диммеры (0-255; 0-100 — только в общем топике без суффикса)
|
||
- `/val` — вход сенсора (THERMO, PID, MULTIVENT, SPRINKLER)
|
||
- Цветовые суффиксы `/hue`, `/sat`, `/HSV`
|
||
|
||
---
|
||
|
||
**Версия документа**: 2.0 (обновлено для соответствия wiki.lazyhome.ru)
|
||
**Последнее обновление**: 2024
|
||
**Источник**: https://www.lazyhome.ru/dokuwiki/doku.php?id=%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0\_%D1%81\_mqtt
|