Connecting Xiaomi Wi-Fi socket to Home Assistant: All ways + error solving

Xiaomi smart outlets (including Aqara and Mi Smart Socket) have long been an integral part of the smart home ecosystem, but integrating them with the Home Assistant often raises questions. Unlike standard management via the Mi Home app, connecting to HA opens up advanced automation scenarios, local control without the cloud, and compatibility with other devices. However, the setup process depends on the communication protocol: Wi-Fi outlets (such as Mi Smart WiFi Socket) require one approach, and Zigbee devices (Aqara Smart Plug) – a completely different approach.

In this article, we’ll look at all the current ways to add Xiaomi outlets to the Home Assistant, from official integration via Mi Home to local methods using MQTT or ESPHome. We’ll focus on common errors (like Device not found or token problems), and optimize your work to minimize delays. If you’re just starting out with HA or have already encountered difficulties adding a device, here you’ll find proven solutions.

1.What Xiaomi outlets are compatible with Home Assistant?

Before you start setting up, it is important to determine which model you are using. Xiaomi releases outlets with different communication protocols, and the method of integration depends on this:

• 📶 Wi-Fi sockets: Connect directly to the router. Examples: Mi Smart WiFi Socket (ZNCZ02LM/ZNCZ04LM), Mi Smart Plug (without Zigbee) Requires a cloud bridge or local hack.
• 🐝 Zigbee sockets: Operate through a gateway (e.g. Aqara Hub or Mi Gateway). Examples: Aqara Smart Plug (T1, SP-EUC01), Mi Power Plug Zigbee (ZNCZ12LM). Integrate through ZHA or Zigbee2MQTT.
• ⚡ Hybrid models: Rarely, but there are sockets that support both protocols (for example, some versions of Aqara for the Chinese market).

To find out your outlet model, look at the case or packaging – there is an article (for example, ZNCZ02LM). Also, information can be found in the Mi Home app in the Devices → Settings → Device.

Important! If your outlet is running through Mi Home but not identified by Home Assistant, check the protocol first. For example, many users try to add Aqara via Wi-Fi integration, even though it requires a Zigbee gateway.

2. Preparing Home Assistant to Add a Socket

Before connecting your device, make sure your Home Assistant system is ready to integrate.

• 📥 Home Assistant Version: No less than 2023.12 (for stable work with the latest versions of integrations). → System system → Information.
• 🔌 Network settings: Socket and server HA You need to be on the same local network. VLAN or guest network, temporarily disable the separation.
• 🔑 Mi Home Token: Wi-Fi sockets will require a Xiaomi account token (how to get it – read the next section).
• 🐝 Zigbee Coordinator: If you have a Zigbee outlet, you need an adapter (e.g. Sonoff ZBDongle-E or ConBee). II) firmware Zigbee2MQTT/ZHA.

It is also recommended that:

1. Create a backup of the HA configuration (Settings → Backups).
2. Update all integrations to the latest versions (Settings → Additions → Updates).
3. If you are using a Docker version of HA, make sure that the container has access to the host network.

Update Home Assistant to the current version|

Check the connection of the socket to the Wi-Fi | network

Download Mi Home token (for Wi-Fi sockets) |

Connect Zigbee adapter (for Zigbee sockets) |

Create a backup copy of the configuration-->

Warning: If you use Mi Home with servers in China, you will need a VPN or a change of account region to get the token.

3. Method 1: Connecting a Wi-Fi outlet through official Mi Home integration

This is the easiest method for Wi-Fi outlets (e.g. Mi Smart WiFi Socket ZNCZ02LM) and uses Xiaomi’s cloud API, so it doesn’t require complex manipulations, but depends on the stability of the company’s servers.

Adjustment steps:

1. Install Mi Home integration: Go to Settings → Devices & Services → Add Integration. Search for Mi Home and select Official Integration.

Xiaomi

Russia

China

Mi Home

