Xiaomi Humidizer Integration in Home Assistant: A Complete Guide with Examples

Xiaomi’s smart humidifiers are some of the most popular devices for creating a comfortable microclimate in the home. However, their full potential is only revealed when integrated with smart home systems such as Home Assistant. Unlike the standard Mi Home app, Home Assistant allows you to flexibly configure automation, link the humidifier to other sensors (such as hygrometers or thermostats), and control it through voice assistants.

In this article, we will look at all the possible ways to connect Xiaomi humidifiers (including Mi Air Humidifier, Smartmi and Viomi models) to the Home Assistant, from getting a token to configuring automatic scripts. We will focus on solving common errors such as Unable to connect or status update issues. If you have tried to integrate the device but have encountered difficulties, here you will find proven solutions.

Important: the integration process depends on the humidifier firmware and the Home Assistant version. We updated the instructions for Home Assistant 2026.6+ and the latest versions of Xiaomi firmware (including devices with support for BLE and Wi-Fi).

1.Preparation: What will be needed for integration

Before you start setting up, make sure you have everything you need. Without some components, integration will be impossible.

• 📱 Xiaomi Humidifier with Wi-Fi support or BLE (see below for a list of compatible models).
• 🖥️ Home Assistant version 2023.12 or later (recommended 2026.6+).
• 📲 Mi Home App (to obtain a device token).
• 🌐 Stable Internet connection (the humidifier must be connected to the same network as the Home Assistant).
• 🔧 Additional tools: Mi Home Token Extractor (for Android) or Python script for iOS.

If your humidifier is only BLE-powered (e.g. Smartmi Air Humidifier JSQ-S03), you will need additional hardware – ESP32 with ESPHome firmware or Bluetooth Proxy in Home Assistant. For Wi-Fi models (e.g. Xiaomi Mi Air Humidifier CA1/CA4), a token from the Mi Home app is enough.

2. Obtaining a device token from Mi Home

The token is a unique identifier that allows Home Assistant to interact with the humidifier through the Xiaomi cloud. Without it, integration is impossible. There are several ways to get it, but the most reliable is using the Mi Home Token Extractor (only for Android).

If you have an iPhone, you have to take a workaround, either temporarily install Mi Home on an Android emulator (like BlueStacks), or use a Python script to intercept traffic, and we'll go into detail on both.

Method 1: Token Extractor for Android

1. Install the Mi Home Token Extractor app (available on GitHub).
2. Sign in to Mi Home with the same account that the humidifier is attached to.
3. Open Token Extractor, select your device from the list and copy the token.
4. Also write down Device ID (you will need it for configuration).

Method 2: Intercept traffic on iOS (via MITM-proxy)

This method is more complex and requires skills in Python and Charles Proxy:

git clone https://github.com/Maxmudjon/mihome_binary_protocol


cd mihome_binary_protocol




pip install -r requirements.txt




python miio_extractor.py

After launching the script, log in to Mi Home and wait for the token to appear in the console.

⚠️ Warning: Don't share your token with outsiders! It provides full access to device management. If the token is compromised, immediately reset the device to factory settings and get a new token.

3. Set up integration in Home Assistant

There are three main ways to connect Xiaomi humidifier to Home Assistant:

1. Xiaomi Miio integration (the easiest method)
2. MQTT (for advanced users)
3. Local control over BLE (for devices without Wi-Fi).

We recommend starting with the first method, and if it doesn't work (for example, because of regional constraints), move on to the second.

Method 1: Official integration of Xiaomi Miio

Add the following code to the configuration.yaml file:

miio:


devices:




- host: 192.168.1.100 # IP- address of the humidifier




token: YOUR_TOKEN_HERE # Token from the previous step




model: zhimi.humidifier.ca1 # Device model (see table below)

After saving the file, restart Home Assistant. The humidifier will appear in Settings → Devices.

Method 2: Integration through MQTT (alternative)

If the official integration doesn’t work, use MQTT with an intermediary broker (such as Mosquitto).

