# 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 использует **жёстко структурированную, декларативную модель**.

Это даёт:
- предсказуемость
- надёжность
- промышленный стиль конфигурации

---

**Конец документа**