[opensourcedex]

hass-xiaomi-miot is a free, open source internet of things (iot) project written in Python and released under Apache-2.0. It has 6,133 GitHub stars, 865 forks and 929 open issues, and was last pushed 7 days ago. On this registry it ranks #5 of 41 tracked projects in Internet of Things (IoT), with 5 head-to-head comparisons available.

What is hass-xiaomi-miot?

hass-xiaomi-miot is a Home Assistant custom integration that connects most Xiaomi IoT devices — Wi-Fi, BLE and ZigBee — to Home Assistant through the miot protocol without any YAML, and it is built for Xiaomi and Mijia device owners who run their own Home Assistant instance.

What it is

hass-xiaomi-miot is a Python custom component for Home Assistant, shipped as the xiaomi_miot integration from the custom_components/xiaomi_miot folder and published under the Apache-2.0 licence. It is a HACS default repository and carries the topics custom-component, hass, home-assistant, home-assistant-integration, homeassistant, iot, miio, miot, miot-spec, smart-home, xiaoai and xiaomi. The component reads MIoT-Spec, the protocol specification the Xiaomi IoT platform uses to describe hardware product functions according to networking mode, product characteristics and usage scenario, and turns that description into working Home Assistant entities. Its homepage is miot-spec.com, and it documents itself in English and Simplified Chinese.

The concrete problem it solves is onboarding. Without an integration of this kind, adding Xiaomi hardware to Home Assistant means editing configuration.yaml and hand-maintaining entity definitions for each model, which breaks as soon as device firmware or the device list changes. This project replaces that manual YAML work with the Home Assistant config flow, so devices are discovered from a Mi Account and configured in the Web UI. It also solves the transport problem: Xiaomi devices split across Wi-Fi, BLE and ZigBee, so the integration offers three connection modes — Automatic, Local and Cloud — and in Automatic mode it regularly refreshes the list of LAN devices that support miot-spec, kept in custom_components/xiaomi_miot/core/miot_local_devices.py, and prefers a local connection for those devices.

Key capabilities

  • Account-based setup through the Home Assistant Web UI, reached via Settings > Devices and Services > Integrations > Add Integration > search for Xiaomi Miot, with no YAML required.
  • Device onboarding from a Mi Account, which imports the device list filtered by the integration configuration.
  • Three connection modes introduced in v0.4.4 — Automatic, Local and Cloud — selectable when integrating by account.
  • Automatic mode, which periodically updates the list of LAN devices supporting miot-spec in custom_components/xiaomi_miot/core/miot_local_devices.py and uses the local connection for them.
  • Local mode, which forces every filtered device onto a local connection and marks devices without LAN miot support as unavailable.
  • Cloud mode, which the README recommends for miio, BLE and ZigBee devices, plus Cloud, Local and Automatic behaviour exposed per integration entry.
  • Four installation paths: HACS, manual copy of the custom_components/xiaomi_miot folder over Samba or SFTP, a one-line shell installer using wget -O - https://get.hacs.vip | DOMAIN=xiaomi_miot bash -, and a shell_command service named update_xiaomi_miot.

Who uses it and how

  • Home Assistant operators running a mixed Xiaomi fleet of Wi-Fi, BLE and ZigBee hardware, who onboard everything in bulk through a single Mi Account integration entry.
  • Households that want local control: Automatic mode keeps LAN-capable devices on a local connection and only falls back to the cloud for the rest.
  • Users whose devices are miio, BLE or ZigBee hardware that cannot be reached in the LAN, and who therefore accept cloud connection for those devices.
  • Headless and remote installs, where the Samba/SFTP path, the SSH or Terminal & SSH add-on one-liner, and the shell_command.update_xiaomi_miot service allow installation and updates without a file manager.
  • Xiao Ai (xiaoai) voice hardware, listed among the project topics alongside the core miot identifiers.

Getting started

Install through HACS, where the project is a default repository, or copy the custom_components/xiaomi_miot folder into the custom_components directory of the Home Assistant config folder. Then open Settings > Devices and Services > Integrations > Add Integration, search for Xiaomi Miot, and sign in with a Mi Account.

