lighthub/documentation/suffixes_reference_v2.md

# Справочник суффиксов 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 (OpenHab) |
| `/val` | ❌ | ✅ | Текущее значение (только выход) | 0-255 |
| `/del` | ✅ | ❌ | Команда с задержкой | Текст (команда + время) |

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

| Суффикс | Вход | Выход | Назначение | Диапазон |
|---------|:----:|:-----:|-----------|----------|
| `/hue` | ✅ | ✅ | Оттенок (HSV) | 0-365° |
| `/sat` | ✅ | ✅ | Насыщенность (HSV) | 0-100% |
| `/hsv` | ✅ | ✅ | Полный цвет (hue,sat,val) | `H,S,V` |
| `/rgb` | ✅ | ✅ | Цвет в RGB/RGBW нотации | `R,G,B` или `R,G,B,W` |

**Примеры**:
```
# Установить красный цвет (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

# Установить RGB красный
myhome/in/rgb_light/rgb → 255,0,0

# Установить RGBW
myhome/in/rgb_light/rgb → 255,0,0,100
```

**Особенности HSV**:
- `0°` — красный
- `60°` — желтый
- `120°` — зеленый
- `180°` — голубой
- `240°` — синий
- `300°` — магента

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

| Суффикс | Вход | Выход | Назначение | Значения |
|---------|:----:|:-----:|-----------|----------|
| `/cmd` | ✅ | ✅ | Включить/выключить кондиционер | ON, OFF, TOGGLE |
| `/mode` | ✅ | ✅ | Режим работы | HEAT, COOL, AUTO, DRY, FAN_ONLY |
| `/set` | ✅ | ✅ | Установленная температура | 16-30 (или диапазон устройства) |
| `/fan` | ✅ | ✅ | Скорость вентилятора | HIGH, MED, LOW, AUTO |
| `/lock` | ✅ | ✅ | Блокировка ПДУ | ON, OFF |
| `/swing` | ✅ | ✅ | Направление воздушного потока | ON, OFF |
| `/quiet` | ✅ | ✅ | Режим "тихой работы" | ON, OFF |

**Примеры**:
```
# Включить кондиционер
myhome/in/ac_main/cmd → ON

# Установить режим нагрева
myhome/in/ac_main/mode → HEAT

# Установить температуру 22°C
myhome/in/ac_main/set → 22

# Максимальная скорость вентилятора
myhome/in/ac_main/fan → HIGH

# Включить тихий режим
myhome/in/ac_main/quiet → ON
```

**Логика срабатывания AC**:
- При получении команды на `/cmd` кондиционер сохраняет **последний режим, температуру и скорость вентилятора**
- При выключении (`OFF`) эти значения **восстанавливаются** при включении (`ON`)

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

| Суффикс | Вход | Выход | Назначение | Диапазон |
|---------|:----:|:-----:|-----------|----------|
| `/cmd` | ✅ | ✅ | Включить/выключить | ON, OFF, TOGGLE |
| `/set` | ✅ | ✅ | Установленная температура | Текущее значение |
| `/fan` | ✅ | ✅ | Скорость вентилятора | HIGH, MED, LOW |
| `/mode` | ✅ | ✅ | Режим работы | HEAT, AUTO, COOL |

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

```json
{
  "items": {
    "multivent": [
      17,
      {
        "bedroom": {"set": "multivent/bedroom/set"},
        "kitchen": {"set": "multivent/kitchen/set"},
        "bathroom": {"set": "multivent/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, OFF |

**Примеры**:
```
# Включить теплые полы
myhome/in/floor/cmd → ON

# Установить температуру 25°C
myhome/in/floor/set → 25

# Включить автоматический режим
myhome/in/floor/mode → 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 |
| Условный 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** | `/cmd`, `/set`, `/val` | Лампа, светодиод |
| **1 — CH_RELAY** | `/cmd`, `/set`, `/val`, `/del` | Реле, розетка |
| **2 — CH_TRIGGER** | `/cmd`, `/del` | Кнопка, импульс |
| **10 — CH_RGB** | `/cmd`, `/set`, `/hue`, `/sat`, `/hsv`, `/rgb` | RGB лента, LED |
| **11 — CH_RGBW** | `/cmd`, `/set`, `/hue`, `/sat`, `/hsv`, `/rgb` | RGBW люстра |
| **12 — CH_RGBWW** | `/cmd`, `/set`, `/hue`, `/sat`, `/hsv`, `/rgb` | Теплый+холодный RGB |
| **13 — CH_AC** | `/cmd`, `/set`, `/mode`, `/fan`, `/lock`, `/swing`, `/quiet` | Кондиционер |
| **15 — CH_PID** | `/cmd`, `/set`, `/ctrl`, `/mode` | PID регулятор, теплые полы |
| **17 — CH_MULTIVENT** | `/cmd`, `/set`, `/fan`, `/mode` + subitem-ы | Многозональная вентиляция |
| **2 — CH_GPIO** | `/cmd`, `/set` | GPIO контроль |
| **3 — CH_PWM** | `/cmd`, `/set`, `/val` | PWM вывод |

