Интеграция шлюза Xiaomi в Domoticz: полное руководство с пошаговыми инструкциями

Подключение шлюза Xiaomi Mi Home Gateway (включая модели Aqara Gateway, Mi Gateway 2/3) к системе домашней автоматизации Domoticz открывает новые возможности управления умным домом. В отличие от стандартного приложения Mi Home, Domoticz позволяет создавать сложные сценарии, интегрировать устройства разных брендов и управлять ими через единый интерфейс. Однако процесс интеграции часто вызывает сложности у пользователей из-за особенностей протокола ZigBee, требований к прошивке шлюза и нюансов настройки MQTT-брокера.

В этой статье вы найдёте актуальную инструкцию на 2026 год, учитывающую изменения в прошивках шлюзов Xiaomi и обновления Domoticz (версия 2023.2 и новее). Мы разберём два основных метода подключения: через протокол Mi Home API (для шлюзов с китайской прошивкой) и через MQTT (универсальный способ для любых регионов). Особое внимание уделено решению типичных ошибок, таких как Error: Device not found или проблемы с получением token шлюза.

Если вы ранее пытались интегрировать шлюз Xiaomi в Home Assistant или OpenHAB, многие шаги будут знакомы, но Domoticz имеет свои особенности — например, необходимость ручного создания виртуальных устройств для некоторых датчиков. Готовьтесь к тому, что процесс займёт от 30 минут до 2 часов в зависимости от выбранного метода и наличия опыта работы с JSON-конфигурациями.

1. Подготовка шлюза Xiaomi к интеграции

Перед подключением к Domoticz шлюз Xiaomi должен быть правильно настроен в оригинальном приложении Mi Home. Это критично, так как многие пользователи пропускают этот этап, чтоlater приводит к ошибкам синхронизации. Вот ключевые шаги:

📱 Обновите прошивку шлюза до последней версии через Mi Home. Для моделей Aqara Gateway проверьте версию в Настройки → Об устройстве. Прошивка ниже 1.4.7_147 может не поддерживать интеграцию.
🌐 Убедитесь, что шлюз привязан к китайскому серверу (Mainland China). Это обязательно для получения token через неофициальные методы. Изменить регион можно при добавлении устройства в Mi Home (выберите в списке стран).
🔧 Включите режим разработчика в Mi Home: перейдите в профиль аккаунта → Настройки → Общие → Режим разработчика. Без этого невозможно получить token.
📡 Проверьте подключение шлюза к Wi-Fi. Он должен быть в той же сети, что и сервер с Domoticz. Используйте статический IP для шлюза (настройте в роутере), чтобы избежать проблем при перезагрузке.

Особое внимание уделите получению токена (token) — уникального идентификатора шлюза. Для этого можно использовать:

🖥️ Официальный метод через Mi Home Open API (требует регистрацию разработчика на developer.mi.com).
🔍 Неофициальные инструменты, такие как Mi Home Token Extractor (для Android) или скрипты на Python (например, miio-cli).

⚠️ Внимание: Если вы используете шлюз с прошивкой для региона Russia или Europe, получение token через неофициальные методы может быть заблокировано. В этом случае единственный вариант — прошивка на китайскую версию или использование MQTT-метода (описан в разделе 3).

📊 Какой шлюз Xiaomi вы используете?

Mi Gateway 1/2

Mi Gateway 3

Aqara Gateway (E1/H1)

Другой

Не знаю модель

2. Установка и настройка Domoticz

Для успешной интеграции шлюза Xiaomi сервер Domoticz должен быть настроен с учётом специфики работы с ZigBee-устройствами. Минимальные требования:

🖥️ Операционная система: Linux (рекомендуется Ubuntu 22.04 LTS или Debian 11), Windows 10/11, либо Docker-контейнер.
📦 Версия Domoticz: 2023.2 или новее (в старых версиях отсутствует поддержка Mi Home API).
🔌 Дополнительные зависимости: Python 3.8+, pip, библиотека python-miio.

Инструкция по установке Domoticz на Ubuntu/Debian:

sudo apt update && sudo apt upgrade -y sudo apt install -y curl libusb-1.0-0-dev libssl-dev build-essential python3 python3-pip

sudo pip3 install python-miio

После установки основного ПО необходимо:

