Xiaomi Gateway Integration in Domoticz: A Complete Guide with Step-by-Step Instructions

Xiaomi Mi Home Gateway (including Aqara Gateway, Mi Gateway) 2/3) In addition to the home automation system Domoticz opens up new ways to manage the smart home. Unlike the standard Mi Home application, Domoticz allows you to create complex scenarios, integrate devices from different brands and manage them through a single interface. However, the integration process often causes difficulties for users due to the features of the ZigBee protocol, the requirements for the gateway firmware and the nuances of configuration. MQTT-broker.

In this article, you will find the current instructions for 2026, taking into account changes in the firmware of the Xiaomi gateways and Domoticz updates (version 2023.2 and later). API (for Chinese-made locks) and through MQTT (Special attention is paid to solving common errors such as Error: Device not found or problems with obtaining a token gateway.

If you’ve previously tried to integrate a Xiaomi gateway into Home Assistant or OpenHAB, many steps will be familiar, but Domoticz has its own peculiarities – for example, the need to manually create virtual devices for some sensors. Prepare for the process to take from 30 minutes to 2 hours depending on the method chosen and the experience with the process. JSON-configuration.

1. Preparing Xiaomi Gateway for Integration

Before connecting to Domoticz, the Xiaomi gateway must be properly configured in the original Mi Home app.This is critical, as many users miss this stage, which leads to sync errors.

• 📱 Update the gateway firmware to the latest version via Mi Home. For Aqara Gateway models, check the version in Settings → About the device. 1.4.7_147 It may not support integration.
• 🌐 Make sure the gateway is linked to a Chinese server (Mainland China), which is required to obtain a token through informal methods. You can change the region when you add the device to Mi Home (select from the list of countries).
• 🔧 Enable Developer Mode in Mi Home: Go to your account profile → Settings → General. → Developer mode. Without that, you can't get a token.
• 📡 Check the gateway's Wi-Fi connection. It should be on the same network as the server with Domoticz. Use static. IP for the gateway (configure in the router) to avoid problems when restarting.

Pay special attention to obtaining a token, a unique gateway identifier, and you can use:

• 🖥️ The official method through Mi Home Open API (Developer registration is required on developer.mi.com).
• 🔍 Unofficial tools such as Mi Home Token Extractor (for Android) or Python scripts (for example, miio-cli).

⚠️ Note: If you use a firmware gateway for Russia or Europe, obtaining token through informal methods may be blocked, in which case the only option is to use firmware for the Chinese version or use it. MQTT-method (described in section 3).

2.Installation and configuration of Domoticz

To successfully integrate the Xiaomi gateway, the Domoticz server must be configured to work with ZigBee devices.

• 🖥️ Operating system: Linux (Ubuntu recommended) 22.04 LTS Debian 11), Windows 10/11, or Docker container.
• 📦 Domoticz version: 2023.2 or later (older versions do not support Mi Home) API).
• 🔌 Additional Dependencies: Python 3.8+, pip, Python-miio library.

Instructions for installing Domoticz on 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

After installing the main software, it is necessary to:

1. Run Domoticz and open a web interface at the address http://[IP-server address]:8080.
2. Go to Settings → Add a new device like the Mi Home Gateway.
3. Enter. IP-Gateway address, token (previously received) and save settings.

If the Mi Home Gateway is not listed, then your version of Domoticz is outdated. Update it or install the plugin manually via GitHub:

cd domoticz/plugins


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

⚠️ Note: When using a Docker container for Domoticz, make sure that the port is 9898 (mi-home API) not locked. Add a flag to the launch command. -p 9898:9898.

Domoticz Updated to Version 2023.2+|IP-gateway address fixed on router|Token gateway received and verified|Port 9898 is open on the server (for Docker)|The python-miio library is installed-->

3. Method 1: Connection via Mi Home API

This method is suitable for Chinese-based gateways and allows you to manage devices directly through the Xiaomi cloud.

• ⚡ Quick setup (10-15 minutes).
• 🔄 Automatic update of device statuses.
• 📱 Support for most sensors (Aqara, MiJia).

Connection algorithm:

1. In the Domoticz web interface, go to Settings → Equipment → Add.
2. Choose the Mi Home Gateway type.
3. Fill in the fields: IP Address - static IP Token - a unique gateway identifier (32 characters) Port - 9898 (default).

Add

If the devices are not displayed:

• 🔹 Check that the gateway is not asleep (click the button on the case).
• 🔹 Make sure that the gateway is linked to the same account from which the token was received.
• 🔹 In Domoticz logs (Settings) → Logs) look for Connection refused errors, which indicates a port lock.

💡

If, after adding a gateway to Domoticz, the sensors appear as Unknown, try manually specifying their type. → Devices, select the problem sensor and change it to the appropriate type (e.g. Temperature for the temperature sensor).

4. Method 2: Connection through MQTT (universal)

If the first method did not work (for example, due to regional firmware), use the MQTT-Broker.This method works with all Xiaomi gateways, including Aqara, but requires additional customization:

• 🌍 It works with any regional firmware.
• 🔄 More stable synchronization.
• 🛠️ Flexibility in setting up topics.

The setup will require:

1. Install MQTT-broker (e.g. Mosquitto):

sudo apt install -y mosquitto mosquitto-clients


sudo systemctl enable mosquitto




sudo systemctl start mosquitto

1. Set up Xiaomi gateway to send data to MQTT via OpenMQTTGateway firmware or script miio2mqtt.

Example of configuration for miio2mqtt (config.yaml):

devices:


- id: "192.168.1.100" # IP gateway




