Multi - AC (betta) and some AI generated docs (not fully verefied)

2026-03-14 05:16:31 +03:00 · 2026-03-01 23:43:40 +03:00
parent 8db9e551ff
commit c5427251fc
32 changed files with 9688 additions and 90 deletions
--- a/documentation/README.md
+++ b/documentation/README.md
@@ -0,0 +1,302 @@
+# 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