Запустить Domoticz и открыть веб-интерфейс по адресу http://[IP-адрес_сервера]:8080.
Перейти в Настройки → Оборудование и добавить новое устройство типа Mi Home Gateway.
Ввести IP-адрес шлюза, token (полученный ранее) и сохранить настройки.

Если в списке оборудования нет Mi Home Gateway, значит, ваша версия Domoticz устарела. Обновите её или установите плагин вручную через GitHub:

cd domoticz/plugins

git clone https://github.com/guino/domoticz-mi-home-plugin.git

⚠️ Внимание: При использовании Docker-контейнера для Domoticz убедитесь, что порт 9898 (используемый для Mi Home API) не заблокирован. Добавьте в команду запуска флаг -p 9898:9898.

Domoticz обновлён до версии 2023.2+|IP-адрес шлюза зафиксирован в роутере|Token шлюза получен и проверен|Порт 9898 открыт на сервере (для Docker)|Установлена библиотека python-miio-->

3. Метод 1: Подключение через Mi Home API

Этот метод подходит для шлюзов с китайской прошивкой и позволяет управлять устройствами напрямую через облако Xiaomi. Преимущества:

⚡ Быстрая настройка (10–15 минут).
🔄 Автоматическое обновление статусов устройств.
📱 Поддержка большинства датчиков (Aqara, MiJia).

Алгоритм подключения:

В веб-интерфейсе Domoticz перейдите в Настройки → Оборудование → Добавить.
Выберите тип Mi Home Gateway.
Заполните поля:
- IP Address — статический IP шлюза (например, 192.168.1.100).
- Token — уникальный идентификатор шлюза (32 символа).
- Port — 9898 (по умолчанию).

Нажмите Добавить и дождитесь появления устройств в списке.

Если устройства не отображаются:

🔹 Проверьте, что шлюз не спит (нажмите кнопку на корпусе).
🔹 Убедитесь, что в Mi Home шлюз привязан к тому же аккаунту, с которого получен token.
🔹 В логах Domoticz (Настройки → Логи) ищите ошибки типа Connection refused — это указывает на блокировку порта.

Ошибка	Причина	Решение
`Invalid token`	Неверный или устаревший токен.	Получите новый токен через Mi Home Token Extractor.
`Device not found`	Шлюз не отвечает на запросы.	Проверьте сеть, перезагрузите шлюз.
`Unsupported device`	Устройство не поддерживается плагином.	Обновите плагин или используйте MQTT.

4. Метод 2: Подключение через MQTT (универсальный способ)

Если первый метод не сработал (например, из-за региональной прошивки), используйте MQTT-брокер. Этот способ работает со всеми шлюзами Xiaomi, включая Aqara, но требует дополнительной настройки. Преимущества:

🌍 Работает с любыми региональными прошивками.
🔄 Более стабильная синхронизация.
🛠️ Гибкость в настройке топиков.

Для настройки потребуется:

Установить MQTT-брокер (например, Mosquitto):

sudo apt install -y mosquitto mosquitto-clients sudo systemctl enable mosquitto

sudo systemctl start mosquitto

Настроить шлюз Xiaomi на отправку данных в MQTT через прошивку OpenMQTTGateway или скрипт miio2mqtt.

Пример конфигурации для miio2mqtt (config.yaml):

devices: - id:"192.168.1.100" # IP шлюза token:"YOUR_TOKEN_HERE" # Token шлюза model:"lumi.gateway.v3" # Модель шлюза mqtt: host:"localhost" # IP брокера MQTT port: 1883 user:"domoticz" # Логин для MQTT (опционально) password:"password" # Пароль (опционально)

topic_prefix:"xiaomi" # Префикс топиков

Запустите скрипт:

npm install -g miio2mqtt

miio2mqtt -c /путь/к/config.yaml

В Domoticz добавьте новое оборудование типа MQTT Client Gateway with LAN interface и укажите:

Remote Address — localhost (или IP брокера).
Port — 1883.
Topic — xiaomi/# (или ваш префикс).

⚠️ Внимание: При использовании MQTT данные со шлюза передаются в открытом виде. Если брокер доступен из интернета, настройте шифрование (TLS) и аутентификацию (user/password).

5. Настройка устройств в Domoticz