How it compares

The registry facts list no paid products that this project replaces, and they name no competing Xiaomi integration. On the available evidence, it stands alone in this registry as the entry covering Xiaomi device integration for Home Assistant.

When to use it — and when not to

Self-hosting means running Home Assistant itself and keeping a custom component current, and devices without miot-spec LAN support become unavailable if Local mode is chosen. Cloud mode depends on Xiaomi's cloud rather than purely local control, and the repository carries 929 open issues, so anyone needing guaranteed local-only operation for BLE or ZigBee hardware should verify device support before committing. Anyone who does not run Home Assistant, or who will not hold a Xiaomi account inside that instance, should not pick it.

project readme (upstream, from github) — read inline

version releases stars issues HACS

Xiaomi Miot For HomeAssistant

English | 简体中文

MIoT-Spec: The protocol specification for Xiaomi IoT devices, is a standard designed by the Xiaomi IoT platform to describe the function definition of hardware products according to the networking mode of hardware products, the characteristics of product functions, the characteristics of user usage scenarios and the user's requirements for hardware product use experience specification.

This component uses the miot protocol to automatically integrate Xiaomi devices into HomeAssistant, and currently supports most Xiaomi IoT devices. And it supports HA Web UI, and you can easily integrate Xiaomi devices into HA without configuring yaml.

hass-xiaomi-miot-configs

Installation

Method 1: HACS
  • First installation

    HACS > Integrations > ➕ EXPLORE & DOWNLOAD REPOSITORIES > Xiaomi Miot > DOWNLOAD THIS REPOSITORY

  • Update component

    HACS > Integrations > Xiaomi Miot > UPDATE / Redownload

Method 2: Manually installation via Samba / SFTP

Download and copy custom_components/xiaomi_miot folder to custom_components folder in your HomeAssistant config folder

Method 3: Onkey shell via SSH / Terminal & SSH add-on
wget -O - https://get.hacs.vip | DOMAIN=xiaomi_miot bash -

# Or

wget -O - https://raw.githubusercontent.com/al-one/hass-xiaomi-miot/master/install.sh | ARCHIVE_TAG=latest bash -
Method 4: shell_command service
  1. Copy this code to file configuration.yaml
    shell_command:
  update_xiaomi_miot: |-
    wget -O - https://get.hacs.vip | DOMAIN=xiaomi_miot bash -
  2. Restart HA core
  3. Call this service: shell_command.update_xiaomi_miot in Developer Tools
  4. Restart HA core again

Config

⚙️ Configuration > Devices and Services > 🧩 Integrations > ➕ Add Integration > 🔍 Search Xiaomi Miot

Or click: Add Integration

Add devices using Mi Account:

Starting from the v0.4.4 version, the component has added support for selecting the connection device mode when integrated by account:

  • Automatic: The component will regularly update the devices that support miot-spec in LAN, and automatically use the local connection for the supported devices (recommended)
  • Local: All devices filtered by the integrated configuration will use local connection. If you check the devices that do not support miot in LAN, they will be unavailable
  • Cloud: All devices filtered by the integrated configuration will use cloud connection. It is recommended that miio, BLE, ZigBee devices use this mode

Note: For Local mode, some devices require Home Assistant to be on the same subnet/VLAN. They will not respond to requests from a different subnet. A workaround is to NAT your Home Assistant IP to the device's subnet.

Add device using host/token:

Suitable for devices support miot-spec protocol in LAN

Config Xiaomi Cloud:

Config Xiaomi cloud for the devices integrated by host/token

# configuration.yaml
xiaomi_miot:
  username: xiaomi_username
  password: xiaomi_password
  # server_country: cn # Location of xiaomi cloud: cn(default), de, i2, ru, sg, tw, us
  # http_timeout: 15   # Timeout (seconds) for requesting the xiaomi apis

⚙️ Configuration > Devices and Services > 🧩 Integrations > Xiaomi Miot > Options > ☑️ Enable miot cloud

