mirror of
https://github.com/anklimov/lighthub
synced 2026-03-14 05:16:31 +03:00
Multi - AC (betta) and some AI generated docs (not fully verefied)
This commit is contained in:
@@ -0,0 +1,372 @@
|
||||
# LightHub
|
||||
## Полное инженерное описание JSON‑конфигурации контроллера
|
||||
|
||||
> Документ предназначен для инженеров автоматизации, интеграторов и разработчиков.
|
||||
> Основан **строго** на официальной документации LazyHome / LightHub.
|
||||
> Описывает реальный формат конфигурации, без абстракций и допущений.
|
||||
|
||||
---
|
||||
|
||||
## 1. Назначение конфигурационного файла
|
||||
|
||||
JSON‑конфигурация LightHub — это **единственный источник описания системы**. Она определяет:
|
||||
|
||||
- сетевую интеграцию (MQTT, syslog)
|
||||
- подключённые физические интерфейсы
|
||||
- библиотеки Modbus‑устройств
|
||||
- логические объекты (items)
|
||||
- маршрутизацию данных и команд
|
||||
|
||||
❗ В LightHub **нет runtime‑конфигурации** — всё задаётся декларативно.
|
||||
|
||||
---
|
||||
|
||||
## 2. Общая структура JSON
|
||||
|
||||
Корневой объект конфигурации содержит **независимые секции**:
|
||||
|
||||
```json
|
||||
{
|
||||
"mqtt": [],
|
||||
"topics": {},
|
||||
"syslog": [],
|
||||
"ow": {},
|
||||
"dmx": [],
|
||||
"modbus": {},
|
||||
"in": {},
|
||||
"items": {}
|
||||
}
|
||||
```
|
||||
|
||||
Любая секция может отсутствовать, если функциональность не используется.
|
||||
|
||||
---
|
||||
|
||||
## 3. Секция `mqtt`
|
||||
|
||||
### 3.1 Назначение
|
||||
|
||||
Определяет **MQTT‑клиент LightHub**. Контроллер всегда работает как клиент.
|
||||
|
||||
### 3.2 Формат
|
||||
|
||||
```json
|
||||
"mqtt": [
|
||||
"client_id",
|
||||
"broker_host",
|
||||
1883,
|
||||
"username",
|
||||
"password"
|
||||
]
|
||||
```
|
||||
|
||||
### 3.3 Параметры (позиционные!)
|
||||
|
||||
```
|
||||
| № | Назначение |
|
||||
|--|--|
|
||||
| 0 | MQTT Client ID |
|
||||
| 1 | DNS‑имя или IP брокера |
|
||||
| 2 | Порт (опционально, по умолчанию 1883) |
|
||||
| 3 | Логин (опционально) |
|
||||
| 4 | Пароль (опционально) |
|
||||
```
|
||||
|
||||
⚠️ Пароль рекомендуется задавать через CLI, а не хранить в JSON.
|
||||
|
||||
---
|
||||
|
||||
## 4. Секция `topics`
|
||||
|
||||
### 4.1 Назначение
|
||||
|
||||
Глобальные настройки MQTT‑топиков.
|
||||
|
||||
### 4.2 Формат
|
||||
|
||||
```json
|
||||
"topics": {
|
||||
"root": "myhome"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Поведение
|
||||
|
||||
Все MQTT‑топики, создаваемые LightHub, будут иметь вид:
|
||||
|
||||
```
|
||||
<root>/<item>/<parameter>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Секция `syslog`
|
||||
|
||||
### 5.1 Назначение
|
||||
|
||||
Передача логов контроллера на удалённый syslog‑сервер (UDP).
|
||||
|
||||
### 5.2 Формат
|
||||
|
||||
```json
|
||||
"syslog": ["192.168.1.10", 514]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Секция `ow` (1‑Wire)
|
||||
|
||||
### 6.1 Назначение
|
||||
|
||||
Подключение датчиков 1‑Wire (DS18B20 и совместимые).
|
||||
|
||||
### 6.2 Формат
|
||||
|
||||
```json
|
||||
"ow": {
|
||||
"28FF641D2A1603B1": {
|
||||
"emit": "temp/outdoor",
|
||||
"item": "t_out"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 Поведение
|
||||
|
||||
- ключ — **уникальный ROM‑код датчика**
|
||||
- `emit` — MQTT‑топик публикации
|
||||
- `item` — привязка к локальному объекту
|
||||
|
||||
---
|
||||
|
||||
## 7. Секция `modbus` — КЛЮЧЕВАЯ
|
||||
|
||||
### 7.1 Назначение
|
||||
|
||||
Раздел `modbus` — это **библиотека описаний Modbus‑устройств**.
|
||||
|
||||
❗ Здесь **НЕ задаются реальные адреса устройств**, только шаблоны.
|
||||
|
||||
---
|
||||
|
||||
### 7.2 Общая структура
|
||||
|
||||
```json
|
||||
"modbus": {
|
||||
"device_type": {
|
||||
"baud": 9600,
|
||||
"serial": "8N1",
|
||||
"poll": {},
|
||||
"par": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7.3 Параметры линии
|
||||
|
||||
#### `baud`
|
||||
Скорость RS‑485: 9600 / 19200 / 38400 / 115200
|
||||
|
||||
#### `serial`
|
||||
Формат кадра:
|
||||
- `8N1` — стандарт
|
||||
- `8E1`, `8O1` — с чётностью
|
||||
|
||||
---
|
||||
|
||||
### 7.4 Раздел `poll`
|
||||
|
||||
Определяет **стратегию опроса**.
|
||||
|
||||
```json
|
||||
"poll": {
|
||||
"regs": [[0, 40], [100, 20]],
|
||||
"irs": [300, 301],
|
||||
"coils": [0, 1],
|
||||
"delay": 2000
|
||||
}
|
||||
```
|
||||
|
||||
#### Интерпретация
|
||||
|
||||
- `regs` — Holding Registers (блоки)
|
||||
- `irs` — Input Registers
|
||||
- `coils` — Coil Registers
|
||||
- `delay` — задержка между циклами (мс)
|
||||
|
||||
LightHub **объединяет регистры в минимальное число запросов**.
|
||||
|
||||
---
|
||||
|
||||
### 7.5 Раздел `par` — параметры устройства
|
||||
|
||||
Каждый параметр описывает **один логический сигнал**.
|
||||
|
||||
```json
|
||||
"par": {
|
||||
"power": {
|
||||
"reg": 41,
|
||||
"type": "u8l",
|
||||
"id": 1,
|
||||
"map": {"cmd": [["OFF",0],["ON",1]]}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Поля параметра
|
||||
|
||||
| Поле | Назначение |
|
||||
|--|--|
|
||||
| `reg` | Holding Register |
|
||||
| `ir` | Input Register |
|
||||
| `coil` | Coil |
|
||||
| `type` | Тип данных |
|
||||
| `id` | ID команды |
|
||||
| `map` | Преобразование |
|
||||
|
||||
---
|
||||
|
||||
### 7.6 Типы данных (`type`)
|
||||
|
||||
| Тип | Описание |
|
||||
|--|--|
|
||||
| `i16` | int16 |
|
||||
| `u16` | uint16 |
|
||||
| `i32` | int32 |
|
||||
| `u32` | uint32 |
|
||||
| `i8h` | старший байт |
|
||||
| `i8l` | младший байт |
|
||||
|
||||
---
|
||||
|
||||
### 7.7 Подавление повторов
|
||||
|
||||
По умолчанию значения публикуются **только при изменении**.
|
||||
|
||||
Для отключения:
|
||||
|
||||
```json
|
||||
"@V": null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Секция `items` — ЛОГИКА
|
||||
|
||||
### 8.1 Назначение
|
||||
|
||||
`items` — это **логические объекты LightHub**.
|
||||
|
||||
Они связывают:
|
||||
- Modbus параметры
|
||||
- MQTT
|
||||
- локальные объекты
|
||||
- входы
|
||||
|
||||
---
|
||||
|
||||
### 8.2 Общий формат
|
||||
|
||||
```json
|
||||
"item_name": [ TYPE, CONFIG ]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8.3 Тип 14 — Modbus v2
|
||||
|
||||
```json
|
||||
"vent1": [
|
||||
14,
|
||||
["vent", {
|
||||
"power": {"emit": "home/vent/1/power"},
|
||||
"fan": {"emit": "home/vent/1/fan"}
|
||||
}]
|
||||
]
|
||||
```
|
||||
|
||||
#### Расшифровка
|
||||
|
||||
- `14` — тип объекта Modbus v2
|
||||
- `vent` — имя шаблона из `modbus`
|
||||
- объект — привязка параметров
|
||||
|
||||
---
|
||||
|
||||
### 8.4 Мультивыход
|
||||
|
||||
```json
|
||||
"fan": [
|
||||
{"emit": "a"},
|
||||
{"emit": "b", "item": "local_fan"}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Секция `in` — входы
|
||||
|
||||
### 9.1 Назначение
|
||||
|
||||
Связывает физические входы с логикой.
|
||||
|
||||
```json
|
||||
"in": {
|
||||
"37": {
|
||||
"item": "light",
|
||||
"scmd": "TOGGLE",
|
||||
"rcmd": "TOGGLE"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Полный пример
|
||||
|
||||
```json
|
||||
{
|
||||
"mqtt": ["lh1","192.168.1.10"],
|
||||
"topics": {"root":"home"},
|
||||
"modbus": {
|
||||
"boiler": {
|
||||
"baud":9600,
|
||||
"serial":"8N1",
|
||||
"poll":{"regs":[[0,20]],"delay":1000},
|
||||
"par":{
|
||||
"temp":{"reg":5,"type":"i16"}
|
||||
}
|
||||
}
|
||||
},
|
||||
"items":{
|
||||
"boiler1":[14,["boiler",{"temp":{"emit":"home/boiler/temp"}}]]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Инженерные правила
|
||||
|
||||
- сначала описывается **modbus‑шаблон**
|
||||
- затем создаётся **item**
|
||||
- затем подключается MQTT
|
||||
- всегда минимизировать `poll`
|
||||
|
||||
---
|
||||
|
||||
## 12. Заключение
|
||||
|
||||
LightHub использует **жёстко структурированную, декларативную модель**.
|
||||
|
||||
Это даёт:
|
||||
- предсказуемость
|
||||
- надёжность
|
||||
- промышленный стиль конфигурации
|
||||
|
||||
---
|
||||
|
||||
**Конец документа**
|
||||
|
||||
Reference in New Issue
Block a user