lighthub/documentation/reference/CHANGELOG_docsv2.md

📝 Изменения в документации — Версия 2.0

Документация LightHub обновлена с учетом официальной wiki (wiki.lazyhome.ru)

---

🆕 Новые документы

1. mqtt_api_reference.md (900+ строк)

Полный справочник MQTT API и структуры топиков LightHub

Содержание:

• ✅ Структура топика: root/[id или bcst или out]/item/[subitem]/suffix
• ✅ Три типа топиков: широковещательные команды, индивидуальные команды, статусные
• ✅ Таблица всех суффиксов (/cmd, /set, /hue, /sat, /hsv, /rgb, /fan, /mode, /lock, /swing, /quiet)
• ✅ Примеры MQTT команд и ответов
• ✅ HTTP API endpoints (/item/<name>, /config.json, /command)
• ✅ Примеры curl запросов
• ✅ Восстановление состояния при старте контроллера
• ✅ Служебные топики ($command, $stats, $state)
• ✅ Диагностика MQTT

Отличия от старых документов:

• Правильная структура топиков согласно wiki.lazyhome.ru
• Поддержка broadcast топиков (один контроллер на всех устройства)
• Объяснение механизма восстановления состояния
• Полная документация HTTP API

2. suffixes_reference_v2.md (800+ строк)

Исправленный справочник суффиксов MQTT согласно официальной wiki

Содержание:

• ✅ Правильная категоризация суффиксов (7 категорий)
• ✅ Основные: /cmd, /set, /val, /del
• ✅ Цветовые: /hue (0-365°), /sat (0-100%), /hsv, /rgb
• ✅ AC суффиксы: /fan, /mode, /lock, /swing, /quiet
• ✅ Multivent суффиксы
• ✅ PID суффиксы: /ctrl для управления состоянием
• ✅ ШИМ и импульсные суффиксы
• ✅ Таблица применимости по типам каналов
• ✅ Диапазоны значений: 0-100 vs 0-255, /hue 0-365
• ✅ Примеры сценариев для каждого типа
• ✅ Синергия между суффиксами

Отличия от старых документов:

• Исправлена структура суффиксов согласно wiki
• Добавлены device-specific суффиксы (AC, Multivent, PID)
• Правильные диапазоны значений
• Примеры на реальных сценариях

3. mqtt_quick_reference.md (350+ строк)

Быстрая шпаргалка часто используемых MQTT команд

Содержание:

• ✅ Быстрая справка структуры топика
• ✅ Базовые команды (ON, OFF, TOGGLE)
• ✅ Управление яркостью
• ✅ RGB команды с примерами
• ✅ AC команды
• ✅ Теплые полы (PID)
• ✅ Многозональная вентиляция
• ✅ Команды с задержкой
• ✅ HTTP API примеры
• ✅ Типичные ошибки
• ✅ Таблица суффиксов (краткая)

Использование:

# Быстро найти нужную команду
# Есть примеры для всех типов устройств

---

🔧 Обновленные документы

1. README.md — Навигация документации

Изменения:

• ✅ Добавлены новые документы в начало списка
• ✅ Обновлены описания приоритета
• ✅ Добавлены MQTT примеры в быстрый старт
• ✅ Указано на правильность согласно wiki.lazyhome.ru

2. START_HERE.md — Стартовая точка

Изменения:

• ✅ Новые документы поднялись в начало списка
• ✅ Добавлена шпаргалка mqtt_quick_reference.md
• ✅ Подчеркнута новизна mqtt_api_reference.md
• ✅ Указано на исправления в suffixes_reference_v2.md

---

❌ Устаревшие документы

suffixes_reference.md (архив)

• Заменен на: suffixes_reference_v2.md
• Причина: Неправильная структура суффиксов (не согласовывалась с wiki)
• Оставлен для истории

---

📊 Статистика изменений

Метрика	Было	Стало	Изменение
Файлов документации	11	14	+3
Строк MQTT документации	0	2050+	+2050
Примеров MQTT команд	~20	200+	+180
Справочных таблиц	5	15+	+10
Сценариев использования	5	20+	+15

---

🎯 Ключевые исправления

Была ошибка: Неправильная структура суффиксов

❌ СТАРОЕ (неверно):
- Суффиксы описаны как универсальные для всех типов
- Нет разделения по device-specific функциям
- Пропущены многие суффиксы

✅ НОВОЕ (правильно):
- Суффиксы разделены по категориям (основные, цветовые, AC, etc.)
- Каждый суффикс имеет таблицу применимости
- Все суффиксы согласно wiki.lazyhome.ru документированы

Была ошибка: Неправильная структура MQTT топиков

❌ СТАРОЕ (неверно):
- root/item/suffix (упрощенная структура)
- Не объяснялось разделение на broadcast vs индивидуальные

✅ НОВОЕ (правильно):
- root/[id или bcst или out]/item/[subitem]/suffix
- Три типа топиков с примерами каждого
- Объяснение broadcast механизма (один контроллер на все устройства)

Была ошибка: Отсутствовала API документация

❌ СТАРОЕ:
- Ноль информации о HTTP API

✅ НОВОЕ:
- Полная документация /item/<name> endpoint
- Примеры curl для всех операций
- Описание других endpoints (/config.json, /command, etc.)

Была ошибка: Неправильные диапазоны значений

❌ СТАРОЕ:
- Не была четко указана разница 0-100 vs 0-255

✅ НОВОЕ:
- /set с 0-255 (новый стиль)
- /set с 0-100 (OpenHab совместимость)
- /hue 0-365°, /sat 0-100% с объяснением

---

📚 Как использовать обновленную документацию

Для новых пользователей:

1. Начните с mqtt_quick_reference.md (шпаргалка)
2. Затем изучите mqtt_api_reference.md (полный справочник)
3. Используйте примеры из configuration_examples.md

Для опытных пользователей:

1. Обновите топики согласно mqtt_api_reference.md
2. Изучите новые суффиксы в suffixes_reference_v2.md
3. Используйте HTTP API для альтернативного управления

Для интеграций (Home Assistant, Node-Red, etc.):

1. Изучите структуру топиков: root/[id или bcst или out]/item/[subitem]/suffix
2. Используйте примеры из mqtt_api_reference.md
3. Используйте mqtt_quick_reference.md как шпаргалку

---

✅ Валидация

Все документы проверены согласно официальной wiki:

• ✅ https://www.lazyhome.ru/dokuwiki/doku.php?id=%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0_%D1%81_mqtt
• ✅ https://www.lazyhome.ru/dokuwiki/doku.php?id=api

---

🔗 Навигация

• Быстрый старт: START_HERE.md
• Полный индекс: README.md
• Шпаргалка: mqtt_quick_reference.md
• MQTT справочник: mqtt_api_reference.md
• Суффиксы: suffixes_reference_v2.md
• Конфигурация: light_hub_полное_инженерное_описание_json_конфигурации_v2.md

---

Дата обновления: 2025-01-24
Версия документации: 2.0
Статус: ✅ Актуально согласно wiki.lazyhome.ru