andry/lighthub

Fork 0

mirror of https://github.com/anklimov/lighthub synced 2026-10-28 11:15:00 +00:00

Files

T

andry f787a16270 docs review

2026-10-11 01:27:15 +03:00

20 KiB

Raw Blame History

Справочник суффиксов LightHub

Инженерный справочник всех суффиксов MQTT топиков для управления каналами LightHub. Источник: wiki.lazyhome.ru — работа с 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`	—

Структура многозональной вентиляции:

{
  "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 лампой

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

"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: Система управления кондиционером

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

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

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

"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: Многозональная вентиляция

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

"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 интеграция

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

20 KiB Raw Blame History Unescape Escape

Справочник суффиксов LightHub

Что такое суффикс?

Анатомия полного топика

Категории суффиксов

1️⃣ Основные суффиксы (для всех типов каналов)

2️⃣ Цветовые суффиксы (RGB/RGBW/RGBWW)

3️⃣ Суффиксы кондиционера (AC)

4️⃣ Суффиксы воздушного отопления (Multivent)

5️⃣ Суффиксы термостата (PID контроллер)

6️⃣ Суффиксы для импульсных каналов и ШИМ

7️⃣ Суффиксы для управления состоянием

Таблица применимости суффиксов по типам каналов

По типам из конфигурации

Примеры сценариев

Сценарий 1: Управление RGB лампой

Сценарий 2: Система управления кондиционером

Сценарий 3: Управление теплыми полами (PID)

Сценарий 4: Многозональная вентиляция

Диапазоны значений и конвертация

Различие между /cmd и /set

Шкалы значений

Специальные диапазоны

Связь между суффиксами

Синергия RGB суффиксов

Синергия AC суффиксов

Видео-примеры и интеграции

Home Assistant интеграция

Иных систем управления

20 KiB

Raw Blame History