mirror of
https://github.com/anklimov/lighthub
synced 2026-03-14 05:16:31 +03:00
372 lines
13 KiB
Markdown
372 lines
13 KiB
Markdown
# LightHub: Справочник суффиксов и параметров
|
||
|
||
> **Инженерный справочник** суффиксов для обращения к различным параметрам каналов в MQTT и при программном управлении.
|
||
> Актуально для версии ядра. Источник: [lighthub/item.h](../lighthub/item.h)
|
||
|
||
---
|
||
|
||
## Таблица суффиксов
|
||
|
||
| Код | Суффикс | Назв. констаны | Описание | Применяемость | Пример |
|
||
|-----|---------|---|---------|---------|---------|
|
||
| **0** | (не используется) | `S_NOTFOUND` | Суффикс не найден или корневой параметр | - | `channel_name` |
|
||
| **1** | `/cmd` | `S_CMD` | Команда управления (ON, OFF, SET и др.) | Все типы каналов | `lamp/cmd` → ON |
|
||
| **2** | `/set` | `S_SET` | Установка значения для регулирующих каналов | Регулирующие (DMX, PWM, PID) | `dimmer/set` → 150 |
|
||
| **3** | `/val` | `S_VAL` | Текущее значение (статус канала) | Все типы каналов | `dimmer/val` → 100 |
|
||
| **4** | `/del` | `S_DELAYED` | Отложенная команда (выполнится позже) | Логирование | `lamp/del` |
|
||
| **5** | `/HSV` | `S_HSV` | Цвет в формате HSV (Hue, Saturation, Value) | RGB/RGBW/RGBWW каналы | `lamp/HSV` → 120,255,200 |
|
||
| **6** | `/RGB` | `S_RGB` | Цвет в формате RGB (Red, Green, Blue) | RGB/RGBW/RGBWW каналы | `lamp/RGB` → 255,128,0 |
|
||
| **7** | `/fan` | `S_FAN` | Скорость вентилятора | Multivent, Vacom, AC | `ac/fan` → 2 |
|
||
| **8** | `/mode` | `S_MODE` | Режим работы | AC, Multivent, регуляторы | `ac/mode` → HEAT |
|
||
| **9** | `/ctrl` | `S_CTRL` | Управление (дублирует функцию /cmd) | Специальные случаи | `channel/ctrl` |
|
||
| **10** | `/hue` | `S_HUE` | Оттенок (Hue, 0-359°) | RGB/RGBW/RGBWW каналы | `lamp/hue` → 240 |
|
||
| **11** | `/sat` | `S_SAT` | Насыщенность (Saturation, 0-100%) | RGB/RGBW/RGBWW каналы | `lamp/sat` → 80 |
|
||
| **12** | `/temp` | `S_TEMP` | Температура цвета (Color Temp, K) | RGB/RGBW/RGBWW каналы | `lamp/temp` → 6500 |
|
||
| **13** | `/raw` | `S_RAW` | Сырые данные (itemCmd в JSON формате) | Отладка, интеграция | `channel/raw` → {...} |
|
||
|
||
---
|
||
|
||
## Примеры использования по типам каналов
|
||
|
||
### Реле (CH_RELAY - 6)
|
||
|
||
```
|
||
myhome/dev/relay1/cmd ← ON / OFF / TOGGLE
|
||
myhome/dev/relay1/val ← 0 или 1 (текущее состояние)
|
||
myhome/dev/relay1/set ← 1 (включить) / 0 (выключить)
|
||
```
|
||
|
||
### DMX/PWM диммер (CH_DIMMER - 0, CH_PWM - 3)
|
||
|
||
```
|
||
myhome/dev/dimmer/cmd ← ON, OFF, SET
|
||
myhome/dev/dimmer/val ← 0-255 (текущая яркость)
|
||
myhome/dev/dimmer/set ← 100 (установить яркость 100/255)
|
||
myhome/dev/dimmer/set ← 50% (установить яркость 50%)
|
||
myhome/dev/dimmer/set ← UP / DOWN
|
||
```
|
||
|
||
### RGB светильник (CH_RGB - 2, CH_RGBW - 1, CH_RGBWW - 17)
|
||
|
||
```
|
||
# Управление цветом (HSV формат)
|
||
myhome/dev/rgb_lamp/hue ← 240 (0-359°, синий)
|
||
myhome/dev/rgb_lamp/sat ← 100 (0-100%, насыщенность)
|
||
myhome/dev/rgb_lamp/val ← 200 (0-255, яркость)
|
||
|
||
# Управление цветом (RGB формат)
|
||
myhome/dev/rgb_lamp/RGB ← 255,0,0 (красный)
|
||
myhome/dev/rgb_lamp/RGB ← 0,255,0 (зелёный)
|
||
myhome/dev/rgb_lamp/RGB ← 0,0,255 (синий)
|
||
|
||
# RGBW (с белым каналом)
|
||
myhome/dev/rgbw_lamp/RGB ← 255,128,0,100 (RGB + White)
|
||
|
||
# RGBWW (RGB + тёплый + холодный белый)
|
||
myhome/dev/rgbww_lamp/RGB ← 255,128,0,200,50 (RGB + Warm + Cold)
|
||
|
||
# Температура цвета
|
||
myhome/dev/rgb_lamp/temp ← 3000 (тёплый, 3000K)
|
||
myhome/dev/rgb_lamp/temp ← 6500 (дневной, 6500K)
|
||
```
|
||
|
||
### Термостат (CH_THERMO - 5)
|
||
|
||
```
|
||
myhome/dev/thermo_bath/cmd ← ON / OFF
|
||
myhome/dev/thermo_bath/val ← 1 или 0 (статус нагрева)
|
||
myhome/dev/thermo_bath/set ← 25 (установить целевую температуру)
|
||
```
|
||
|
||
### Группа каналов (CH_GROUP - 7)
|
||
|
||
```
|
||
myhome/dev/lights_all/cmd ← ON (включит ВСЕ люстры в группе)
|
||
myhome/dev/lights_all/cmd ← OFF (выключит ВСЕ люстры в группе)
|
||
myhome/dev/lights_all/cmd ← TOGGLE (переключит ВСЕ)
|
||
```
|
||
|
||
### PID регулятор (CH_PID - 13)
|
||
|
||
```
|
||
myhome/dev/pid_heat/cmd ← ON / OFF / SET
|
||
myhome/dev/pid_heat/val ← текущее значение выхода (0-255)
|
||
myhome/dev/pid_heat/set ← требуемое значение процесса
|
||
```
|
||
|
||
### Кондиционер Haier (CH_AC - 10)
|
||
|
||
```
|
||
myhome/dev/ac/cmd ← ON / OFF
|
||
myhome/dev/ac/mode ← COOL / HEAT / FAN / DRY / AUTO
|
||
myhome/dev/ac/fan ← 0, 1, 2, 3 (скорость вентилятора)
|
||
myhome/dev/ac/val ← текущая температура (в помещении)
|
||
myhome/dev/ac/set ← 22 (установить целевую T)
|
||
```
|
||
|
||
### Многозональная вентиляция (CH_MULTIVENT - 18)
|
||
|
||
```
|
||
# Основной контроллер
|
||
myhome/dev/vents/cmd ← ON / OFF
|
||
myhome/dev/vents/val ← текущая T (комната)
|
||
myhome/dev/vents/mode ← режим
|
||
|
||
# Для зоны "спальня" (через subitems)
|
||
myhome/dev/vents/bedroom/cmd ← управление зоной
|
||
myhome/dev/vents/bedroom/val ← T в спальне
|
||
myhome/dev/vents/bedroom/fan ← открытие жалюзи спальни
|
||
myhome/dev/vents/bedroom/set ← уставка T в спальне
|
||
```
|
||
|
||
### Счётчик импульсов (CH_COUNTER - 20)
|
||
|
||
```
|
||
myhome/dev/energy_meter/val ← текущее значение (кВт·ч)
|
||
myhome/dev/gas_meter/val ← текущее значение (м³)
|
||
```
|
||
|
||
---
|
||
|
||
## Специальные команды управления
|
||
|
||
### Основные команды (работают с большинством каналов)
|
||
|
||
| Команда | Код | Описание |
|
||
|---------|-----|---------|
|
||
| `ON` | 1 | Включить |
|
||
| `OFF` | 0 | Выключить |
|
||
| `TOGGLE` | 2 | Переключить состояние |
|
||
| `SET` | 4 | Установить значение |
|
||
|
||
### Команды изменения значения
|
||
|
||
| Команда | Описание |
|
||
|---------|---------|
|
||
| `UP` | Увеличить на 1 |
|
||
| `DOWN` | Уменьшить на 1 |
|
||
| `INCREASE` | Плавно увеличить |
|
||
| `DECREASE` | Плавно уменьшить |
|
||
|
||
### Команды расписания
|
||
|
||
| Команда | Описание |
|
||
|---------|---------|
|
||
| `FREEZE` | Заморозить текущее состояние |
|
||
| `UNFREEZE` | Разморозить |
|
||
| `HALT` | Остановить (аварийная остановка) |
|
||
| `RESTORE` | Восстановить последнее состояние |
|
||
|
||
---
|
||
|
||
## Форматирование значений в MQTT
|
||
|
||
### Числовые значения
|
||
|
||
```
|
||
myhome/dev/dimmer/set ← 150 # абсолютное значение (0-255)
|
||
myhome/dev/dimmer/set ← 50% # процент
|
||
myhome/dev/dimmer/set ← UP 10 # с модификатором
|
||
```
|
||
|
||
### Цветовые значения
|
||
|
||
```
|
||
# RGB
|
||
myhome/dev/lamp/RGB ← 255,0,0 # красный
|
||
myhome/dev/lamp/RGB ← #FF0000 # красный (hex)
|
||
|
||
# HSV
|
||
myhome/dev/lamp/HSV ← 0,100,100 # красный (полная насыщенность)
|
||
myhome/dev/lamp/HSV ← 120,100,100 # зелёный
|
||
myhome/dev/lamp/HSV ← 240,100,100 # синий
|
||
```
|
||
|
||
### Текстовые команды
|
||
|
||
```
|
||
myhome/dev/relay/cmd ← ON
|
||
myhome/dev/relay/cmd ← OFF
|
||
myhome/dev/relay/cmd ← TOGGLE
|
||
myhome/dev/ac/mode ← HEAT
|
||
myhome/dev/ac/mode ← COOL
|
||
```
|
||
|
||
---
|
||
|
||
## JSON формат (subitems)
|
||
|
||
Для каналов с подпараметрами используется специальный JSON формат:
|
||
|
||
```json
|
||
{
|
||
"item": "multizone_ac/bedroom",
|
||
"cmd": "SET",
|
||
"val": 22,
|
||
"suffix": "set"
|
||
}
|
||
```
|
||
|
||
Или через MQTT топик:
|
||
|
||
```
|
||
myhome/dev/multizone_ac/bedroom/set ← 22
|
||
```
|
||
|
||
---
|
||
|
||
## Приоритет суффиксов
|
||
|
||
При обработке команды LightHub проверяет суффиксы в следующем порядке:
|
||
|
||
1. Явный суффикс в команде (`/cmd`, `/val`, `/set`, etc.)
|
||
2. Суффикс по умолчанию для типа канала
|
||
3. Корневой параметр (если суффиксов нет)
|
||
|
||
**Пример**:
|
||
```
|
||
# Команда с явным суффиксом имеет приоритет
|
||
myhome/dev/lamp/cmd ← ON # выполнится как команда ON
|
||
|
||
# Без суффикса используется суффикс по умолчанию
|
||
myhome/dev/lamp ← ON # может интерпретироваться как SET
|
||
```
|
||
|
||
---
|
||
|
||
## Статус канала (ответ контроллера)
|
||
|
||
Контроллер публикует текущий статус в топик:
|
||
|
||
```
|
||
myhome/s_out/<item_name>/<suffix>
|
||
```
|
||
|
||
Пример:
|
||
```
|
||
myhome/s_out/lamp1/val # яркость лампы 1
|
||
myhome/s_out/lamp1/cmd # последняя выполненная команда
|
||
myhome/s_out/rgb_lamp/hue # текущий оттенок
|
||
myhome/s_out/rgb_lamp/sat # текущая насыщенность
|
||
myhome/s_out/ac/mode # текущий режим кондиционера
|
||
```
|
||
|
||
---
|
||
|
||
## Особенности отдельных типов
|
||
|
||
### RGB каналы с коррекцией белого (RGBWW)
|
||
|
||
**RGBWW формат**: `R,G,B,WarmWhite,ColdWhite`
|
||
|
||
```
|
||
# Пример: розовый свет (красный + тёплый белый)
|
||
myhome/dev/led/RGB ← 255,0,0,100,0
|
||
|
||
# Нейтральный белый (комбинация тёплого и холодного)
|
||
myhome/dev/led/RGB ← 0,0,0,128,128
|
||
|
||
# Холодный белый
|
||
myhome/dev/led/RGB ← 0,0,0,0,255
|
||
```
|
||
|
||
### Multivent суффиксы для отдельных зон
|
||
|
||
Для зон используются дополнительные параметры:
|
||
|
||
```
|
||
myhome/dev/multivent/bedroom/fan ← 50 # открытие жалюзи
|
||
myhome/dev/multivent/bedroom/mode ← HEAT # режим нагрева
|
||
myhome/dev/multivent/bedroom/set ← 23 # уставка температуры
|
||
myhome/dev/multivent/bedroom/val ← текущая T в спальне
|
||
```
|
||
|
||
---
|
||
|
||
## Отладка через /raw суффикс
|
||
|
||
Для отладки и развёрнутого логирования можно использовать суффикс `/raw`:
|
||
|
||
```
|
||
myhome/dev/lamp/raw ← получить полное описание состояния в JSON
|
||
```
|
||
|
||
Ответ:
|
||
```json
|
||
{
|
||
"cmd": 1,
|
||
"val": 150,
|
||
"type": 0,
|
||
"arg": [1],
|
||
"suffix": 0
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Таблица соответствия суффиксов и типов каналов
|
||
|
||
| Тип | /cmd | /val | /set | /hue | /sat | /temp | /fan | /mode |
|
||
|-----|:----:|:----:|:----:|:----:|:----:|:-----:|:----:|:-----:|
|
||
| RELAY (6) | ✓ | ✓ | - | - | - | - | - | - |
|
||
| DMX (0) | ✓ | ✓ | ✓ | - | - | - | - | - |
|
||
| PWM (3) | ✓ | ✓ | ✓ | - | - | - | - | - |
|
||
| RGB (2) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - |
|
||
| RGBW (1) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - |
|
||
| RGBWW (17) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - |
|
||
| THERMO (5) | ✓ | ✓ | ✓ | - | - | - | - | - |
|
||
| PID (13) | ✓ | ✓ | ✓ | - | - | - | - | - |
|
||
| AC (10) | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓ |
|
||
| MULTIVENT (18) | ✓ | ✓ | ✓ | - | - | - | ✓ | ✓ |
|
||
| GROUP (7) | ✓ | ✓ | - | - | - | - | - | - |
|
||
| COUNTER (20) | - | ✓ | - | - | - | - | - | - |
|
||
| MOTOR (12) | ✓ | ✓ | ✓ | - | - | - | - | - |
|
||
|
||
---
|
||
|
||
## Примеры реальных MQTT команд
|
||
|
||
### Включение всех светильников в комнате
|
||
|
||
```
|
||
myhome/dev/lights_hall/cmd ON
|
||
```
|
||
|
||
### Установка яркости на 50%
|
||
|
||
```
|
||
myhome/dev/dimmer1/set 128
|
||
```
|
||
|
||
### Установка цвета RGB лампы на синий с 80% яркостью
|
||
|
||
```
|
||
myhome/dev/lamp_rgb/hue 240
|
||
myhome/dev/lamp_rgb/sat 100
|
||
myhome/dev/lamp_rgb/val 200
|
||
```
|
||
|
||
### Включение кондиционера в режим охлаждения при 22°C
|
||
|
||
```
|
||
myhome/dev/ac/cmd ON
|
||
myhome/dev/ac/mode COOL
|
||
myhome/dev/ac/set 22
|
||
```
|
||
|
||
### Нагрев в спальне многозональной системы до 23°C
|
||
|
||
```
|
||
myhome/dev/multivent/bedroom/set 23
|
||
myhome/dev/multivent/bedroom/mode HEAT
|
||
```
|
||
|
||
---
|
||
|
||
## Полезные ссылки
|
||
|
||
- [Справочник типов каналов](channel_types_reference.md)
|
||
- [Полное описание конфигурации](light_hub_полное_инженерное_описание_json_конфигурации.md)
|
||
- [Описание модулей](modules_description.md)
|
||
- [Исходный код item.h](../lighthub/item.h)
|