andry/lighthub
1
0
Fork 0
mirror of https://github.com/anklimov/lighthub synced 2026-03-14 05:16:31 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
master
lighthub/documentation/README.md

303 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# LightHub: Инженерная документация (Индекс)
> **Полная инженерная документация системы LightHub**
> Версия ядра: CH_DIMMER (0) - CH_MERCURY (22)
> Дата актуализации: 2025-01-24
---
## 📚 Структура документации
### Основные документы
1. **[light_hub_полное_инженерное_описание_json_конфигурации_v2.md](light_hub_полное_инженерное_описание_json_конфигурации_v2.md)** ⭐ **НАЧНИТЕ ОТСЮДА**
- Полное описание структуры JSON конфигурации
- Все секции: mqtt, topics, modbus, items, in
- Инженерные принципы конфигурирования
- Полный пример реальной конфигурации
### Справочники
**🆕 MQTT API и топики:**
2. **[mqtt_api_reference.md](mqtt_api_reference.md)** — ⭐ ПОЛНЫЙ справочник MQTT API
- Структура MQTT топиков: `root/[id или bcst или out]/item/[subitem]/suffix`
- Три типа топиков: широковещательные команды, индивидуальные команды, статусные
- Таблица суффиксов с применимостью
- HTTP API endpoints (`/item/<name>`, `/config.json`, `/command`)
- Примеры MQTT команд и HTTP curl запросов
- Восстановление состояния при старте контроллера
- Диагностика MQTT подключения
3. **[suffixes_reference_v2.md](suffixes_reference_v2.md)** — ⭐ ИСПРАВЛЕННЫЙ справочник суффиксов
- Правильная структура суффиксов согласно wiki.lazyhome.ru
- 7 категорий: основные, цветовые, AC, Multivent, PID, ШИМ, управление состоянием
- Таблица применимости по типам каналов (CH_DIMMER, CH_RGB, CH_AC и др.)
- Диапазоны значений: 0-100 vs 0-255, /hue 0-365°, /sat 0-100%
- Примеры сценариев для каждого типа канала
**Основные справочники:**
4. **[channel_types_reference.md](channel_types_reference.md)** — Справочник типов каналов (0-22)
- Таблица всех типов каналов с кодами
- Текстовые обозначения и английские названия
- Синтаксис конфигурации для каждого типа
- Визуализация иерархии типов
5. **[suffixes_reference.md](suffixes_reference.md)** — Справочник суффиксов параметров (архив)
- Старая версия справочника (см. suffixes_reference_v2.md)
6. **[technical_channel_types_table.md](technical_channel_types_table.md)** — Подробные технические таблицы
- Таблицы параметров для каждого типа
- Значения по умолчанию и ограничения
- Специфика работы каждого типа
### Модули и компоненты
7. **[modules_description.md](modules_description.md)** — Описание модулей
- out_Multivent — многозональная вентиляция
- out_AC — управление кондиционером
- out_PID — PID регулятор
- out_Motor — управление двигателем
- И другие модули...
8. **[multivent_module_description.md](multivent_module_description.md)** — Многозональная вентиляция (подробно)
9. **[modules_real_config.md](modules_real_config.md)** — Реальные конфигурации модулей
---
## 🎯 Быстрый старт по задачам
### Задача: Управлять LED светом через MQTT
1. Откройте [mqtt_api_reference.md](mqtt_api_reference.md) — чтобы понять структуру топиков
2. Выберите тип канала: CH_RGB (10), CH_RGBW (11) или CH_RGBWW (12)
3. Найдите примеры в [configuration_examples.md](configuration_examples.md)
4. Используйте MQTT команды из [suffixes_reference_v2.md](suffixes_reference_v2.md):
```
myhome/in/rgb_lamp/hue → 240 (установить синий)
myhome/in/rgb_lamp/sat → 100 (полная насыщенность)
myhome/in/rgb_lamp/set → 200 (яркость 200)
```
5. Получите ответы в статусных топиках:
```
myhome/s_out/rgb_lamp/hue → 240
myhome/s_out/rgb_lamp/sat → 100
myhome/s_out/rgb_lamp/val → 200
```
### Задача: Управлять кондиционером через MQTT
1. Откройте [mqtt_api_reference.md](mqtt_api_reference.md) — раздел "Суффиксы кондиционера (AC)"
2. Найдите CH_AC (13) в [configuration_examples.md](configuration_examples.md)
3. Используйте MQTT команды из [suffixes_reference_v2.md](suffixes_reference_v2.md):
```
myhome/in/ac_main/cmd → ON (включить)
myhome/in/ac_main/mode → HEAT (режим нагрева)
myhome/in/ac_main/set → 22 (температура 22°C)
myhome/in/ac_main/fan → HIGH (вентилятор на максимум)
```
4. Получите ответы в статусных топиках:
```
myhome/s_out/ac_main/cmd → ON
myhome/s_out/ac_main/mode → HEAT
myhome/s_out/ac_main/set → 22
```
### Задача: Настроить многозональную вентиляцию
1. Прочитайте [multivent_module_description.md](multivent_module_description.md)
2. Найдите CH_MULTIVENT (18) в [configuration_examples.md](configuration_examples.md)
3. Добавьте зоны в массив `"зоны": {...}`
4. Настройте PID параметры `[Kp, Ki, Kd, dT]`
5. Привяжите MQTT топики через `"emit"`
### Задача: Создать систему с входами (кнопки, датчики)
1. Прочитайте раздел "Секция `in`" в [light_hub_полное_инженерное_описание_json_конфигурации_v2.md](light_hub_полное_инженерное_описание_json_конфигурации_v2.md)
2. Определите GPIO пины входов (37, 38, 39, и т.д.)
3. Привяжите их к объектам через `"item": "имя_канала"`
4. Используйте команды `scmd`, `rcmd` для действий
5. Используйте `"emit"` для публикации событий в MQTT
---
## 📖 Таблица типов каналов
| Код | Тип | Применение | Ссылка на пример |
|-----|-----|-----------|------------------|
| 0 | DMX | Диммер через DMX 512 | [⬇️](configuration_examples.md#ch_dimmer-0---dmx-диммер) |
| 1 | DMXRGBW | RGB+White через DMX | [⬇️](configuration_examples.md#ch_rgbw-1---dmx-rgbwhite) |
| 2 | DMXRGB | RGB через DMX | [⬇️](configuration_examples.md#ch_rgb-2---dmx-rgb) |
| 3 | PWM | GPIO PWM | [⬇️](configuration_examples.md#ch_pwm-3---gpio-pwm) |
| 4 | MBUSDIM | Modbus AC Dimmer (Legacy) | [⬇️](configuration_examples.md#ch_modbus-4---modbus-ac-dimmer-legacy) |
| 5 | THERMO | ON/OFF Термостат | [⬇️](configuration_examples.md#ch_thermo-5---onoff-термостат) |
| 6 | RELAY | GPIO Реле | [⬇️](configuration_examples.md#ch_relay-6---gpio-реле) |
| 7 | GROUP | Группа каналов | [⬇️](configuration_examples.md#ch_group-7---группа-каналов) |
| 8 | VCTEMP | Vacom PID Терморегулятор | [⬇️](configuration_examples.md#ch_vctemp-8---vacom-pid-терморегулятор) |
| 9 | MBUSVC | Vacom Мотор | [⬇️](configuration_examples.md#ch_vc-9---vacom-мотор-регулятор) |
| 10 | ACHAIER | Кондиционер Haier | [⬇️](configuration_examples.md#ch_ac-10---кондиционер-haier) |
| 11 | SPILED | SPI LED Лента | [⬇️](configuration_examples.md#ch_spiled-11---spi-led-лента) |
| 12 | MOTOR | Шаговый двигатель | [⬇️](configuration_examples.md#ch_motor-12---шаговый-двигатель) |
| 13 | PID | PID Регулятор | [⬇️](configuration_examples.md#ch_pid-13---pid-регулятор) |
| 14 | MBUS | Universal Modbus | [⬇️](configuration_examples.md#ch_mbus-14---universal-modbus) |
| 15 | UARTBRDG | UART Мост | [⬇️](configuration_examples.md#ch_uartbridge-15---uart-мост) |
| 16 | RELAYX | Медленный PWM реле | [⬇️](configuration_examples.md#ch_relayx-16---медленный-pwm-через-реле) |
| 17 | DMXRGBWW | RGBWW через DMX | [⬇️](configuration_examples.md#ch_rgbww-17---dmx-rgbww) |
| 18 | VENTS | Многозональная вентиляция | [⬇️](configuration_examples.md#ch_multivent-18---многозональная-вентиляция) |
| 19 | ELEVATOR | Лифт | - (TBD) |
| 20 | COUNTER | Счётчик импульсов | [⬇️](configuration_examples.md#ch_counter-20---счётчик-импульсов) |
| 21 | HUM | Увлажнитель | [⬇️](configuration_examples.md#ch_humidifier-21---управление-увлажнителем) |
| 22 | MERCURY | Счётчик энергии | [⬇️](configuration_examples.md#ch_mercury-22---счётчик-энергии-mercury) |
---
## 📊 Таблица суффиксов MQTT
| Суффикс | Назначение | Применимо к |
|---------|-----------|-----------|
| `/cmd` | Команда управления | Все типы |
| `/val` | Текущее значение (статус) | Все типы |
| `/set` | Установка значения | Диммеры, регуляторы |
| `/hue` | Оттенок (0-359°) | RGB/RGBW/RGBWW |
| `/sat` | Насыщенность (0-100%) | RGB/RGBW/RGBWW |
| `/temp` | Температура цвета (K) | RGB/RGBW/RGBWW |
| `/fan` | Скорость вентилятора | AC, Multivent, Vacom |
| `/mode` | Режим работы | AC, Multivent |
| `/raw` | JSON формат (отладка) | Все типы |
---
## 🔗 Инструменты и утилиты
### JSON Валидаторы
- [JSONLint](https://www.jsonlint.com/) — проверка синтаксиса JSON
- [JSON Online Editor](https://jsoncrack.com/) — визуализация структуры
### Инженерные калькуляторы
- Масштабирование значений: `value_out = (value_in - min_in) / (max_in - min_in) * (max_out - min_out) + min_out`
- Коэффициенты PID (для запуска): `Kp = 1.0, Ki = 0.05, Kd = 0.02, dT = 5.0`
---
## 🛠️ Отладка конфигурации
### Проверка синтаксиса
```bash
# Скопируйте конфигурацию в JSONLint или используйте Python:
python3 -m json.tool config.json
```
### Логирование Modbus
Если Modbus устройство не отвечает:
1. Проверьте baudrate (по умолчанию 9600)
2. Проверьте адрес устройства
3. Проверьте регистры (должны быть доступны для чтения)
4. Включите syslog для отладки
### MQTT Отладка
```bash
# Подпишитесь на все топики
mosquitto_sub -h 192.168.88.2 -t "myhome/#" -v
# Отправьте команду
mosquitto_pub -h 192.168.88.2 -t "myhome/dev/lamp/cmd" -m "ON"
```
---
## ⚡ Инженерные правила
### Правило 1: Сначала структура
```
Modbus шаблон (в "modbus")
↓
Item (в "items")
↓
MQTT привязка (через "emit")
↓
Входы (в "in", опционально)
```
### Правило 2: Минимизируй poll
- DMX: нет опроса (output only)
- RS485 Modbus: не менее 100 мс задержки
- 1-Wire: 500-1000 мс
- GPIO входы: 10-50 мс
### Правило 3: Используй GROUP для синхронизации
```json
"lights_all": [7, ["lamp1", "lamp2", "lamp3"]],
// Теперь можно управлять всеми сразу:
// myhome/dev/lights_all/cmd → ON
```
### Правило 4: Подробное имя = легче найти
```json
"lamp_bedroom_ceiling": [0, 1], // ✓ Хорошо
"lamp1": [0, 1] // ✗ Плохо
```
---
## 📞 Получить помощь
- **GitHub репозиторий**: https://github.com/anklimov/lighthub
- **Официальный сайт**: https://lazyhome.ru
- **Документация Wiki**: https://www.lazyhome.ru/dokuwiki/
---
## 📝 История версий
| Версия | Дата | Изменения |
|--------|------|----------|
| 2.0 | 2025-01-24 | Полная актуализация документации для ядра CH_DIMMER (0) - CH_MERCURY (22) |
| 1.0 | 2024-12-16 | Исходная версия |
---
## ✅ Чек-лист перед запуском
- [ ] JSON синтаксис проверен (JSONLint)
- [ ] Все GPIO пины уникальны (нет конфликтов)
- [ ] Все Modbus адреса доступны
- [ ] MQTT брокер доступен и запущен
- [ ] Все типы каналов в диапазоне 0-22
- [ ] Содержатся ли необходимые секции (mqtt, items)
- [ ] Проверены все MQTT топики
- [ ] Запасная копия конфигурации сохранена
---
## 📌 Важные замечания
⚠️ **БЕЗОПАСНОСТЬ**:
- Не сохраняйте пароли MQTT в конфигурации!
- Используйте CLI для установки пароля
⚠️ **ПРОИЗВОДИТЕЛЬНОСТЬ**:
- Максимум 1000 items рекомендуется для стабильной работы
- Не устанавливайте poll менее 50 мс для RS485
⚠️ **СОВМЕСТИМОСТЬ**:
- Эта документация актуальна для ядра с типами 0-22
- Убедитесь, что ваша версия LightHub поддерживает нужные типы
---
**Последнее обновление**: 24 января 2026 г.
**Актуально для**: LightHub Core v2.x
**Автор**: Документация LightHub Project
**Лицензия**: Apache 2.0
Reference in New Issue View Git Blame Copy Permalink