---

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

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

**Конфигурация**:
```json
"items": {
  "rgb_lamp": [10, 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": [13, {
    "mode": {"emit": "ac/mode"},
    "temp": {"emit": "ac/temp"}
  }]
}
```

**Команды**:
```
# Включить, установить HEAT, 22°C, вентилятор на максимум
myhome/in/ac_hallway/cmd → ON
myhome/in/ac_hallway/mode → 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 → ON
myhome/s_out/ac_hallway/mode → HEAT
myhome/s_out/ac_hallway/set → 22
myhome/s_out/ac_hallway/fan → HIGH
```

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

**Конфигурация**:
```json
"items": {
  "floor_heating": [15, 4]
}
```

**Команды**:
```
# Включить отопление
myhome/in/floor_heating/cmd → ON

# Установить температуру 24°C
myhome/in/floor_heating/set → 24

# Установить режим AUTO (включить, если T < установленной)
myhome/in/floor_heating/mode → AUTO

# Заморозить (не менять значение)
myhome/in/floor_heating/ctrl → FREEZE

# Разморозить
myhome/in/floor_heating/ctrl → UNFREEZE
```

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

**Конфигурация**:
```json
"items": {
  "multivent": [17, {
    "bedroom": {"set": "multivent/bedroom/set"},
    "kitchen": {"set": "multivent/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

# Ответы
myhome/s_out/multivent/bedroom/val → 21.5
myhome/s_out/multivent/kitchen/val → 20.2
```

---

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

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

| Параметр | /cmd | /set |
|----------|------|------|
| **Тип данных** | Текст (команда) | Число (значение) |
| **Диапазон (новый)** | Команды | 0-255 |
| **Диапазон (OpenHab)** | Команды | 0-100 |
| **Примеры** | ON, OFF, TOGGLE | 128, 255 |
| **Когда использовать** | Нужна команда (ON/OFF) | Нужно установить значение |

### Автоматическая нормализация

Контроллер автоматически конвертирует:

```
/set → 0-100 → 0-255 при отправке на устройство
/set → 0-255 → 0-100 при отправке в OpenHab совместимость
```

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

| Суффикс | Диапазон | Особенность |
|---------|----------|-----------|
| `/set` | 0-255 или 0-100 | Зависит от конфигурации |
| `/hue` | 0-365 | Градусы в цветовом круге (0=красный) |
| `/sat` | 0-100 | Проценты (0=белый, 100=полная насыщенность) |
| `/fan` | HIGH, MED, LOW | Текстовые значения |
| `/mode` | HEAT, COOL, AUTO... | Текстовые команды |

---

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

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

```
Команда          Результат
────────────────────────────────────────
/cmd → ON        Включить, восстановить последний цвет
/cmd → OFF       Выключить
/hue → 240       Поменять оттенок на синий
/sat → 50        Поменять насыщенность
/hsv → 240,100,255  Установить полный цвет (синий максимум)
/rgb → 0,0,255   Установить синий RGB
```

**Публикуемые значения**:
```
myhome/s_out/rgb_lamp/hue → 240
myhome/s_out/rgb_lamp/sat → 100
myhome/s_out/rgb_lamp/val → 255
myhome/s_out/rgb_lamp/cmd → ON
```

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

```
Команда                    Состояние
────────────────────────────────────────
/cmd → ON                  Включить (восстановить режим/T)
/mode → HEAT               Установить режим нагрева
/set → 22                  Установить 22°C
/fan → HIGH                Максимальная скорость вентилятора
/lock → ON                 Заблокировать ПДУ (только кондиционер)
/swing → ON                Включить направление воздуха
/quiet → ON                Тихий режим
```

---

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

### 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/val"
    hs_command_topic: "myhome/in/rgb_lamp/hsv"
    hs_state_topic: "myhome/s_out/rgb_lamp/hsv"
    payload_on: "ON"
    payload_off: "OFF"
```

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

Большинство MQTT систем (OpenHAB, Home Assistant, Node-Red и др.) поддерживают:
- `/cmd` — переключатели (ON/OFF)
- `/set` — диммеры (0-100 или 0-255)
- `/val` — датчики (показания)
- Цветовые суффиксы `/hue`, `/sat`

---

**Версия документа**: 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