lighthub/documentation/MIGRATION_GUIDE.md

Миграция с suffixes_reference.md на suffixes_reference_v2.md

Руководство для пользователей старой документации по переходу на новую правильную версию

---

📋 Основные различия

Старая версия (suffixes_reference.md) — ❌ Неверно

Проблемы:

1. ❌ Суффиксы описаны как универсальные для всех типов каналов
2. ❌ Нет разделения на device-specific суффиксы
3. ❌ Пропущены многие суффиксы (особенно для AC, Multivent, PID)
4. ❌ Неправильные диапазоны значений
5. ❌ Структура MQTT топиков упрощена

Пример старой ошибки:

# suffixes_reference.md
- /cmd — команда
- /set — значение
- /val — статус
- /hue — цвет
- /sat — насыщенность

(Других суффиксов нет — ошибка!)

Новая версия (suffixes_reference_v2.md) — ✅ Правильно

Улучшения:

1. ✅ Правильная категоризация (7 категорий суффиксов)
2. ✅ Таблица применимости для каждого типа канала
3. ✅ Device-specific суффиксы (AC, Multivent, PID)
4. ✅ Правильные диапазоны значений
5. ✅ Полная структура MQTT топиков

Пример новой структуры:

# suffixes_reference_v2.md

## Основные суффиксы (для всех)
- /cmd, /set, /val, /del

## Цветовые суффиксы (RGB)
- /hue, /sat, /hsv, /rgb

## Суффиксы AC
- /mode, /fan, /lock, /swing, /quiet

## Суффиксы Multivent
- /mode, /fan

## Суффиксы PID
- /ctrl, /mode

(Все суффиксы согласно wiki.lazyhome.ru)

---

🔄 Таблица соответствия

Как переписать старые конфигурации

Старое	Новое	Примечание
/cmd	/cmd	Не изменилось
/set	/set	Не изменилось, но теперь 0-255
/val	/val	Не изменилось, только для выхода
/hue	/hue	0-365° (было неупомянуто)
/sat	/sat	0-100% (было неупомянуто)
Отсутствовало	/fan	Новое для AC и Multivent
Отсутствовало	/mode	Новое для AC, Multivent, PID
Отсутствовало	/lock	Новое для AC
Отсутствовало	/swing	Новое для AC
Отсутствовало	/quiet	Новое для AC
Отсутствовало	/ctrl	Новое для управления состоянием
Отсутствовало	/del	Новое для команд с задержкой

---

🎯 Примеры обновления конфигураций

Сценарий 1: RGB свет

Старое (неверное)

{
  "items": {
    "rgb_light": [10, 1]
  }
}

Топики:
- myhome/in/rgb_light/cmd → ON, OFF
- myhome/in/rgb_light/set → 0-100
- myhome/in/rgb_light/hue → ???
- myhome/in/rgb_light/sat → ???

Проблемы:

• ❌ /hue и /sat не описаны
• ❌ Не ясны диапазоны значений
• ❌ Нет информации о взаимодействии суффиксов

Новое (правильное)

{
  "items": {
    "rgb_light": [10, 1]
  }
}

Топики согласно suffixes_reference_v2.md:
- myhome/in/rgb_light/cmd → ON, OFF, TOGGLE (команды)
- myhome/in/rgb_light/set → 0-255 (яркость)
- myhome/in/rgb_light/hue → 0-365 (оттенок в градусах)
- myhome/in/rgb_light/sat → 0-100 (насыщенность в %)
- myhome/in/rgb_light/hsv → hue,sat,val (полный HSV)
- myhome/in/rgb_light/rgb → r,g,b или r,g,b,w (RGB формат)

Синергия:
- ON без /hue, /sat → восстановить последний цвет
- /hue = 0 → красный
- /sat = 0 → белый (без цвета)
- /sat = 100 → полный цвет

Сценарий 2: Кондиционер

Старое (неверное)

{
  "items": {
    "ac_main": [13, {...}]
  }
}

Топики (из старого suffixes_reference.md):
- myhome/in/ac_main/cmd → ON, OFF
- myhome/in/ac_main/set → 0-100 (???)
(Никаких других суффиксов не описано!)

Проблемы:

• ❌ Отсутствуют суффиксы: /mode, /fan, /lock, /swing, /quiet
• ❌ Невозможно управлять режимом работы
• ❌ Невозможно менять скорость вентилятора

Новое (правильное)

{
  "items": {
    "ac_main": [13, {
      "mode": {"emit": "ac/mode"},
      "temp": {"emit": "ac/temp"}
    }]
  }
}

Топики согласно suffixes_reference_v2.md:
- myhome/in/ac_main/cmd → ON, OFF, TOGGLE
- myhome/in/ac_main/mode → HEAT, COOL, AUTO, DRY, FAN_ONLY
- myhome/in/ac_main/set → 16-30 (температура °C)
- myhome/in/ac_main/fan → HIGH, MED, LOW, AUTO
- myhome/in/ac_main/lock → ON, OFF (блокировка ПДУ)
- myhome/in/ac_main/swing → ON, OFF (направление воздуха)
- myhome/in/ac_main/quiet → ON, OFF (тихий режим)

Синергия:
- ON → восстановить последний режим и температуру
- OFF → запомнить текущие параметры
- /mode → только для выбора режима
- /set → установить температуру
- /fan → скорость вентилятора

Сценарий 3: Многозональная вентиляция

Старое (неверное)

{
  "items": {
    "multivent": [17, {...}]
  }
}

Топики:
- myhome/in/multivent/set → 20-25
(Больше ничего не понятно)

Проблемы:

