Integrating Xiaomi’s ecosystem into a single smart home system through the Homebridge platform is one of the most popular requests among automation enthusiasts, allowing devices from different brands to be brought together under a single management, such as Apple’s HomeKit app, which doesn’t natively support many Chinese gadgets.
Unlike standard connectivity via the official Mi Home app, using Homebridge requires a dedicated server, most often running on the Raspberry Pi or Docker operating system. You will interact with the command line and configuration files of JSON. However, the result is worth it: you get local management without delay and independence from the manufacturer’s cloud servers.
Before you start setting up, make sure your lamp is already connected to the Wi-Fi network and successfully managed through a standard application. This is a basic requirement, since Homebridge does not create new devices, but only translates their status to another platform.
Preparing the server environment and installing Homebridge
The first step is to deploy the Homebridge platform itself on your device. If you use a Raspberry Pi, the easiest way is to install a finished Hassbian image or use an hb-service script. For Docker users, the process is even easier: just run the appropriate container with port port port drop and save configuration.
Once the basic software is installed, you need to access the web management interface, which is usually available at the address. http://IP-server-address:8585. Here you can manage plugins, logs and settings without directly editing text files, making life much easier for beginners. IP-address on your local network.
⚠️ Warning: Make sure your Homebridge server and smart lamp are on the same subnet. VLAN For IoT devices, you need to correctly pass multicast traffic, otherwise device detection will be impossible.
For stable operation of the system, it is critical that the Node.js version meets the requirements specified in the plugin documentation. Using outdated versions can lead to errors in the compilation of modules during installation.
Selecting and installing the right plugin
There are several plugins available to work with Xiaomi ecosystem devices, but the most versatile and supported is homebridge-miio or its modern forks, such as @miio/homebridge-xiaomi-miio.These plugins use the miIO protocol for local communication with devices, which ensures high response speed.
Installation is done through the plugin interface in the Homebridge web panel or through the terminal by the command npm install -g homebridge-miio. After installing the plugin, you need to go to the platform settings and add a new section for Xiaomi.
It’s important to understand the difference between plugins. Some emulate only basic features like on and off, while advanced versions allow you to control color temperature, brightness, and even scripts. Choose a solution with an active repository on GitHub to be sure of supporting new lamp models.
Obtaining a device token and access key
The most difficult step for many users is to get a unique device token, and this 32-character hexadecimal key is your pass for local lamp management, and without it, the plugin will not be able to log in to the device on your network.
There are several ways to mine a token, and the easiest way is to use root access on an Android smartphone and the Mi Home app, where the tokens are stored in a miio.db database. An alternative method is to use a miio Python script that intercepts a data packet when you add a device to the network.
Alternative method of obtaining a token through the Cloud API
Once you get the token, write it down, and you'll need it to fill out the configuration file. MAC-Device address, as some plugins use it to identify instead of name.
Configuring a configuration file config.json
The main magic happens in the config.json configuration file. This is where we prescribe the communication parameters between Homebridge and your lamp. The file has a strict JSON structure, so any syntax error, such as a missed comma, will cause the service to drop.
You need to add the XiaomiMiio platform to the platform array and specify the necessary parameters. Below is an example of the correct configuration structure for a single lamp.
{
"platform": "XiaomiMiio",
"name": "Xiaomi Lamp",
"devices": [
{
"name": "Living Room Lamp",
"address": "192.168.1.55",
"token": "ffffffffffffffffffffffffffffffff",
"model": "philips.light.bulb"
}
]
}☑️ Configuration check before launch
Note the model field. Different Xiaomi lamps (Yeelight, Philips, Mijia) may have different models. Using an incorrect model may cause the lamp to be defined as a switch without brightness adjustment. The list of supported models is usually available in the plugin documentation or in the logs when you try to autodetermine.
Types of devices and model compatibility
Xiaomi's ecosystem is vast, and not all lamps work the same way. Devices are divided into those that connect directly over Wi-Fi, and those that require a Zigbee gateway or Bluetooth. The homebridge-miio plugin is primarily focused on devices with a direct connection to the network.
If your lamp is running through a gateway, you may need a separate plugin for the gateway itself that will broadcast the status of the sensors and lamps connected to it. The table below shows popular models and their support status.
| Model of the device | Protocol | Support for plug-in | Functional |
|---|---|---|---|
| Yeelight White | Wi-Fi | Complete. | On/off, Brightness |
| Philips Bulb | Wi-Fi | Complete. | On/off, Brightness, Temperature |
| Mijia Bedside Lamp | Wi-Fi | Partial | On/off, Color (RGB) |
| Zigbee Bulb | Zigbee | Through the lock. | Depends on the lock. |
For Yeelight series devices, it is often recommended to use a dedicated homebridge-yeelight plugin, as it supports more features such as music mode and smooth color transitions that a standard miIO plugin may not see.
Diagnostics of problems and error solving
You may encounter errors in Homebridge logs during the setup process. The most common problem is Device offline or Invalid token. The first one indicates network problems, the second one indicates an error when entering the 32-character key. Recheck the token, symbol by symbol.
Another common situation is that the lamp stops responding after the router restarts. IP-address, and in configuration config.json It's written in old static. Solution: reserve. IP-address MAC-lamp addresses in settings DHCP your router.
💡
Use static. IP-This will save you 90% of the problems with loss of communication after a power failure or reboot of the router.
If the lamp is visible on the network but not controlled, try updating the device's firmware through the Mi Home app. Sometimes older versions of firmware have bugs in the implementation of the miIO protocol that are patched by the manufacturer.
⚠️ Attention: Frequent polling requests can overload Xiaomi budget lights. If you notice that the device often loses communication, increase the poll interval in the plugin settings with standard 5 second 10-15.
Advanced scenarios and automation
After successfully adding the bulb to Homebridge, it becomes available across all related systems, including Apple HomeKit, Google Home and Home Assistant, opening up opportunities to create complex scripts not available in the native app.
For example, you can adjust the lamp's response to a door opening or a change in the weather outside the window. In the Home app on iOS, you can create automations, where the Xiaomi lamp acts as a trigger or actuator along with other brands' gadgets.
💡
Homebridge’s core value is the ability to create cross-platform scenarios that combine devices that are not initially friendly with each other.
Also worth mentioning is the ability to manage via Siri. Phrases like "Siri, turn on the light in the living room" will work instantly, since Homebridge emulates Apple's native accessory.