# 📝 Изменения в документации — Версия 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