mirror of
https://github.com/anklimov/lighthub
synced 2026-03-14 05:16:31 +03:00
206 lines
9.3 KiB
Markdown
206 lines
9.3 KiB
Markdown
# 📝 Изменения в документации — Версия 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 примеры
|
||
- ✅ Типичные ошибки
|
||
- ✅ Таблица суффиксов (краткая)
|
||
|
||
**Использование:**
|
||
```bash
|
||
# Быстро найти нужную команду
|
||
# Есть примеры для всех типов устройств
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Обновленные документы
|
||
|
||
### 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](mqtt_quick_reference.md) (шпаргалка)
|
||
2. Затем изучите [mqtt_api_reference.md](mqtt_api_reference.md) (полный справочник)
|
||
3. Используйте примеры из [configuration_examples.md](configuration_examples.md)
|
||
|
||
### Для опытных пользователей:
|
||
1. Обновите топики согласно [mqtt_api_reference.md](mqtt_api_reference.md)
|
||
2. Изучите новые суффиксы в [suffixes_reference_v2.md](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](mqtt_api_reference.md)
|
||
3. Используйте [mqtt_quick_reference.md](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](START_HERE.md)
|
||
- **Полный индекс**: [README.md](README.md)
|
||
- **Шпаргалка**: [mqtt_quick_reference.md](mqtt_quick_reference.md)
|
||
- **MQTT справочник**: [mqtt_api_reference.md](mqtt_api_reference.md)
|
||
- **Суффиксы**: [suffixes_reference_v2.md](suffixes_reference_v2.md)
|
||
- **Конфигурация**: [light_hub_полное_инженерное_описание_json_конфигурации_v2.md](light_hub_полное_инженерное_описание_json_конфигурации_v2.md)
|
||
|
||
---
|
||
|
||
**Дата обновления**: 2025-01-24
|
||
**Версия документации**: 2.0
|
||
**Статус**: ✅ Актуально согласно wiki.lazyhome.ru
|