• ❌ Структура subitem-ов не описана
• ❌ Отсутствуют суффиксы /fan, /mode
• ❌ Непонятно, как управлять отдельными зонами

Новое (правильное)

{
  "items": {
    "multivent": [17, {
      "bedroom": {"set": "multivent/bedroom/set"},
      "kitchen": {"set": "multivent/kitchen/set"}
    }]
  }
}

Топики согласно suffixes_reference_v2.md:
- myhome/in/multivent/cmd → ON, OFF (главное управление)
- myhome/in/multivent/mode → HEAT, AUTO, COOL (режим)
- myhome/in/multivent/fan → HIGH, MED, LOW (скорость вентилятора)

Для отдельных зон:
- myhome/in/multivent/bedroom/set → 21 (установить T в спальне)
- myhome/in/multivent/kitchen/set → 22 (установить T на кухне)

Статус:
- myhome/s_out/multivent/bedroom/val → 21.5 (текущая T)
- myhome/s_out/multivent/kitchen/val → 22.1 (текущая T)

Сценарий 4: Теплые полы (PID)

Старое (неверное)

{
  "items": {
    "floor": [15, 4]
  }
}

Топики:
- myhome/in/floor/cmd → ON, OFF
- myhome/in/floor/set → 20-30
(Никакого управления состоянием)

Проблемы:

• ❌ Отсутствует управление состоянием (FREEZE, ENABLE, DISABLE)
• ❌ Нет информации о режимах (AUTO, HEAT)
• ❌ Невозможно заблокировать канал

Новое (правильное)

{
  "items": {
    "floor": [15, 4]
  }
}

Топики согласно suffixes_reference_v2.md:
- myhome/in/floor/cmd → ON, OFF, TOGGLE (включить/выключить)
- myhome/in/floor/set → 24 (установить температуру)
- myhome/in/floor/mode → AUTO, HEAT, OFF (режим работы)
- myhome/in/floor/ctrl → ENABLE, DISABLE, FREEZE, UNFREEZE (управление)

Синергия:
- ON + mode AUTO → включить, включить регулирование если T < установленной
- ON + mode HEAT → включить отопление
- OFF → выключить (но помнить последние параметры)
- /ctrl FREEZE → заблокировать (игнорировать команды)
- /ctrl ENABLE → разрешить управление

---

📊 Полная таблица нового документа

Основные суффиксы (универсальные)

Суффикс	Применимость	Диапазон	Пример
/cmd	Все	Текст	ON, OFF, TOGGLE
/set	Все	0-255	150
/val	Все	0-255	100 (только выход)
/del	Все	Текст + время	"ON 5000"

Цветовые суффиксы (RGB, RGBW, RGBWW)

Суффикс	Применимость	Диапазон	Пример
/hue	RGB только	0-365°	240 (синий)
/sat	RGB только	0-100%	100 (полный)
/hsv	RGB только	H,S,V	240,100,200
/rgb	RGB только	R,G,B или R,G,B,W	255,0,0 или 255,0,0,100

AC суффиксы

Суффикс	Применимость	Значения	Пример
/cmd	AC	ON, OFF, TOGGLE	ON
/mode	AC	HEAT, COOL, AUTO, DRY, FAN_ONLY	HEAT
/set	AC	16-30°C	22
/fan	AC	HIGH, MED, LOW, AUTO	HIGH
/lock	AC	ON, OFF	ON
/swing	AC	ON, OFF	ON
/quiet	AC	ON, OFF	ON

Multivent суффиксы

Суффикс	Применимость	Значения	Пример
/cmd	Multivent	ON, OFF	ON
/set	Multivent	0-100 или температура	21
/mode	Multivent	HEAT, AUTO, COOL	AUTO
/fan	Multivent	HIGH, MED, LOW	HIGH

PID суффиксы

Суффикс	Применимость	Значения	Пример
/cmd	PID	ON, OFF, TOGGLE	ON
/set	PID	Температура	24
/mode	PID	HEAT, AUTO, OFF	AUTO
/ctrl	PID	ENABLE, DISABLE, FREEZE, UNFREEZE	FREEZE

---

🚀 Как перейти

Шаг 1: Поняться, что изменилось

Прочитайте CHANGELOG_v2.md

Шаг 2: Изучить новую структуру

Изучите suffixes_reference_v2.md

Шаг 3: Обновить конфигурацию

Найдите ваш тип канала в таблице и добавьте новые суффиксы

Шаг 4: Обновить MQTT подписки

Добавьте новые топики в вашу систему (Home Assistant, Node-Red, etc.)

Шаг 5: Тестирование

Проверьте все топики согласно mqtt_quick_reference.md

---

❓ FAQ

Q: Нужно ли мне обновлять существующие конфигурации?

A: Да, если вы используете:

• AC (кондиционер) — добавьте /mode, /fan, /lock, /swing, /quiet
• RGB свет — убедитесь, что используете /hue, /sat, /hsv, /rgb правильно
• Multivent — добавьте /fan, /mode
• PID (теплые полы) — добавьте /ctrl для управления состоянием

Q: Будет ли работать старая конфигурация?

A: Да, но вы потеряете функциональность. Рекомендуется обновить.

Q: Что если я использую только включение/выключение?

A: Для простых ON/OFF конфигурация не изменится.但 рекомендуется обновить для совместимости.

Q: Где найти примеры обновления?

A: В configuration_examples.md есть готовые примеры для всех типов.

---

📞 Помощь

• Вопросы о суффиксах: suffixes_reference_v2.md
• Структура MQTT: mqtt_api_reference.md
• Быстрая справка: mqtt_quick_reference.md
• Примеры: configuration_examples.md

---

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