# Справочник суффиксов 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