token: "YOUR_TOKEN_HERE" #Token gateway




model: "lumi.gateway.v3" #Glueway model




mqtt:




host: "localhost" #IP broker MQTT




port: 1883




user: "domoticz" # Login for MQTT (optional)




password: "password" # password (optional)




topic_prefix: "xiaomi" # Topics Prefix

Run the script:

npm install -g miio2mqtt


miio2mqtt -c /path/k/config.yaml

In Domoticz add new type equipment MQTT Client Gateway with LAN interface and specify:

• Remote Address - localhost (or IP broker).
• Port — 1883.
• Topic — xiaomi/# (or your prefix).

⚠️ Attention: When in use MQTT The data from the gateway is transmitted in plain form. If the broker is available from the Internet, set up encryption (TLS) authentication (user/password).

💡

MQTT-method is the only reliable way of integration for gateways with firmware Europe/Russia. It takes more time to set up, but it keeps things running smoothly even after Xiaomi firmware updates.

5. Set up devices in Domoticz

Once the gateway is successfully connected, Domoticz will have new devices, but they may require additional configuration.

Temperature and Humidity Sensors (Aqara Temperature Sensor)

These sensors are usually automatically detected, but sometimes displayed as Unknown.

1. Go to Settings. → Devices.
2. Find a sensor called lumi.weather.
3. Click Change and select Temp type + Humidity.

5.2. buttons and switches (Mi Wireless Switch)

Xiaomi buttons (like Aqara Opple) in Domoticz are created as Selector Switch.

• Create a new Blockly script (Settings) → Additionally. → Scripts).
• Add the trigger device → [Name of the button] → On Action.
• In the action block, specify commands for other devices (for example, turning on the lights).

5.3 Motion Sensors (Aqara Motion Sensor)

For the correct operation of motion sensors:

• Set Timeout (Time-Off) in the device settings (Settings) → Devices → [Sensor] → Time of inactivity Recommended value: 60 seconds.
• Create a script that will work when you change the status of the sensor from Off to On.

6. Solving typical problems

Even with the right setup, there can be errors, and the solutions to the most common problems are:

6.1 Connection refused (Connection refused)

Causes and solutions:

• 🔌 Gateway off or off: Check power and indicators on the case. Reset the gateway with a button on the back.
• 🔒 Port Lock: Make sure the port is locked 9898 (For Mi Home API) or 1883 (for MQTT) open in firewall: sudo ufw allow 9898/tcp sudo ufw allow 1883/tcp
• 🌐 Network mismatch: Domoticz gateway and server must be on the same subnet. Check with ping: ping 192.168.1.100

6.2 Devices are displayed as Unknown

This is a typical problem for new sensor models.

• 🔄 Update the plugin: Download the latest version of domoticz-mi-home-plugin with GitHub.
• 📝 Manual matching: In file mihome_devices.json (in the plugin folder, add a description of your device. Example for vibration sensor":"lumi.vibration.aq1", "name":"Aqara Vibration Sensor", "type":"Vibration" }
• 🔧 Use it. MQTT: Some devices (such as the Aqara Cube) only work correctly through the MQTT.

Delays in updating statuses

If the sensor data is updated with a delay (more than 5 minutes):

• ⚡ Check the server load: Run htop and make sure CPU/RAM not loaded 100%.
• 🔄 Reduce the polling interval: In the settings of the Mi Home Gateway plugin, set Poll Interval for 60 seconds (by default – 300).
• 📡 Check the signal quality of ZigBee: If the gateway is far from the sensors, use a ZigBee repeater (e.g., Aqara Range Extender).

⚠️ Warning: If after updating the firmware gateway Xiaomi stopped responding, reset it to factory settings (hold the button 10 seconds) and repeat the procedure for obtaining token.

7. Optimization and automation

After successfully integrating the Xiaomi gateway into Domoticz, you can set up automation. Here are some useful scenarios:

Smart lighting with motion sensor

Example of scenario for turning on light when motion is detected:

1. Create a new script in Blockly (Settings) → Additionally. → Scripts).
2. Add the trigger: The device → [Motion sensor] → On.
3. Add action: Device → [Smart lamp] → On.
4. Add the delay: Wait → 5 minutes.
5. Add action: Device → [Smart lamp] → Off.

Water leak alerts

The Aqara Water Leak Sensor:

• Create a script with a trigger Device → [Water sensor] → Wet.
• Add Actions: Send notifications to your phone via Telegram or Pushbullet. turn on the siren (Aqara Alarm) or smart socket with a pump.

Geolocation office

To automatically turn on the heating when returning home:

• Use the Domoticz plugin GPS tracking the location of the smartphone.
• Create a script with the condition: [GPS device] → In the Home Zone".
• Add action: Device → [Smart heater] → On.

Important: Geolocation requires a static external IP-address DDNS (For example, through No-IP, because Domoticz must be available from the Internet to update the status. GPS.

8. Alternative methods of integration

If standard methods do not work, consider alternatives:

8.1 Use of Home Assistant as an intermediate link

Home Assistant has more advanced support for Xiaomi devices.

1. Connect the gateway to Home Assistant via MQTT Mi Home API.
2. Integration of Home Assistant with Domoticz REST API or MQTT.

8.2. Gateway firmware on OpenMQTTGateway

For advanced users:

• Flush the Xiaomi gateway to the alternative firmware OpenMQTTGateway (supports ZigBee, BLE, RF).
• Set up data transfer directly to Domoticz via MQTT.

⚠️ Warning: Firmware gateway to custom software voids warranty and may cause device failure.

FAQ: Frequent questions