Xiaomi MIoT smart home integration, free and open source
Xiaomi purifiers, humidifiers, fans, plugs and lights on the local network (MIoT).
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
Control your Xiaomi, Mi Home and Mijia Wi-Fi devices from Gladys, on your local network: air purifiers, humidifiers, dehumidifiers, fans, smart plugs, switches, lights, air quality monitors, and the sensors built into them. The integration reads the public MIoT specification of each model and translates its standard services into Gladys features: no model is coded by hand. It adds a dashboard widget, a maintenance trigger and a scene action.
The Xiaomi account is only used once, to list your devices with their local address and their token (the key each device needs). After that, everything stays on your network: Gladys talks to each device directly, like the Mi Home app does on your Wi-Fi.
It complements the other integrations of the store: the robot vacuums of the Mi Home app are driven by the Xiaomi Home integration, Roborock and Dreame robots by theirs. This integration leaves the vacuums out.
Developed without the hardware: feedback welcome. This integration was built and tested against real MIoT specifications (published by the homebridge-miot and hass-xiaomi-miot projects) and against simulated devices, not against a real purifier nor a real Xiaomi account. If something does not work as described, please say so on the Gladys forum or in the issues.
Not affiliated with Xiaomi. Xiaomi, Mi Home and Mijia are trademarks of their owners.
What you need
- Gladys Assistant 5.1.0 or later.
- Xiaomi Wi-Fi devices already set up in the Mi Home (Xiaomi Home) app, on the same network as Gladys.
- Either the e-mail (or phone number) and the password of the Mi Home account, and its region; or, for each device, its IP address and its token (32 hexadecimal characters), found with another tool.
- Internet access for Gladys at setup: the Xiaomi account (once) and miot-spec.org (once per model, to download its specification).
Set up
With the Xiaomi account
- Install the integration from the Gladys catalog.
- Open its Configuration and fill in:
- E-mail or phone number and Password of the Mi Home account;
- Region of the account: the server region chosen in the Mi Home app (Profile → Settings → Region). Europe by default; a device paired in another region is not listed;
- Refresh interval: how often each device is read, 15 s to 2 min (30 s by default);
- Language of the feature names: English, French, German or Spanish (French by default). The names of a device and of its features are given when you add it.
- Save. The integration logs in and imports the devices at once; to do it again later, click Import the devices of the Xiaomi account: the message under the button lists what was imported and what was left out.
- Two-step verification: if Xiaomi asks for it, the message gives a link. Open it in a browser, ask for the code there (SMS or e-mail), but do not type it on that page. Back in Gladys, type the code in the Verification code field and click Import the devices of the Xiaomi account again, within 15 minutes.
- Open the Discover tab: one device per Xiaomi device. Click Add, pick a room, save.
The password stays in the configuration of the integration; the tokens are
kept in its private volume (/data) and never shown again. You can empty
the password once the devices are imported: they keep working.
By IP address and token
No account, or a device the account does not list? In the Configuration screen, click Add a device by IP address and token, with the address of the device (your router lists it) and its token. The integration asks the device for its model, which also proves the token. The device appears in the Discover tab.
Other actions of the Configuration screen
- Diagnose the devices: for each device, its model, address, whether it answers, how many features were translated and which services were left out; and the miIO devices found on the network that the integration does not know.
- Forget a device and its token: removes a device from the integration (sold, replaced). Delete it in Gladys too.
The Gladys devices
Each device becomes one Gladys device, named after its Mi Home name (or its kind and the end of its id). Only what its specification declares is published:
| Feature | What it is | Devices |
|---|---|---|
| Power | On / off | Purifiers, humidifiers, fans, plugs, switches |
| Light | On / off | Lights |
| Mode | The mode list of the device (Auto, Sleep, Favorite…) | Purifiers, humidifiers, fans |
| Fan speed | A level list, or a slider | Purifiers, humidifiers, fans |
| Horizontal oscillation | Oscillation on / off | Fans |
| Vertical oscillation | Oscillation on / off | Fans |
| Target humidity | A list every 5 % | Humidifiers, dehumidifiers |
| Water level | Water left in the tank, in % | Humidifiers |
| Water tank empty | Yes / no | Some humidifiers |
| Target temperature | The setpoint, shown only | Heaters |
| Fault | What the device reports, or No fault | Most devices |
| Temperature | °C | Devices with a sensor |
| Humidity | % | Devices with a sensor |
| PM2.5 / PM10 | µg/m³ | Purifiers, monitors |
| CO2 | ppm | Monitors |
| Illuminance | lux | Devices with a light sensor |
| Filter life | % left | Purifiers |
| Filter time left | Days or hours | Purifiers |
| Battery | % | Battery monitors |
| Child lock | Locks the buttons of the device | Most devices |
| Power draw | Watts | Plugs with a power meter |
| Brightness | % | Lights |
| Color temperature | Kelvins, within the range of the model | Lights |
| Color | The colour of a colour light | Colour lights |
- A heater is shown, never driven: its power and setpoint are read only. A heater driven like a light by a scene, a dashboard or a voice assistant could heat an empty room or start next to something; use its own buttons or the Mi Home app.
- What the translation leaves out (the buzzer, the display, the indicator light, the vendor settings) is listed by Diagnose the devices and stays reachable with the Set a MIoT property scene action.
- When a device no longer answers, its badge says it is unreachable; it comes back by itself.
Dashboard widget
Add the Air quality widget to a dashboard and choose a device in its settings. It shows up to four live tiles (PM2.5, CO2, temperature, humidity, water level, filter life as a gauge, in this order), the state of the device (on, off or not answering), its mode and fan speed, a fault when there is one, and buttons:
- Turn on / Turn off, which switches the device whatever the widget showed (not on a heater);
- the first two modes of the device (for example Auto and Sleep); the running one has a tick icon.
Scenes
Trigger
Xiaomi device needs attention: fired once when a reason starts, and again only after it ended. Filters:
- Xiaomi device: one device, or any;
- Reason: Filter to replace (filter life at 10 % or less), Water tank empty (the tank alarm, or a water level at 0 %), Fault (the device reports a fault); empty for all.
The variables give the name of the device (device_name), the reason
(filter, water or fault) and a detail (the filter life, the fault
reported). The reasons in progress are remembered across restarts.
Action
Set a MIoT property: writes any writable property of a device by its
number on miot-spec.org (siid.piid, for example 6.1 for the buzzer of a
Mi Air Purifier 4), with a value as the specification expects (true /
false, a number or a text). The action refuses a property that does not
exist, is read only, or a value out of its range; and any heater. It gives
the value written to the next actions.
To find the numbers: open https://home.miot-spec.com/spec/<model> (for
example zhimi.airp.mb5), or run Diagnose the devices, which names the
services left out with their number.
Scene ideas
- Filter reminder: Xiaomi device needs attention, reason Filter to replace → send the message "{{device_name}}: filter at {{detail}}".
- Quiet nights: every day at 22:00 → set the Mode of the purifier to
Sleep, then Set a MIoT property
6.1=falseto mute its buzzer. - Breathe better: when the PM2.5 of the air monitor goes above 35 → turn the purifier on, mode Auto.
- Humidifier refill: Xiaomi device needs attention, reason Water tank empty → send a message, and turn the humidifier off.
Troubleshooting
- No device imported: check the region of the account (a Xiaomi account is tied to a region), and the message under the button: vacuums, Bluetooth and Zigbee devices are left out on purpose.
- "Xiaomi asks for a captcha": log in once to the Mi Home app from the same network, wait a few minutes, try again; or add the devices by hand.
- A device does not answer: check that it is on the same network as Gladys (a guest network or an isolated IoT VLAN blocks it), and give it a fixed address in your router. A device that changes address is found again within 15 minutes by a discovery broadcast sent by Gladys (UDP port 54321, which is why the install screen asks for this permission).
- "refuses its token": the device was reset or paired again in Mi Home, its token changed: click Import the devices of the Xiaomi account again.
- "specification missing": miot-spec.org has nothing for this model, or could not be reached; the integration tries again every 15 minutes. Old miIO-only models (before MIoT) are not supported.
- The integration logs what it finds and what does not answer (more with
LOG_LEVEL=debug): open its logs from the Gladys interface.
Limits
- Wi-Fi devices only: the Bluetooth and Zigbee devices that go through a Xiaomi gateway have no address of their own, and are left out.
- Robot vacuums are left out (see the Xiaomi Home, Roborock and Dreame integrations).
- Air conditioners, thermostats, kettles, cookers and other kinds are not translated yet: they appear only if they have one of the standard services above (a plug, a sensor…).
- No push: each device is read every 30 seconds by default, one grouped request per device; a change made in Mi Home shows up at the next reading.
- The Xiaomi servers are only called when you import the devices (and when the account details change); miot-spec.org once per model. Neither is needed afterwards.
- Developed without the hardware: the per-model differences that the specifications do not tell (some report their power in other units) may need adjustments; please report them.
Configuration settings
These are the settings Xiaomi MIoT asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Xiaomi account | section | No | The account is used once, to list your Wi-Fi devices with their address and token; then everything stays on the local network. Save, then run “Import the devices of the Xiaomi account” below. No account? Add a device by its IP address and token. |
| E-mail or phone number | string | No | The login of your Mi Home (Xiaomi Home) account. |
| Password | secret | No | |
| Region of the account | select | No | The server region chosen in the Mi Home app (Profile → Settings → Region). |
| Refresh interval | select | No | How often every device is read on the local network. |
| Language of the feature names | select | No | Names given to the devices when you add them, and texts of the integration. |
How to install Xiaomi MIoT in Gladys
- In Gladys, open Integrations: Xiaomi MIoT appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-xiaomi-miot:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-xiaomi-miot.
Xiaomi MIoT requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Xiaomi MIoT is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all external integrations
- Discover the native integrations built into Gladys
- Build and publish your own external integration
- Source code on GitHub — source of this documentation