Как использовать контроллеры ZS05 Zigbee с помощью SmartIR
Некоторое время назад я купил популярный Zigbee‑инфракрасный пульт ZS05. Идея была очевидной: подключить его к Home Assistant, повесить на стену и через него управлять телевизором, проектором и кондиционером. Первая попытка была через интеграцию Zigbee Home Automation (ZHA). Настроить удалось лишь базовое управление телевизором и проектором, а вот кондиционер так и остался "на потом" - наступила зима, и мотивация пропала.
Позже я полностью переустановил Home Assistant, потеряв старую конфигурацию, и решил строить систему заново - уже на базе Zigbee2MQTT. На первый взгляд, связка ZS05 + Zigbee2MQTT + SmartIR выглядит простой, но на практике обнаружилось неприятное расхождение с официальной инструкцией SmartIR: в ней допущена ошибка (или пропущен важный нюанс), из-за которой ZS05 просто игнорирует команды, хотя с точки зрения Home Assistant всё выглядит корректно.
Ниже - рабочая пошаговая схема, которая позволяет подружить ZS05, Zigbee2MQTT и SmartIR и настроить полноценное управление климатом и другой техникой через Home Assistant.
---
Что потребуется
Для начала убедитесь, что у вас есть следующее:
- Home Assistant (актуальная версия, способ установки не принципиален).
- Zigbee2MQTT (как аддон Home Assistant или в Docker-контейнере).
- Интеграция SmartIR (установка через HACS).
- Инфракрасный Zigbee‑контроллер ZS05 (или совместимый аналог, работающий по тому же принципу - Zigbee‑ИК‑брелок/пульт).
Связка ZS05 с Zigbee2MQTT обычно работает стабильнее, чем через ZHA, но важен корректный MQTT‑топик и формат кодов.
---
Шаг 1. Подключаем ZS05 к Zigbee2MQTT
1. Включите в Zigbee2MQTT режим сопряжения (Permit join).
2. Переведите контроллер ZS05 в режим сброса/спаривания - обычно это длительное удержание кнопки на корпусе до мигания светодиода.
3. Через несколько секунд ZS05 должен появиться в интерфейсе Zigbee2MQTT как новое устройство.
4. Задайте ему понятное Friendly Name, например:
`ir_livingroom`, `ir_bedroom`, `ir_tv` - название потом напрямую влияет на MQTT‑топики.
5. В логах Zigbee2MQTT проверьте, что устройство живое и обменивается сообщениями. Топики должны выглядеть примерно так:
`zigbee2mqtt/ir_livingroom` и ответы на них.
Важно: ZS05 ожидает управляющие команды не на корневой топик устройства, а на конкретный подтопик, об этом и спотыкается большинство инструкций.
---
Шаг 2. Устанавливаем и готовим SmartIR
Если SmartIR ещё не установлен:
1. Откройте HACS в Home Assistant.
2. Найдите интеграцию SmartIR.
3. Установите её и перезапустите Home Assistant.
SmartIR создаёт в Home Assistant виртуальные сущности:
- `climate` - кондиционеры и климат-системы,
- `fan` - вентиляторы,
- `media_player` - телевизоры, приставки, ресиверы и пр.
Эти сущности не управляют техникой напрямую: они отдают команды в выбранную интеграцию (Broadlink, MQTT и т. д.). В нашем случае роль "транспортного слоя" играет MQTT, а реальную передачу ИК‑сигнала выполняет ZS05 через Zigbee2MQTT.
---
Шаг 3. Правильная конфигурация SmartIR (ключевая ошибка в инструкциях)
В официальных примерах конфигурации для MQTT зачастую указан неверный подтопик, что делает ZS05 "глухим" к командам. На первый взгляд всё выглядит логично, но контроллер ждёт команд в другом месте.
Какую ошибку обычно делают
В примерах часто встречается примерно такой вариант:
```yaml
controller_data: zigbee2mqtt/ir_livingroom/command
```
Логика понятна: "мы же отправляем команду, значит /command". Для ZS05 (и большинства подобных Zigbee‑ИК‑контроллеров) это неверно.
Как нужно на самом деле
Контроллер ждёт ИК‑команды в подтопике `/set/ir_code_to_send`. То есть для Friendly Name `ir_livingroom` корректным будет:
```yaml
controller_data: zigbee2mqtt/ir_livingroom/set/ir_code_to_send
```
Именно в этот MQTT‑топик Zigbee2MQTT принимает строку с кодом (обычно в Base64), а затем уже сам отправляет её на ZS05 для воспроизведения по ИК.
---
Шаг 4. Пример конфигурации SmartIR в configuration.yaml
Рассмотрим базовый пример для кондиционера. В файл `configuration.yaml` добавляем сущность `climate`, управляемую SmartIR:
```yaml
climate:
- platform: smartir
name: Кондиционер в гостиной
unique_id: livingroom_ac
device_code: 1000
controller_data: zigbee2mqtt/ir_livingroom/set/ir_code_to_send
temperature_sensor: sensor.livingroom_temperature
humidity_sensor: sensor.livingroom_humidity
power_sensor: binary_sensor.livingroom_ac_power
```
Разберём ключевые моменты:
- `platform: smartir` - указывает Home Assistant, что сущность создаётся через SmartIR.
- `name` - отображаемое имя в интерфейсе.
- `unique_id` - уникальный идентификатор, лучше задать сразу и не менять.
- `device_code` - код устройства из библиотеки SmartIR (об этом ниже).
- `controller_data` - КРИТИЧЕСКИЙ параметр:
для ZS05 обязателен формат
`zigbee2mqtt//set/ir_code_to_send`
- `temperature_sensor` / `humidity_sensor` - необязательные, но весьма полезные сенсоры для корректной работы климат-контроля (режимы Auto, поддержание температуры).
- `power_sensor` - датчик, по которому SmartIR понимает, включен ли сейчас кондиционер (может быть, например, датчиком потребления от умной розетки).
---
Шаг 5. Подбор и подготовка device_code
SmartIR использует библиотеку конфигурационных файлов с кодами ИК‑команд. Для климат‑устройств они лежат в папке `smartir/codes/climate` (числовые файлы: `1000.json`, `1001.json` и т. д.).
Как выбрать код
1. Найдите в библиотеке бренд и модель вашего кондиционера.
2. Если точного совпадения нет, выберите ближайший по протоколу или используйте универсальные коды (часто подходят варианты для Gree, Midea и других массовых брендов).
3. Запишите выбранный номер в `device_code`.
Однако есть нюанс: стандартные коды в библиотеке SmartIR изначально ориентированы на устройства Broadlink и используют их внутренний формат ИК‑последовательностей. ZS05 таким форматом не пользуется - он принимает сырой MQTT‑пакет с данными (обычно закодированными в Base64 или в другой "сырой" форме).
Если использовать файл из библиотеки как есть, SmartIR будет честно отправлять в MQTT "broadlink‑коды", но ZS05 не сможет их воспроизвести. Поэтому файлы нужно предварительно конвертировать.
---
Шаг 6. Конвертация Broadlink‑кодов в Raw MQTT
1. Загрузка исходного файла
- Найдите нужный файл из библиотеки SmartIR (например, `1000.json`).
- Скопируйте его себе локально (на компьютер или в файловый менеджер Home Assistant).
Внутри вы увидите структуру с параметрами режимов, температур и массивами ИК‑команд, обычно в виде строк, специфичных для Broadlink.
2. Конвертация кода
Есть два основных подхода, как преобразовать Broadlink‑формат в "сырой MQTT" для ZS05:
Вариант А. Онлайн‑конвертер
Существует специализированный онлайн‑инструмент, который берёт на вход строку Broadlink‑кода и возвращает строку в формате Raw MQTT (как правило, Base64 либо JSON‑структуру, подходящую для отправки через Zigbee2MQTT).
Алгоритм действий:
1. Берёте строку кода из файла SmartIR.
2. Вставляете её в поле конвертера.
3. Получаете на выходе строку в формате, который понимает ZS05 через Zigbee2MQTT.
4. Подставляете полученный результат обратно в свой копию файла `device_code`, заменяя исходные значения.
Преимущество: не нужно ничего устанавливать, достаточно браузера. Недостаток: придётся вручную конвертировать каждый уникальный код.
Вариант Б. Локальный Python‑скрипт
Если вы предпочитаете работать локально, можно использовать готовый скрипт на Python, который:
- читает файл SmartIR в Broadlink‑формате,
- преобразует каждую строку к нужному виду,
- сохраняет обновлённый JSON с теми же параметрами, но уже в формате Raw MQTT.
Типичный сценарий:
1. Устанавливаете Python на компьютер или используете встроенную среду в Home Assistant.
2. Кладёте скрипт и нужный JSON‑файл рядом.
3. Запускаете преобразование.
4. Получаете новый файл - его и указываете как `device_code` (под тем же номером или меняете номер на свой).
---
Шаг 7. Что должно получиться после конвертации
После обработки:
- структура файла SmartIR (режимы, зависимости, температуры) остаётся прежней;
- вместо Broadlink‑строк в полях `command` или аналогичных полях теперь лежат строки в формате, совместимом с ZS05 и Zigbee2MQTT;
- сам SmartIR по-прежнему считает, что работает с обычным устройством, но реальная передача идёт через MQTT в "сыром" виде.
Важно: не меняйте логику полей (температуры, режимы, флаги), правьте только сами коды сигналов.
---
Шаг 8. Проверка работы и отладка
После того как:
- ZS05 привязан к Zigbee2MQTT,
- SmartIR настроен в `configuration.yaml`,
- коды конвертированы и сохранены,
нужно проверить работу.
1. Перезапуск Home Assistant
После правок конфигурации:
1. Проверьте конфигурацию через интерфейс (пункт "Проверить конфигурацию").
2. Перезапустите Home Assistant.
3. Убедитесь, что сущность `climate` (или другая) появилась и доступна.
2. Тест из интерфейса
Откройте карточку кондиционера:
- Попробуйте включить/выключить устройство.
- Измените температуру.
- Переключите режимы (охлаждение, обогрев, авто и т. д.).
При каждом действии:
- в журналах Home Assistant должны появляться события отправки команд через SmartIR;
- в логах Zigbee2MQTT вы должны видеть публикации в топик
`zigbee2mqtt/ir_livingroom/set/ir_code_to_send`
с длинными строками (обычно Base64).
Если в логах MQTT ничего не появляется - проблема в конфигурации SmartIR (чаще всего в `controller_data`).
Если сообщения есть, но кондиционер не реагирует - либо неправильные коды, либо некорректная конвертация.
---
Частые ошибки и способы их устранения
1. Неверный MQTT‑топик в controller_data
- Симптом: никаких сообщений в логах Zigbee2MQTT при управлении через Home Assistant.
- Решение: перепроверьте Friendly Name устройства в Zigbee2MQTT и точно пропишите:
`zigbee2mqtt//set/ir_code_to_send`.
2. Использование исходных Broadlink‑кодов без конвертации
- Симптом: сообщения в MQTT есть, но техника не реагирует.
- Решение: обязательно конвертируйте коды в формат Raw MQTT и замените содержимое файла `device_code`.
3. Кондиционер периодически "теряет" состояние
- Симптом: в интерфейсе Home Assistant кондиционер отображается включенным, а по факту - выключен (или наоборот).
- Решение: добавьте `power_sensor` (например, от умной розетки или датчика потребления). SmartIR будет сверять фактическое состояние устройства с ожидаемым.
4. Некорректные режимы или невозможность выставить некоторую температуру
- Симптом: часть температур/режимов недоступна, либо при выборе определённой комбинации ничего не происходит.
- Решение: проверьте контент JSON‑файла устройства - возможно, выбранный `device_code` не полностью соответствует вашему кондиционеру; иногда помогает подобрать другой файл из той же линейки бренда и снова выполнить конвертацию.
---
Дополнительные возможности и расширения
После того как связка ZS05 + Zigbee2MQTT + SmartIR заработала, можно существенно расширить сценарии использования:
- Автоматизации по расписанию: включать кондиционер заранее перед приходом домой, снижать мощность ночью, отключать при открытии окна.
- Связка с датчиками качества воздуха: например, при превышении углекислого газа включать режим вентиляции или охлаждения.
- Управление несколькими устройствами: один ZS05 может обслуживать телевизор, кондиционер, приставку и ресивер, если ИК‑диоды "видят" все устройства. Для каждого создаются свои сущности SmartIR (climate, media_player и т. д.) с разными `device_code`, но с одинаковым `controller_data`.
- Групповое управление: можно сделать сцены, переключающие одновременно климат, освещение и мультимедиа (например, "режим кино" - погасить свет, включить проектор, задать нужную температуру).
---
Итог
Главная сложность при интеграции ZS05 с Home Assistant через SmartIR - это не сам Zigbee2MQTT и не Home Assistant, а комбинация двух нюансов:
1. Правильный MQTT‑топик для отправки ИК‑кода:
`zigbee2mqtt//set/ir_code_to_send`.
2. Необходимость конвертации стандартных Broadlink‑кодов SmartIR в формат Raw MQTT, который понимает ZS05.
Если эти два момента учтены, ZS05 превращается в универсальный и надёжный инфракрасный пульт для умного дома, позволяя управлять привычной техникой так же удобно, как "умными" устройствами, и вы больше не будете тратить время на бесконечные эксперименты с неработающими конфигурациями.
