# 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)