Translations

Looking forward to your contribution.

# configuration.yaml
xiaomi_miot:
  language: zh # Using the built-in dictionary, currently only `zh` is supported
  # https://github.com/al-one/hass-xiaomi-miot/blob/master/custom_components/xiaomi_miot/core/translation_languages.py
  translations:
    # Global dictionary
    idle: '空闲'
    busy: '工作中'
    # Dictionary for specifying fan modes
    fan.mode:
      straight wind: '直吹模式'
      natural wind: '自然风'
    # Dictionary for specifying the drying modes of the washer
    washer.drying_level:
      moist: '微湿'
      extra: '特干'

Customize entity

# configuration.yaml
homeassistant:
  customize: !include customize.yaml

# Customize via device model
xiaomi_miot:
  # https://github.com/al-one/hass-xiaomi-miot/blob/master/custom_components/xiaomi_miot/core/device_customizes.py
  device_customizes:
    chuangmi.plug.212a01:
      miot_local: true
      chunk_properties: 7


# Customize via parent entity
# customize.yaml
domain.your_entity_id:
  miot_local: true        # Force to read and write data in LAN (integrate by account)
  miot_cloud: true        # Enable miot cloud for entity (read, write, action)
  miot_cloud_write: true  # Enable miot cloud (only write)
  miot_cloud_action: true # Enable miot cloud (only action)
  check_lan: true         # Check LAN connection in cloud mode
  miio_properties: power,battery # Get miio properties to state attributes
  miio_cloud_props: prop.power,event.dev_online

# Custom sub entities
domain.parent_entity_id:
  sensor_properties: temperature,humidity,illumination # Miot properties
  binary_sensor_properties: is_volume_muted,any_boolen_property
  switch_properties: on,power
  number_properties: volume
  select_properties: mode
  fan_properties: mode,fan_level
  cover_properties: motor_control

light.your_entity_id:
  color_temp_reverse: false # Reverse color temperature (Requires reload config entry)
  yeelight_smooth_on:  2000 # milliseconds (Only for Yeelights in local mode)
  yeelight_smooth_off: 3000 # milliseconds (Only for Yeelights in local mode)

climate.your_entity_id:
  bind_sensor: sensor.temperature_entity,sensor.humidity_entity # Sensor entities

camera.your_entity_id:
  video_attribute: 1   # https://github.com/al-one/hass-xiaomi-miot/issues/11#issuecomment-773054167
  keep_streaming: true # Continuously update stream address

cover.your_entity_id:
  closed_position: 5     # Change cover state to closed when position <= 5%
  deviated_position: 2   # Current position deviation 2% -> 0%, 98% -> 100%
  motor_reverse: true    # Reverse motor state (Requires reload config entry)
  position_reverse: true # Reverse motor position (Requires reload config entry)
  open_texts: Open,Up
  close_texts: Close,Down

media_player.mitv_entity_id:
  bind_xiaoai: media_player.xiaoai_entity_id # Bind xiaoai speaker for turn on TV

domain.your_entity_id_xxxx:
  interval_seconds: 30 # Seconds between each update state (Requires reload config entry)
  chunk_properties: 10 # Chunk miot properties on update state (LAN)
  reverse_state: true  # Reverse the On/Off state of a binary sensor

Filter entity attributes

Too many entity attributes will make your HA's database very large. If some entity attributes are useless to you, you can configure exclude_state_attributes to ignore them.

# configuration.yaml
xiaomi_miot:
  exclude_state_attributes:
    - miot_type
    - stream_address
    - motion_video_latest

YAML configuration reloading

This component has added support for configuration reloading (to avoid having to restart HomeAssistant instance after a YAML configuration change):

🔨 Developer tools > YAML Configuration > YAML configuration reloading > 🔍 Look for Xiaomi Miot (almost at the bottom of the list)

Supported Devices

Unsupported devices

This component uses the polling method to obtain the device state, so it cannot listen the events of some devices in real time.

Services

