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

Files

T

andry 9a1c5eb143 fix(ac): rename quiet subitem 'queit' to 'quiet', keep legacy alias

The input subitem for the AC quiet mode was misspelled 'queit'. The code
now uses 'quiet' and still accepts 'queit' for backward compatibility;
docs updated accordingly. Removing the alias is tracked in BACKLOG.md.

2026-10-03 00:41:36 +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