После успешного подключения шлюза в Domoticz появятся новые устройства, но они могут требовать дополнительной конфигурации. Рассмотрим типичные случаи:

5.1. Датчики температуры и влажности (Aqara Temperature Sensor)

Эти датчики обычно определяются автоматически, но иногда отображаются как Unknown. Чтобы исправить:

Перейдите в Настройки → Устройства.
Найдите датчик с именем lumi.weather.
Нажмите Изменить и выберите тип Temp + Humidity.

5.2. Кнопки и выключатели (Mi Wireless Switch)

Кнопки Xiaomi (например, Aqara Opple) в Domoticz создаются как Selector Switch. Чтобы настроить сценарии:

Создайте новый Blockly-сценарий (Настройки → Дополнительно → Сценарии).
Добавьте триггер Устройство → [Имя кнопки] → On Action.
В блоке действий укажите команды для других устройств (например, включение света).

5.3. Датчики движения (Aqara Motion Sensor)

Для корректной работы датчиков движения:

Установите Timeout (время срабатывания) в настройках устройства (Настройки → Устройства → [Датчик] → Время бездействия). Рекомендуемое значение: 60 секунд.
Создайте сценарий, который будет срабатывать при изменении статуса датчика с Off на On.

Тип устройства	Тип в Domoticz	Дополнительные настройки
Датчик температуры (lumi.weather)	`Temp + Humidity`	Проверьте единицы измерения (°C/°F) в `Настройки → Локализация`.
Кнопка (lumi.sensor_switch)	`Selector Switch`	Настройте сценарии для каждого `On Action` (одинарное/двойное нажатие).
Датчик движения (lumi.motion)	`Motion Sensor`	Установите `Timeout` не менее 30 секунд.
Умная розетка (lumi.plug)	`On/Off`	Проверьте потребляемую мощность в `Утилиты → Электроэнергия`.

Как добавить виртуальное устройство для неupported датчика?

Если ваш датчик (например, Aqara Vibration Sensor) не поддерживается плагином, создайте виртуальное устройство:

Перейдите в Настройки → Дополнительно → Виртуальные устройства.
Выберите тип Sensor или Switch в зависимости от функций датчика.
Вручную привяжите устройство к MQTT-топику (если используете MQTT) или настройте сценарий для обработки его данных.

6. Решение типичных проблем

Даже при правильной настройке могут возникать ошибки. Ниже — решения наиболее частых проблем:

6.1. Шлюз не отвечает (`Connection refused`)

Причины и решения:

🔌 Шлюз выключен или не в сети: Проверьте питание и индикаторы на корпусе. Перезагрузите шлюз кнопкой на задней панели.
🔒 Блокировка порта: Убедитесь, что порт 9898 (для Mi Home API) или 1883 (для MQTT) открыт в фаерволе:
```
sudo ufw allow 9898/tcp
sudo ufw allow 1883/tcp
```
🌐 Несовпадение сетей: Шлюз и сервер Domoticz должны быть в одной подсети. Проверьте через ping:
```
ping 192.168.1.100
```

6.2. Устройства отображаются как `Unknown`

Это типичная проблема для новых моделей датчиков. Решения:

🔄 Обновите плагин: Скачайте последнюю версию domoticz-mi-home-plugin с GitHub.
📝 Ручное сопоставление: В файле mihome_devices.json (в папке с плагином) добавьте описание вашего устройства. Пример для датчика вибрации:
```
{
"model":"lumi.vibration.aq1",
"name":"Aqara Vibration Sensor",
"type":"Vibration"
}
```
🔧 Используйте MQTT: Некоторые устройства (например, Aqara Cube) корректно работают только через MQTT.

6.3. Задержки в обновлении статусов

Если данные с датчиков обновляются с задержкой (более 5 минут):

⚡ Проверьте нагрузку на сервер: Запустите htop и убедитесь, что CPU/RAM не загружены на 100%.
🔄 Уменьшите интервал опроса: В настройках плагина Mi Home Gateway установите Poll Interval на 60 секунд (по умолчанию — 300).
📡 Проверьте качество сигнала ZigBee: Если шлюз далеко от датчиков, используйте ZigBee-репитер (например, Aqara Range Extender).

