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

693
documentation/light_hub_полное_инженерное_описание_json_конфигурации_v2.md Normal file
View File

@@ -0,0 +1,693 @@
# LightHub: Полное инженерное описание JSON‑конфигурации контроллера
> **Документ актуален для ядра LightHub с типами каналов CH_DIMMER (0) - CH_MERCURY (22)**
>
> Предназначен для инженеров автоматизации, интеграторов и разработчиков.
> Основан **строго** на официальной документации LazyHome / LightHub и исходном коде.
> Описывает реальный формат конфигурации, без абстракций и допущений.
---
## Содержание
1. [Назначение конфигурационного файла](#назначение)
2. [Общая структура JSON](#структура)
3. [Секция `mqtt`](#mqtt)
4. [Секция `topics`](#topics)
5. [Секция `syslog`](#syslog)
6. [Секция `ow` (1-Wire)](#1wire)
7. [Секция `modbus` (КЛЮЧЕВАЯ)](#modbus)
8. [Секция `items` (ЛОГИКА)](#items)
9. [Секция `in` (входы)](#in)
10. [Полный пример](#пример)
11. [Справочники и ссылки](#справочники)
---
## Назначение конфигурационного файла {#назначение}
JSON‑конфигурация LightHub — это **единственный источник описания системы**. Она определяет:
- **Сетевую интеграцию** (MQTT, syslog)
- **Подключённые физические интерфейсы** (DMX, RS485, GPIO, 1-Wire)
- **Библиотеки Modbus‑устройств** (шаблоны с параметрами)
- **Логические объекты (items)** — каналы управления (0-22 типов)
- **Маршрутизацию данных и команд** между MQTT и локальными объектами
❗ **В LightHub нет runtime‑конфигурации** — всё задаётся декларативно при загрузке файла.
---
## Общая структура JSON {#структура}
Корневой объект конфигурации содержит **независимые секции**:
```json
{
"mqtt": [],
"topics": {},
"syslog": [],
"dmx": [],
"ow": {},
"modbus": {},
"in": {},
"items": {}
}
```
**Любая секция может отсутствовать**, если функциональность не используется.
---
## Секция `mqtt` {#mqtt}
### Назначение
Определяет **MQTT‑клиент LightHub**. Контроллер всегда работает как клиент.
### Формат
```json
"mqtt": [
"client_id",
"broker_host",
1883,
"username",
"password"
]
```
### Параметры (позиционные!)
| № | Назначение | Тип | Обязателен | Пример |
|--|--|--|--|--|
| 0 | MQTT Client ID | string | **✓** | `"lighthub-07"` |
| 1 | DNS‑имя или IP брокера | string | **✓** | `"192.168.88.2"` |
| 2 | Порт | int | - | `1883` |
| 3 | Логин | string | - | `"mqtt_user"` |
| 4 | Пароль | string | - | `"pass123"` |
### Примеры
```json
"mqtt": ["lighthub", "m2m.eclipse.org"]
"mqtt": ["lh1", "192.168.1.10", 1883, "user", "pass"]
"mqtt": ["abc3", "192.168.88.2"]
```
⚠️ **Безопасность**: пароль рекомендуется задавать через CLI, а не хранить в JSON.
---
## Секция `topics` {#topics}
### Назначение
Глобальные настройки MQTT‑топиков.
### Формат
```json
"topics": {
"root": "myhome",
"in": "in",
"out": "out"
}
```
### Параметры
| Ключ | Назначение | По умолчанию |
|--|--|--|
| `root` | Корневой префикс всех топиков | `"myhome"` |
| `in` | Входящие команды | `"in"` |
| `out` | Исходящие статусы | `"out"` |
### Поведение
Все MQTT‑топики, создаваемые LightHub, будут иметь вид:
```
<root>/<item>/<parameter>
```
**Пример**:
```
myhome/dev/lamp1/val # статус яркости
myhome/dev/lamp1/cmd # последняя команда
myhome/s_out/lamp1/hue # текущий оттенок RGB лампы
```
---
## Секция `syslog` {#syslog}
### Назначение
Передача логов контроллера на удалённый syslog‑сервер (UDP).
### Формат
```json
"syslog": ["192.168.1.10", 514]
```
### Параметры
| № | Параметр | Тип | По умолчанию |
|--|--|--|--|
| 0 | IP адрес сервера | string | - |
| 1 | UDP порт | int | `514` |
---
## Секция `dmx` {#dmx}
### Назначение
Конфигурация DMX 512 выхода (для работы с LED декодерами).
### Форматы
**Простой** (для всех плат):
```json
"dmx": [512] // 512 DMX каналов
```
**Расширенный** (для Arduino Mega):
```json
"dmx": [3, 512] // GPIO pin 3, 512 каналов
```
### Параметры
| Параметр | Описание |
|--|--|
| GPIO pin | Пин TXD для DMX выхода |
| Кол-во каналов | Число DMX каналов (обычно 512) |
---
## Секция `ow` (1‑Wire) {#1wire}
### Назначение
Подключение датчиков 1‑Wire (DS18B20 и совместимые).
### Формат
```json
"ow": {
"28FF641D2A1603B1": {
"emit": "temp/outdoor",
"item": "t_out"
},
"284811170400005B": {
"emit": "temp/indoor"
}
}
```
### Параметры
| Ключ | Назначение |
|--|--|
| Ключ объекта | **ROM‑код датчика** (уникальный адрес, HEX) |
| `emit` | MQTT‑топик публикации (опционально) |
| `item` | Привязка к локальному объекту (опционально) |
### Поведение
- Датчик автоматически опрашивается по расписанию
- Температура публикуется в MQTT топик `root/emit_name`
- Если задан `item`, значение передаётся в локальный объект
---
## Секция `modbus` — КЛЮЧЕВАЯ {#modbus}
### Назначение
Раздел `modbus` — это **библиотека описаний Modbus‑устройств**.
❗ **Здесь НЕ задаются реальные адреса устройств**, только **шаблоны**.
Реальные адреса и параметры задаются в секции `items` при использовании шаблонов.
### Общая структура
```json
"modbus": {
"device_template_name": {
"baud": 9600,
"serial": "8N1",
"poll": {},
"par": {}
}
}
```
### Параметры линии
#### `baud`
Скорость RS‑485: `9600`, `19200`, `38400`, `115200`
#### `serial`
Формат кадра:
- `8N1` — 8 бит, без чётности, 1 стоп-бит (стандарт)
- `8E1` — 8 бит, чётность even, 1 стоп-бит
- `8O1` — 8 бит, чётность odd, 1 стоп-бит
### Раздел `poll` — стратегия опроса
```json
"poll": {
"regs": [[0, 40], [100, 20]],
"irs": [300, 301],
"coils": [0, 1],
"delay": 2000
}
```
#### Интерпретация
- **`regs`** — Holding Registers (блоки для чтения/записи)
- Формат: `[начальный_адрес, кол-во]`
- Пример: `[[0, 40], [100, 20]]` = два блока: 0-39 и 100-119
- **`irs`** — Input Registers (только чтение, статус)
- Формат: массив адресов
- Пример: `[300, 301]`
- **`coils`** — Coil Registers (логические выходы)
- Формат: массив адресов
- Пример: `[0, 1]`
- **`delay`** — Задержка между циклами опроса (мс)
- Пример: `2000` = опрашивать каждые 2 секунды
**LightHub автоматически объединяет регистры в минимальное число Modbus‑запросов**.
### Раздел `par` — параметры устройства
```json
"par": {
"power": {
"reg": 41,
"type": "u16",
"map": {"cmd": [["OFF", 0], ["ON", 1]]}
},
"temperature": {
"ir": 5,
"type": "i16",
"scale": 0.1
}
}
```
#### Поля параметра
| Поле | Назначение | Тип |
|--|--|--|
| `reg` | Holding Register (R/W) | int |
| `ir` | Input Register (R only) | int |
| `coil` | Coil Register | int |
| `type` | Тип данных | string |
| `map` | Преобразование значений | object |
| `scale` | Множитель масштабирования | float |
#### Типы данных (`type`)
| Тип | Значение | Диапазон |
|--|--|--|
| `u8` | uint8 | 0 - 255 |
| `i8` | int8 | -128 - 127 |
| `u16` | uint16 | 0 - 65535 |
| `i16` | int16 | -32768 - 32767 |
| `u32` | uint32 | 0 - 4294967295 |
| `i32` | int32 | -2147483648 - 2147483647 |
| `f32` | float32 | IEEE 754 |
| `u8h` | uint8 high byte | старший байт u16 |
| `u8l` | uint8 low byte | младший байт u16 |
### Пример Modbus шаблона (реальный)
```json
"modbus": {
"haier_ac": {
"baud": 9600,
"serial": "8N1",
"poll": {
"regs": [[1, 30]],
"delay": 1000
},
"par": {
"power": {
"reg": 1,
"type": "u16",
"map": {"cmd": [["OFF", 0], ["ON", 1]]}
},
"mode": {
"reg": 2,
"type": "u16",
"map": {"cmd": [["COOL", 0], ["HEAT", 1], ["DRY", 2], ["FAN", 3], ["AUTO", 4]]}
},
"temperature": {
"reg": 3,
"type": "u16",
"scale": 0.1
}
}
}
}
```
---
## Секция `items` — ЛОГИКА {#items}
### Назначение
`items` — это **логические объекты (каналы) LightHub**.
Они связывают:
- Физические интерфейсы (GPIO, DMX, RS485)
- Modbus параметры
- MQTT топики
- входы (кнопки, датчики)
### Общий формат
```json
"item_name": [
TYPE,
CONFIG,
initial_value, // опционально
initial_command // опционально
]
```
### Параметры
| Элемент | Назначение | Обязателен | Тип |
|--|--|--|--|
| 0 | **TYPE** — тип канала (0-22) | **✓** | int или string |
| 1 | **CONFIG** — конфигурация (зависит от типа) | **✓** | int, string, или array |
| 2 | Начальное значение (preset) | - | int или array |
| 3 | Начальная команда | - | int |
### Типы каналов (0-22)
**Полный справочник типов каналов см. в [channel_types_reference.md](channel_types_reference.md)**
| Код | Тип | Описание | Конфигурация |
|--|--|--|--|
| **0** | `DMX` | DMX выход с регулировкой | DMX канал или массив каналов |
| **1** | `DMXRGBW` | DMX RGB+White | Стартовый DMX канал |
| **2** | `DMXRGB` | DMX RGB | Стартовый DMX канал |
| **3** | `PWM` | GPIO PWM | GPIO пин или массив пинов |
| **4** | `MBUSDIM` | Modbus AC Dimmer (Legacy) | `[адрес, регистр, маска, макс]` |
| **5** | `THERMO` | ON/OFF термостат | `[GPIO_pin, целевая_T°C]` |
| **6** | `RELAY` | GPIO реле | GPIO пин |
| **7** | `GROUP` | Группа каналов | Массив имён каналов |
| **8** | `VCTEMP` | Vacom PID терморегулятор | `[Modbus_адрес, экземпляр]` |
| **9** | `MBUSVC` | Vacom мотор | `[адрес, конфиг]` |
| **10** | `ACHAIER` | Кондиционер Haier | `[порт, параметры]` |
| **11** | `SPILED` | SPI LED лента | `[CLK_pin, DATA_pin]` |
| **12** | `MOTOR` | Шаговый двигатель | `[PWM_pin, open_pin, close_pin, ...]` |
| **13** | `PID` | PID регулятор | `[[Kp, Ki, Kd, ...], execObj, ...]` |
| **14** | `MBUS` | Universal Modbus | `[адрес, шаблон, параметры]` |
| **15** | `UARTBRDG` | UART мост | Конфигурация портов |
| **16** | `RELAYX` | Медленный PWM | `[GPIO_pin, период_сек]` |
| **17** | `DMXRGBWW` | DMX RGBWW | Стартовый DMX канал |
| **18** | `VENTS` | Многозональная вентиляция | `[адрес, конфиг_зон]` |
| **19** | `ELEVATOR` | Лифт | TBD |
| **20** | `COUNTER` | Счётчик импульсов | `[коэфф, масштаб]` |
| **21** | `HUM` | Увлажнитель | Конфигурация |
| **22** | `MERCURY` | Счётчик энергии Mercury | `[адрес, baudrate, ...]` |
### Примеры конфигурации items
#### CH_RELAY (6) — Простое реле
```json
"relay1": [6, 23], // Реле на GPIO 23
"relay2": ["RELAY", 28], // Текстовое обозначение типа
"relay3": [6, 28, 1, 1] // С начальным значением и командой
```
#### CH_DMX (0) — DMX выход
```json
"lamp1": [0, 5], // DMX канал 5
"lamp2": [0, [10, 11, 12]], // Массив DMX каналов
"dmx_4ch": ["DMX", [1, 2, 3, 4]] // 4-х канальный диммер
```
#### CH_RGBW (1) — RGB+White
```json
"rgb_light": [1, 10] // RGB+W на DMX 10-13
```
#### CH_PWM (3) — GPIO PWM
```json
"pwm1": [3, 9], // PWM на GPIO 9
"pwm_4ch": [3, [11, 12, 13, 14]] // 4-х канальный PWM
```
#### CH_GROUP (7) — Группа каналов
```json
"lights_all": [7, [
"lamp1", "lamp2", "lamp3",
"rgb1", "rgb2"
]],
"lights_bedroom": [7, ["lamp1", "rgb1", "relay1"]]
```
#### CH_THERMO (5) — Термостат
```json
"thermo_bath": [5, 24, 33] // GPIO 24, уставка 33°C
```
#### CH_MBUS (14) — Universal Modbus
```json
"ac_haier": [14, ["haier_ac", {
"power": {"emit": "ac/power"},
"mode": {"emit": "ac/mode"},
"temperature": {"emit": "ac/temp"}
}]]
```
#### CH_COUNTER (20) — Счётчик энергии
```json
"energy": [20, [0.02, 1.2]], // коэффициент, масштаб
"gas": [20, 0] // без калибровки
```
#### CH_MULTIVENT (18) — Многозональная вентиляция
```json
"multivent": [18, [96, {
"": {
"val": {"emit": "main/temp"}
},
"bedroom": {
"val": {"emit": "bedroom/temp"},
"fan": {"emit": "bedroom/fan"},
"set": 22,
"pid": [1.0, 0.05, 0.02, 5.0]
},
"living_room": {
"val": {"emit": "living/temp"},
"set": 21
}
}]]
```
---
## Секция `in` (входы) {#in}
### Назначение
Связывает физические входы (GPIO, кнопки) с логикой.
### Формат
```json
"in": {
"37": {
"T": 0,
"item": "light",
"scmd": "TOGGLE",
"rcmd": "TOGGLE"
}
}
```
### Параметры
| Параметр | Назначение | Описание |
|--|--|--|
| Ключ | GPIO пин | Номер пина входа |
| `T` | Тип входа | 0 = нормальный, 1 = кнопка |
| `emit` | MQTT топик | Куда публиковать (опционально) |
| `item` | Локальный объект | Какой канал управлять |
| `scmd` | Short command | Команда при нажатии (T=0) |
| `rcmd` | Release command | Команда при отпускании (T=0) |
### Пример
```json
"in": {
"37": {
"T": 0,
"emit": "/myhome/in/all",
"scmd": "HALT",
"rcmd": "REST"
},
"38": {
"item": "spots",
"scmd": "TOGGLE",
"rcmd": "TOGGLE"
},
"39": {
"emit": "/myhome/s_out/water_leak"
}
}
```
---
## Полный пример конфигурации {#пример}
```json
{
"mqtt": ["lighthub-07", "192.168.88.2"],
"topics": {"root": "myhome"},
"syslog": ["192.168.88.2", 514],
"dmx": [512],
"modbus": {
"haier_ac": {
"baud": 9600,
"serial": "8N1",
"poll": {
"regs": [[1, 30]],
"delay": 1000
},
"par": {
"power": {
"reg": 1,
"type": "u16",
"map": {"cmd": [["OFF", 0], ["ON", 1]]}
},
"mode": {
"reg": 2,
"type": "u16",
"map": {"cmd": [["COOL", 0], ["HEAT", 1], ["DRY", 2]]}
},
"temperature": {
"reg": 3,
"type": "i16",
"scale": 0.1
}
}
}
},
"items": {
"lights_all": [7, [
"lamp_bedroom",
"lamp_kitchen",
"lamp_hall",
"rgb_living"
]],
"lamp_bedroom": [0, 1],
"lamp_kitchen": [0, 2],
"lamp_hall": [0, 3],
"rgb_living": [1, 10],
"relay_water": [6, 23],
"relay_heat": [6, 24],
"ac_main": [14, ["haier_ac", {
"power": {"emit": "ac/power"},
"mode": {"emit": "ac/mode"},
"temperature": {"emit": "ac/temp"}
}]],
"thermo_bath": [5, 35, 33],
"energy_meter": [20, [0.02, 1.2]]
},
"in": {
"37": {
"item": "lights_all",
"scmd": "TOGGLE",
"rcmd": "TOGGLE"
},
"38": {
"item": "relay_water",
"scmd": "OFF"
}
}
}
```
---
## Справочники и ссылки {#справочники}
### Основные справочники
- **[Справочник типов каналов](channel_types_reference.md)** — коды, текстовые обозначения, синтаксис конфигурации
- **[Справочник суффиксов](suffixes_reference.md)** — параметры (/cmd, /val, /set, /hue, /sat, /temp и др.)
- **[Описание модулей](modules_description.md)** — подробная документация по каждому типу
### Дополнительная информация
- [Исходный код item.h](../lighthub/item.h) — определения типов и констант
- [Исходный код item.cpp](../lighthub/item.cpp) — реализация логики
- Репозиторий: https://github.com/anklimov/lighthub
---
## Инженерные принципы конфигурирования
1. **Сначала描述 Modbus устройства** в секции `modbus`
2. **Затем создаются items** в секции `items` с использованием шаблонов
3. **Затем подключается MQTT** через `emit` параметры
4. **Минимизировать `poll` задержку** (не ниже 100 мс для RS485)
5. **Использовать `topics.root`** для всех MQTT топиков
---
## Заключение
LightHub использует **жёстко структурированную, декларативную модель конфигурации**.
Это даёт:
- **Предсказуемость** — структура всегда одинакова
- **Надёжность** — явное лучше неявного
- **Промышленный стиль** — как в PLC системах
- **Масштабируемость** — легко добавлять новые устройства
**Вся логика контроллера полностью определяется конфигурацией, без необходимости перекомпиляции кода.**
---
**Версия документа**: 2.0
**Дата обновления**: 2025-01-24
**Актуально для**: LightHub с CH_DIMMER (0) - CH_MERCURY (22)
**Источник**: [item.h](../lighthub/item.h), [item.cpp](../lighthub/item.cpp)