1. Install MQTT broker in Home Assistant (via Settings → Add-ons).
2. Set up Mi Home MQTT Bridge (GitHub instructions).
3. Add the device to configuration.yaml: mqtt: broker: core-mosquitto discovery: true

4. Solving common mistakes

Even with the right setup, you can run into problems. Here are the most common mistakes and their solutions:

• ❌ Unable to connect to the device — check IP- the humidifier address (which can change when you restart the router).
• ❌ Invalid token -- the token could change after the firmware update. Get a new one.
• ❌ The device appears as unavailable – make sure the humidifier and Home Assistant are on the same network.
• ❌ No humidity data - update the humidifier firmware via Mi Home.

If the humidifier is connected but does not respond to commands, try:

1. Reboot the device (turn off power for 10 seconds).
2. Update Home Assistant to the latest version.
3. Check the log for errors: tail -f /config/home-assistant.log | grep -i miio

⚠️ Warning: Smartmi JSQ-S03 and JSQ-S04 humidifiers often lose communication when using BLE. If the device is periodically disconnected, set Bluetooth Proxy on ESP32 and place it next to the humidifier.

5. Set-up of automation

Once integrated successfully, you can create automations for smart humidifier management, such as:

• 🌡️ Automatic switching on when humidity drops below 40%.
• 🕒 Shutdown at night (if noise level is critical)
• 🔄 Sensor coupling CO₂ (turn on at high carbon dioxide levels).

Example of automation to maintain humidity (add to automations.yaml):

alias: "Moisturiser: Moisture support"


trigger:




- platform: numeric_state




entity_id: sensor.bedroom_humidity




below: 40




action:




- service: humidifier.turn_on




target:




entity_id: humidifier.xiaomi_humidifier




- service: humidifier.set_mode




target:




entity_id: humidifier.xiaomi_humidifier




data:




mode: "auto"

A critical nuance: Xiaomi humidifiers do not support smooth humidity control through Home Assistant. Instead, use auto, medium or high modes, combining them with external sensors.

💡

To reduce the noise of the humidifier at night, create automation that switches it to silent mode from 23:00 to 7:00. To do this, add a time condition to the automation trigger.

6 Advanced capabilities: bundling with other devices

Home Assistant allows you to combine the humidifier with other devices to create complex scenarios.

• 🌿 Smart greenhouse: The humidifier is turned on when the soil sensor shows low humidity.
• 🏠 Energy saving: Turn off the humidifier when no one is home (according to geolocation data).
• 📊 Data visualization: plot humidity in Grafana or Home Assistant Dashboard.

Use template sensors to connect to sensors, an example of a sensor that takes into account both humidity and temperature:

template:


- sensor:




- name: "Comfort Level"




state: >-




{% if states('sensor.bedroom_humidity')|float < 40 and states('sensor.bedroom_temperature')|float > 22 %}




Dry




{% elif states('sensor.bedroom_humidity')|float > 60 %}




Humid




{% else %}




Normal




{% endif %}

And you can use this sensor to make more complex automations, like turning on the humidifier only if it's hot and dry in the room, but not touching it under normal conditions.

💡

For the stability of automation, use the source of truth, one major humidity sensor (like the Aqara TH Sensor), rather than the built-in humidifier hygrometer, which often gives inaccurate readings due to local evaporation.

7. Firmware Update and Security

Xiaomi regularly releases firmware updates for humidifiers that can break compatibility with Home Assistant.

• 🔄 Turn off automatic updates in the Mi Home app.
• 🛡️ Check the compatibility of new firmware on forums (e.g. Home Assistant Community).
• 🔄 Create a backup of the token and configuration before upgrading.

If the humidifier stopped working with Home Assistant after the update:

1. Get a new token (the old one could have changed).
2. Check if the model has changed in the MiOT documentation.
3. Roll back the firmware (if possible) via Mi Home or Service Mode.

⚠️ Warning: China Mainland firmware often has more features than global ones. However, installing it on EU/RU firmware devices can lead to lockdown. Use Mi Home in Chinese to safely change region.

FAQ: Frequent questions