⚠️ Внимание: Если после обновления прошивки шлюза Xiaomi перестал отвечать, сбросьте его к заводским настройкам (удерживайте кнопку 10 секунд) и повторите процедуру получения token. В некоторых случаях требуется перепрошивка на китайскую версию.

7. Оптимизация и автоматизация

После успешной интеграции шлюза Xiaomi в Domoticz можно настроить автоматизацию. Вот несколько полезных сценариев:

7.1. Умное освещение с датчиком движения

Пример сценария для включения света при обнаружении движения:

Создайте новый сценарий в Blockly (Настройки → Дополнительно → Сценарии).
Добавьте триггер: Устройство → [Датчик движения] → On.
Добавьте действие: Устройство → [Умная лампа] → On.
Добавьте задержку: Ждать → 5 минут.
Добавьте действие: Устройство → [Умная лампа] → Off.

7.2. Оповещения о протечке воды

Для датчика воды (Aqara Water Leak Sensor):

Создайте сценарий с триггером Устройство → [Датчик воды] → Wet.
Добавьте действия:
- Отправка уведомления на телефон через Telegram или Pushbullet.
- Включение сирены (Aqara Alarm) или умной розетки с насосом.

7.3. Управление по геолокации

Чтобы автоматически включать обогрев при возвращении домой:

Используйте плагин Domoticz GPS для отслеживания местоположения смартфона.
Создайте сценарий с условием: Если [GPS устройство] → В зоне"Дом".
Добавьте действие: Устройство → [Умный обогреватель] → On.

Важно: Для геолокации требуется статический внешний IP-адрес или настройка DDNS (например, через No-IP), так как Domoticz должен быть доступен из интернета для обновления статуса GPS.

8. Альтернативные методы интеграции

Если стандартные способы не подходят, рассмотрите альтернативы:

8.1. Использование Home Assistant как промежуточного звена

Home Assistant имеет более развитую поддержку устройств Xiaomi. Вы можете:

Подключить шлюз к Home Assistant через MQTT или Mi Home API.
Настроить интеграцию Home Assistant с Domoticz через REST API или MQTT.

8.2. Прошивка шлюза на OpenMQTTGateway

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

Прошейте шлюз Xiaomi на альтернативную прошивку OpenMQTTGateway (поддерживает ZigBee, BLE, RF).
Настройте отправку данных напрямую в Domoticz через MQTT.

⚠️ Внимание: Прошивка шлюза на кастомное ПО аннулирует гарантию и может привести к неработоспособности устройства. Рекомендуется использовать резервный шлюз для экспериментов.

FAQ: Частые вопросы

🔹 Можно ли подключить шлюз Xiaomi к Domoticz без токена?

Нет, token обязателен для обоих методов (Mi Home API и MQTT). Если вы не можете его получить, попробуйте:

Использовать шлюз с китайской прошивкой (Mainland China).
Восстановить token через резервную копию Mi Home (инструкции есть на форумах 4PDA).

🔹 Почему после обновления Domoticz шлюз перестал работать?

Обновление могло сбросить настройки плагина или изменить структуру конфигурационных файлов. Проверьте:

Версию плагина mihome (обновите вручную при необходимости).
Логи Domoticz на ошибки типа Plugin failed to start.
Права доступа к файлам плагина (chmod -R 755 /путь/к/plugins/mihome).

🔹 Как добавить датчик Aqara Door/Window Sensor, если он не определяется?

Для датчиков дверей/окон:

Убедитесь, что датчик спарен со шлюзом в Mi Home.
В Domoticz вручную создайте виртуальное устройство типа Door Contact.
Настройте сценарий, который будет менять статус устройства при получении данных по MQTT (топик обычно zigbee2mqtt/[ID_датчика]).

🔹 Можно ли управлять шлюзом Xiaomi из Domoticz через интернет?

Да, но требуется:

Настроить проброс портов на роутере для доступа к Domoticz (порт 8080 по умолчанию).
Использовать DDNS (например, No-IP или DynDNS) для динамического IP.
Настроить HTTPS и аутентификацию для безопасности (плагин Domoticz HTTPS).

Для MQTT также потребуется проброс порта 1883 и настройка шифрования.

🔹 Какие шлюзы Xiaomi лучше всего работают с Domoticz?

По отзывам пользователей, наименьшее количество проблем возникает со следующими моделями:

Модель	Поддержка в Domoticz	Примечания