Since the HA support service response has been for some time, this component no longer triggers events starting from v0.7.18.

xiaomi_miot.set_property
service: xiaomi_miot.set_property
data:
  entity_id: camera.isa_hlc7_xxxx
  field: camera_control.on
  value: true
xiaomi_miot.set_miot_property
service: xiaomi_miot.set_miot_property
data:
  entity_id: camera.isa_hlc7_xxxx
  siid: 2
  piid: 1
  value: true
xiaomi_miot.get_properties
service: xiaomi_miot.get_properties
data:
  entity_id: camera.isa_hlc7_1ab7
  mapping:
    - siid: 2
      piid: 1
    - siid: 3
      piid: 2
  update_entity: true # Update to entity state attributes
xiaomi_miot.call_action
service: xiaomi_miot.call_action
data:
  entity_id: vacuum.dreame_p2259_entity_id
  siid: 4 # vacuum-extend
  aiid: 1 # start-clean
  params:
    - 18 # piid: 1 - work-mode
    - '{"selects":[[7,1,0,2,1]]}' # piid: 10 - clean-extend-data
xiaomi_miot.send_command
service: xiaomi_miot.send_command
data:
  entity_id: switch.your_entity_id
  method: set_power
  params:
    - on
xiaomi_miot.get_token
service: xiaomi_miot.get_token
data:
  name: Light # Keyword of device name in Mihome / IP / Model.
xiaomi_miot.intelligent_speaker
service: xiaomi_miot.intelligent_speaker
data:
  entity_id: media_player.xiaoai_lx04_xxxx
  text: Turn on the light
  execute: true # Execute text directive.
  silent: true  # Silent execution.
xiaomi_miot.xiaoai_wakeup
service: xiaomi_miot.xiaoai_wakeup
data:
  entity_id: media_player.xiaoai_lx04_xxxx
xiaomi_miot.renew_devices
service: xiaomi_miot.renew_devices
data:
  username: 80001234 # Xiaomi Account ID / Email / Phone
xiaomi_miot.request_xiaomi_api
service: xiaomi_miot.request_xiaomi_api
data:
  entity_id: sensor.your_entity_id
  api: /v2/plugin/fetch_plugin
  data:
    latest_req:
      api_version: 10070
      plugins:
        - model: brand.device.model

More services

Debug

Get Entity State Attributes

🔨 Developer tools > ℹ️ State > 🔍 Filter Entity

Get Debug Logs

# configuration.yaml
logger:
  default: warning
  logs:
    custom_components.xiaomi_miot: debug

⚙️ Configuration > ⚙️ System > ✍️ Logs

Obtain miio token

  • Use HomeAssistant Service
    1. Goto HomeAssistant service developer tool
    2. Select xiaomi_miot.get_token, Enter the keyword of device name
    3. Find the token from the HA notifications
  • Use MiHome mod by @vevsvevs
    1. Down apk from СКАЧАТЬ ВЕРСИЮ 7.x.x and install
    2. Start Mihome APP > Profile > Experimental features
    3. Check on Write custom log files and Enable app's debug mode
    4. Find the token from vevs/logs/misc/devices.txt after restart app
  • Xiaomi Cloud Tokens Extractor
    1. Download and run token_extractor.exe for Windows or install for Python
    2. Enter username, password and your server region
    3. Extracts tokens from your cloud account. Also reveals the bind_key for BT devices

Thanks

  • PyCharm
  • Dler (10% Discount coupon for new user: CXVbfhHuSRsi)

Frequently asked questions

Is hass-xiaomi-miot free to use?

hass-xiaomi-miot is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does hass-xiaomi-miot do?

Automatic integrate all Xiaomi devices to HomeAssistant via miot-spec, support Wi-Fi, BLE, ZigBee devices. 小米米家智能家居设备接入Hass集成

What is hass-xiaomi-miot written in?

hass-xiaomi-miot is primarily written in Python. Its source is publicly available at https://github.com/al-one/hass-xiaomi-miot, and it has 6,133 GitHub stars.