Project: add a Xiaomi/Mi Home device to Home Assistant, test it with python-miio, and fix VLAN and firewall issues (REJE

[ZerOne]

A practical project for getting a Xiaomi Home device (vacuum, purifier, humidifier or gateway) under local control in Home Assistant and diagnosing the usual problems. It follows the Home Assistant "Xiaomi Home" docs and the python-miio getting-started and troubleshooting pages as at October 2026. I have not repeated every step on my own devices. Token-retrieval methods change with the app, so check python-miio's current instructions and post corrections.

Step 1: Pair in the Xiaomi Home app

Install the Xiaomi Home app, sign in, and add the device there. The HA docs are clear that you should use the Xiaomi Home app, not a vendor-specific one like the Roborock app. Note the account region you use. If the device was previously paired in another app, reset its Wi-Fi and pair again in Xiaomi Home, which generates a new token.

Step 2: Give it a stable address

Create a DHCP reservation for the device in your router so its IP never changes. If you use an IoT VLAN, decide now whether HA will live there too (see Step 5).

Step 3: Add it in Home Assistant

1. Go to Settings > Devices & services > Add integration > Xiaomi Home (or accept it if it is shown as discovered).
2. Enter your Xiaomi Home account email and password and choose the same server region as in the app. The HA docs say HA then retrieves the connection info and token, and connects to the device over your local network.
3. Only use "Configure manually" if the account route fails. You will need the IP and the 32-character token (see Step 4).

Step 4: Check with python-miio (also how to get a token)

On a computer in the same subnet:

Code: Select all

pip install python-miio
miiocli discover

The python-miio docs say discovery runs two methods, handshake and mDNS. Handshake works on all miIO devices but gives no device type, and "may expose the token". If the token returned has characters other than all 0s or all fs, it is likely a valid token. Many newer devices return a blank token, in which case fetch it from the cloud with the micloud package:

Code: Select all

pip install micloud
miiocli cloud list

It asks for your username, password and a server locale (all, cn, de, i2, ru, sg, us), then lists your devices with their tokens. Use all if you are unsure of the region. Do not paste the output (it includes tokens) into forums or issues. The python-miio docs mention legacy methods as alternatives, but I have not checked whether they work with current app versions.

Then a quick test. Run miiocli --help to see the device types it supports and use the command group for your device type (the generic device group, for example, with --ip and --token options and an info command, as I understand it from the CLI help; check the help output on your version):

Code: Select all

miiocli --help
miiocli device --ip 192.168.20.15 --token YOUR_32_CHAR_TOKEN info

The python-miio docs also describe environment variables (MIROBO_IP and MIROBO_TOKEN) for their legacy vacuum tool, so you do not have to type the IP and token each time. The project notes it is in the middle of a big refactoring and that for modern MIoT devices the git version may be needed until 0.6.0, so check the current docs for your device type. A failure with "Unable to discover the device" usually means a subnet/VLAN problem or a wrong token (Step 5).

Step 5: VLANs and subnets

If HA and the device are on different subnets and the device does not respond (python-miio's error is "Unable to discover the device"), the documented fixes are:

• Same subnet for HA and the device. Simple, but you lose the segmentation.
• Dual-home the HA host (a second interface or VLAN interface in the IoT VLAN), with a local firewall on HA to restrict incoming connections from the IoT subnet, as python-miio advises.
• IP masquerading on the router's interface in the device's subnet, so requests appear to come from the same subnet. The docs call this the last resort, and it needs router access.

The devices that python-miio lists as affected include the Xiaomi IR Remote, some humidifiers and some Roborock models, so do not assume it will happen to yours.

Step 6: Block the internet but keep it stable (REJECT not DROP)

Many people block IoT devices from the internet. For vacuums, the HA and python-miio docs say that silently dropping packets can make the device software hang until a watchdog restarts it, so you see intermittent unavailability. Use a firewall REJECT rule for the device's outbound traffic instead of DROP. For example on a Linux iptables router (adapt to OPNsense, pfSense, OpenWrt or your own firewall's wording):

Code: Select all

iptables -A FORWARD -s 192.168.20.15 -o wan0 -j REJECT

Replace wan0 and the address with yours, and keep established-connection and local-network allow rules above this line. This is a firewall example only. Do not paste firewall rules into a production router without understanding them. Note that blocking internet will stop app control from outside the home and may stop firmware updates, so schedule a temporary unblock for updates.

Security checklist

• Keep tokens, the Xiaomi account credentials and the HA config backups private.
• Use a strong unique password and two-step verification on your Xiaomi account if it is offered for your region.
• Isolate cameras, vacuums and gateways in an IoT VLAN.
• Valetudo and rooting are separate, more advanced topics. Read the Valetudo "Why not Valetudo?" page and follow its installation guide for your exact model first.

Links

• Home Assistant: Xiaomi Home
• python-miio: getting started
• python-miio: troubleshooting
• python-miio on GitHub

Question for the group: how have you segmented your Xiaomi devices from the rest of your network, and which of the three VLAN options (same subnet, dual-home, masquerade) worked for you?