lighthub/documentation/light_hub_полное_инженерное_описание_json_конфигурации.md

LightHub

Полное инженерное описание JSON‑конфигурации контроллера

Документ предназначен для инженеров автоматизации, интеграторов и разработчиков. Основан строго на официальной документации LazyHome / LightHub. Описывает реальный формат конфигурации, без абстракций и допущений.

---

1. Назначение конфигурационного файла

JSON‑конфигурация LightHub — это единственный источник описания системы. Она определяет:

• сетевую интеграцию (MQTT, syslog)
• подключённые физические интерфейсы
• библиотеки Modbus‑устройств
• логические объекты (items)
• маршрутизацию данных и команд

❗ В LightHub нет runtime‑конфигурации — всё задаётся декларативно.

---

2. Общая структура JSON

Корневой объект конфигурации содержит независимые секции:

{
  "mqtt": [],
  "topics": {},
  "syslog": [],
  "ow": {},
  "dmx": [],
  "modbus": {},
  "in": {},
  "items": {}
}

Любая секция может отсутствовать, если функциональность не используется.

---

3. Секция mqtt

3.1 Назначение

Определяет MQTT‑клиент LightHub. Контроллер всегда работает как клиент.

3.2 Формат

"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 Формат

"topics": {
  "root": "myhome"
}

4.3 Поведение

Все MQTT‑топики, создаваемые LightHub, будут иметь вид:

<root>/<item>/<parameter>

---

5. Секция syslog

5.1 Назначение

Передача логов контроллера на удалённый syslog‑сервер (UDP).

5.2 Формат

"syslog": ["192.168.1.10", 514]

---

6. Секция ow (1‑Wire)

6.1 Назначение

Подключение датчиков 1‑Wire (DS18B20 и совместимые).

6.2 Формат

"ow": {
  "28FF641D2A1603B1": {
    "emit": "temp/outdoor",
    "item": "t_out"
  }
}

6.3 Поведение

• ключ — уникальный ROM‑код датчика
• emit — MQTT‑топик публикации
• item — привязка к локальному объекту

---

7. Секция modbus — КЛЮЧЕВАЯ

7.1 Назначение

Раздел modbus — это библиотека описаний Modbus‑устройств.

❗ Здесь НЕ задаются реальные адреса устройств, только шаблоны.

---

7.2 Общая структура

"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

Определяет стратегию опроса.

"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 — параметры устройства

Каждый параметр описывает один логический сигнал.

"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 Подавление повторов

По умолчанию значения публикуются только при изменении.

Для отключения:

"@V": null

---

8. Секция items — ЛОГИКА

8.1 Назначение

items — это логические объекты LightHub.

Они связывают:

• Modbus параметры
• MQTT
• локальные объекты
• входы

---

8.2 Общий формат

"item_name": [ TYPE, CONFIG ]

---

8.3 Тип 14 — Modbus v2

"vent1": [
  14,
  ["vent", {
    "power": {"emit": "home/vent/1/power"},
    "fan":   {"emit": "home/vent/1/fan"}
  }]
]

Расшифровка

• 14 — тип объекта Modbus v2
• vent — имя шаблона из modbus
• объект — привязка параметров

---

8.4 Мультивыход

"fan": [
  {"emit": "a"},
  {"emit": "b", "item": "local_fan"}
]

---

9. Секция in — входы

9.1 Назначение

Связывает физические входы с логикой.

"in": {
  "37": {
    "item": "light",
    "scmd": "TOGGLE",
    "rcmd": "TOGGLE"
  }
}

---

10. Полный пример

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

Это даёт:

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

---

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