andry/lighthub
1
0
Fork 0
mirror of https://github.com/anklimov/lighthub synced 2026-03-14 05:16:31 +03:00
Code Issues Packages Projects Releases Wiki Activity

Multi - AC (betta) and some AI generated docs (not fully verefied)

Browse Source
This commit is contained in:
anklimov@gmail.com
2026-03-01 23:43:40 +03:00
parent 8db9e551ff
commit c5427251fc
32 changed files with 9688 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

465
documentation/suffixes_reference_v2.md Normal file
View File

@@ -0,0 +1,465 @@
# Справочник суффиксов 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