mirror of https://github.com/anklimov/lighthub synced 2026-03-13 21:06:31 +03:00

Files

anklimov@gmail.com c5427251fc Multi - AC (betta) and some AI generated docs (not fully verefied)

2026-03-01 23:43:40 +03:00

20 KiB

Raw Permalink Blame History

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

Документ актуален для ядра LightHub с типами каналов CH_DIMMER (0) - CH_MERCURY (22)

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

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

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

Сетевую интеграцию (MQTT, syslog)
Подключённые физические интерфейсы (DMX, RS485, GPIO, 1-Wire)
Библиотеки Modbus‑устройств (шаблоны с параметрами)
Логические объекты (items) — каналы управления (0-22 типов)
Маршрутизацию данных и команд между MQTT и локальными объектами

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

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

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

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

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

Секция `mqtt`

Назначение

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

Формат

"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"`

Примеры

"mqtt": ["lighthub", "m2m.eclipse.org"]

"mqtt": ["lh1", "192.168.1.10", 1883, "user", "pass"]

"mqtt": ["abc3", "192.168.88.2"]

⚠️ Безопасность: пароль рекомендуется задавать через CLI, а не хранить в JSON.

Секция `topics`

Назначение

Глобальные настройки MQTT‑топиков.

Формат

"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‑сервер (UDP).

Формат

"syslog": ["192.168.1.10", 514]

Параметры

№	Параметр	Тип	По умолчанию
0	IP адрес сервера	string	-
1	UDP порт	int	`514`

Секция `dmx`

Назначение

Конфигурация DMX 512 выхода (для работы с LED декодерами).

Форматы

Простой (для всех плат):

"dmx": [512]   // 512 DMX каналов

Расширенный (для Arduino Mega):

"dmx": [3, 512]  // GPIO pin 3, 512 каналов

Параметры

Параметр	Описание
GPIO pin	Пин TXD для DMX выхода
Кол-во каналов	Число DMX каналов (обычно 512)

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

Назначение

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

Формат

"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‑устройств.

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

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

"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` — стратегия опроса

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

"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 шаблона (реальный)

"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 — это логические объекты (каналы) LightHub.

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

Физические интерфейсы (GPIO, DMX, RS485)
Modbus параметры
MQTT топики
входы (кнопки, датчики)

Общий формат

"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

Код	Тип	Описание	Конфигурация
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) — Простое реле

"relay1": [6, 23],              // Реле на GPIO 23
"relay2": ["RELAY", 28],        // Текстовое обозначение типа
"relay3": [6, 28, 1, 1]         // С начальным значением и командой

CH_DMX (0) — DMX выход

"lamp1": [0, 5],                // DMX канал 5
"lamp2": [0, [10, 11, 12]],     // Массив DMX каналов
"dmx_4ch": ["DMX", [1, 2, 3, 4]]  // 4-х канальный диммер

CH_RGBW (1) — RGB+White

"rgb_light": [1, 10]            // RGB+W на DMX 10-13

CH_PWM (3) — GPIO PWM

"pwm1": [3, 9],                 // PWM на GPIO 9
"pwm_4ch": [3, [11, 12, 13, 14]] // 4-х канальный PWM

CH_GROUP (7) — Группа каналов

"lights_all": [7, [
  "lamp1", "lamp2", "lamp3",
  "rgb1", "rgb2"
]],
"lights_bedroom": [7, ["lamp1", "rgb1", "relay1"]]

CH_THERMO (5) — Термостат

"thermo_bath": [5, 24, 33]      // GPIO 24, уставка 33°C

CH_MBUS (14) — Universal Modbus

"ac_haier": [14, ["haier_ac", {
  "power": {"emit": "ac/power"},
  "mode": {"emit": "ac/mode"},
  "temperature": {"emit": "ac/temp"}
}]]

CH_COUNTER (20) — Счётчик энергии

"energy": [20, [0.02, 1.2]],     // коэффициент, масштаб
"gas": [20, 0]                   // без калибровки

CH_MULTIVENT (18) — Многозональная вентиляция

"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` (входы)

Назначение

Связывает физические входы (GPIO, кнопки) с логикой.

Формат

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

Пример

"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"
  }
}

Полный пример конфигурации

{
  "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"
    }
  }
}

Справочники и ссылки

Основные справочники

Справочник типов каналов — коды, текстовые обозначения, синтаксис конфигурации
Справочник суффиксов — параметры (/cmd, /val, /set, /hue, /sat, /temp и др.)
Описание модулей — подробная документация по каждому типу

Дополнительная информация

Исходный код item.h — определения типов и констант
Исходный код item.cpp — реализация логики
Репозиторий: https://github.com/anklimov/lighthub

Инженерные принципы конфигурирования

Сначала描述 Modbus устройства в секции modbus
Затем создаются items в секции items с использованием шаблонов
Затем подключается MQTT через emit параметры
Минимизировать poll задержку (не ниже 100 мс для RS485)
Использовать topics.root для всех MQTT топиков

Заключение

LightHub использует жёстко структурированную, декларативную модель конфигурации.

Это даёт:

Предсказуемость — структура всегда одинакова
Надёжность — явное лучше неявного
Промышленный стиль — как в PLC системах
Масштабируемость — легко добавлять новые устройства

Вся логика контроллера полностью определяется конфигурацией, без необходимости перекомпиляции кода.

Версия документа: 2.0
Дата обновления: 2025-01-24
Актуально для: LightHub с CH_DIMMER (0) - CH_MERCURY (22)
Источник: item.h, item.cpp

20 KiB Raw Permalink Blame History Unescape Escape

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

Содержание

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

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

Секция mqtt

Назначение

Формат

Параметры (позиционные!)

Примеры

Секция topics

Назначение

Формат

Параметры

Поведение

Секция syslog

Назначение

Формат

Параметры

Секция dmx

Назначение

Форматы

Параметры

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

Назначение

Формат

Параметры

Поведение

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

Назначение

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

Параметры линии

baud

serial

Раздел poll — стратегия опроса

Интерпретация

Раздел par — параметры устройства

Поля параметра

Типы данных (type)

Пример Modbus шаблона (реальный)

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

Назначение

Общий формат

Параметры

Типы каналов (0-22)

Примеры конфигурации items

CH_RELAY (6) — Простое реле

CH_DMX (0) — DMX выход

CH_RGBW (1) — RGB+White

CH_PWM (3) — GPIO PWM

CH_GROUP (7) — Группа каналов

CH_THERMO (5) — Термостат

CH_MBUS (14) — Universal Modbus

CH_COUNTER (20) — Счётчик энергии

CH_MULTIVENT (18) — Многозональная вентиляция

Секция in (входы)

Назначение

Формат

Параметры

Пример

Полный пример конфигурации

Справочники и ссылки

Основные справочники

Дополнительная информация

Инженерные принципы конфигурирования

Заключение

20 KiB

Raw Permalink Blame History

Секция `mqtt`

Секция `topics`

Секция `syslog`

Секция `dmx`

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

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

`baud`

`serial`

Раздел `poll` — стратегия опроса

Раздел `par` — параметры устройства

Типы данных (`type`)

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

Секция `in` (входы)