After successful authorization, select the socket from the list of detected devices.

If the socket is not displayed:

• 🔄 Reset the socket (take out and paste back into the network).
• 🌐 Check that Mi Home is connected to the same account as in HA.
• 🔧 Integration settings Mi Home in HA Enable the option of Show Unsupported Devices.

💡

If you have an error “Invalid credentials” during authorization, try changing the password in your Xiaomi account to a simpler one (without special characters) or using an app password instead of the main one.

Limitations of the method:

• Dependence on the Xiaomi cloud – if server failures, management will disappear.
• Delays in execution of commands (up to 2-5 seconds).
• Impossibility of local government without the Internet.

Method 4: Local Wi-Fi connection via token (without cloud)

For those who want to get rid of cloud addiction, there is a method of connecting through the local API Xiaomi. It requires obtaining a device token, but provides instant response and work without the Internet.

Instructions:

1. Get a device token: How to get a Mi Home token? Install the Mi Home app on Android. Enable USB debugging and connect your phone to your PC. Use this script or Packet Capture to intercept the token when you connect to an outlet. Alternative: use Mi Home Token Extractor (requires root rights). The token is a unique 32-character key (e.g., a1b2c3d4e5f678901234567890abcdef), which identifies the device on the local network.
2. Add the socket to configuration.yaml: miio: devices: - host: 192.168.1.100 # IP-token: YOUR_TOKEN_HERE name: "Xiaomi Socket Living Room" IP-The address of the socket can be found in the router (section) DHCP Clients) or through a network scanner (e.g. Fing).
3. Reboot Home Assistant and check for device appearance in Settings → Devices.

Advantages of the method:

• 🚀 Instant response (delay) <1 seconds).
• 🔒 Working without the Internet.
• 🔧 Access to all parameters (power, voltage, if supported).

💡

The local method is only suitable for outlets with firmware that supports Miio Protocol (most models after 2018).

⚠️ Note: If after rebooting HA The outlet does not appear, check it out:

• Correctness IP-Addresses (it may change when reconnecting the socket).
• No firewall blocking ports 54321 (Miio Protocol used)
• The relevance of the token (when resetting the socket, the token changes!).

5. Method 3: Integration of Zigbee sockets (Aqara, Mi Power Plug Zigbee)

Xiaomi/Aqara Zigbee devices connect to Home Assistant via a gateway, with the most popular options being Zigbee Home Automation (ZHA) and Zigbee2MQTT. Let's look at both.

Option A: Through ZHA (Integrated Integration)

1. Connect a Zigbee adapter (such as Sonoff ZBDongle-E) to the HA server.
2. Enable ZHA integration: Go to Settings → Devices and Services → Add Integration → Zigbee Home Automation. Select the adapter port (e.g. /dev/ttyACM0).

• For Aqara Smart Plug: Hold the 5-second button until the light starts flashing.
• For Mi Power Plug Zigbee: Press the button 1 time, then again in 2 seconds.
• In the ZHA interface, press Add Device and wait for detection.

⚠️ Note: If the socket does not pair, check:

• 🔋 Signal level of Zigbee (should be) >-80 dBm. Use it. Zigbee2MQTT diagnostic.
• 🔄 Reboot the coordinator and the socket (take it off the network for 10 seconds).
• 📡 Make sure the adapter supports your model (e.g. ConBee) II It does not work with some Aqara devices).

Method 4: Alternative methods (ESPHome, MQTT)

If standard methods don’t work or you want maximum customization, consider these options:

A. Firmware via ESPHome (for power users)

Suitable for sockets based on the ESP8266/ESP32 chip (such as some Mi Smart Socket clones), it allows you to completely reflash the device and control it through HA without the cloud.

• 🔧 A soldering iron is required to connect to the socket contacts.
• 💻 Need firmware knowledge via esphome or Tasmota.
• ⚡ The risk of losing warranty and “killing” the device in case of error.