al-one/hass-xiaomi-miot: Xiaomi devices in Home Assistant without YAML

What problem hass-xiaomi-miot solves for Home Assistant users

Xiaomi sells a large catalog of smart home hardware, and each product exposes its own set of properties and actions. Writing a Home Assistant integration per model does not scale, so this component reads MIoT-Spec, which the README describes as the protocol specification for Xiaomi IoT devices designed by the Xiaomi IoT platform to describe the function definition of hardware products. The integration uses the miot protocol to add Xiaomi devices to Home Assistant and states that it currently supports most Xiaomi IoT devices.

The audience is Home Assistant users who already own Xiaomi hardware and do not want to maintain YAML for every entity. The README points out that configuration happens through the HA Web UI, so a user can integrate devices without configuring yaml. That is the practical difference from a hand-rolled setup: the device model drives what entities exist, and you adjust behavior afterward through options and customization rather than writing the entity definitions yourself.

How miot-spec drives device discovery and entity creation

The integration is a custom component under custom_components/xiaomi_miot. Its manifest.json carries the version that the README badge reads, and the repository also ships core modules such as miot_local_devices.py, device_customizes.py and translation_languages.py. Those file names describe the split: a list of devices known to support miot-spec on the LAN, per-model customization defaults, and translation dictionaries.

When you add devices through a Mi account, the component filters devices according to the integration configuration and then decides how to talk to each one. The README describes three connection modes. Automatic regularly updates the list of devices that support miot-spec in LAN and uses the local connection for supported devices, which the README recommends. Local forces every filtered device onto the local connection, and the README warns that checking devices which do not support miot in LAN will leave them unavailable. Cloud sends everything through Xiaomi's servers, and the README recommends that mode for miio, BLE and ZigBee devices.

The data flow follows from that choice. Local mode means Home Assistant talks to the device on your network; cloud mode means requests go out to Xiaomi's APIs. The README notes that cloud configuration is for devices integrated by host and token, and that you can enable miot cloud per entity on top of an account-based integration.

Installing through HACS and adding a first device with host and token

The README lists four installation methods. HACS is the first: open HACS, go to Integrations, choose EXPLORE & DOWNLOAD REPOSITORIES, search for Xiaomi Miot and download the repository. Updates go through the same HACS entry with UPDATE or Redownload. The manual method copies the custom_components/xiaomi_miot folder into the custom_components folder of your Home Assistant config folder.

The third method runs a shell installer over SSH or the 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 -

The fourth method wraps the same installer in a shell_command so it can be triggered from Developer Tools. It goes into configuration.yaml:

shell_command:
  update_xiaomi_miot: |-
    wget -O - https://get.hacs.vip | DOMAIN=xiaomi_miot bash -

After restarting HA core, you call service: shell_command.update_xiaomi_miot from Developer Tools, then restart HA core again. Note that this method is an updater, not a first install path in the README text.

To add a device, open Settings, then Devices and Services, then Integrations, choose Add Integration and search for Xiaomi Miot. The README says the host and token path is suitable for devices that support miot-spec in LAN. For those devices you can also configure Xiaomi cloud credentials in 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

The commented keys are the ones the README documents: server_country defaults to cn and accepts de, i2, ru, sg, tw or us, and http_timeout is the timeout in seconds for requesting the Xiaomi APIs. What you should see after a successful setup is a device entry with entities generated from its miot-spec model, which you can then rename and customize.

Local mode and the subnet constraint that breaks it

The most concrete limitation in the README concerns Local mode. Some devices require Home Assistant to be on the same subnet or VLAN, and they will not respond to requests from a different subnet. The README offers a workaround: NAT your Home Assistant IP to the device's subnet. That is a network configuration change, not a setting in the integration, so it belongs in your decision before you adopt the component.

A second failure mode follows from the same section. If you pick Local mode and include devices that do not support miot in LAN, those devices become unavailable. The README states this plainly. Automatic mode exists to avoid that outcome, because it tracks which devices support local connections and falls back for the rest.

Cloud mode has its own cost, which the README does not quantify: requests go through Xiaomi's servers, so a device that is reachable on your network is still controlled through the internet, and the integration depends on Xiaomi's APIs staying reachable. The README also does not document rollback to an earlier release, so if an upgrade changes how your devices behave, you will not find a documented procedure for reverting in the README.

Customizing entities when the generated model is not what you want

Generated entities are a starting point, and the README documents several ways to adjust them. Per-entity customization uses Home Assistant's customize mechanism, included from a separate file:

homeassistant:
  customize: !include customize.yaml

xiaomi_miot:
  device_customizes:
    chuangmi.plug.212a01:
      miot_local: true
      chunk_properties: 7

The device_customizes block keys off the device model and points at device_customizes.py in the repository for the available options. The same block can be applied through a parent entity in customize.yaml, where the README lists keys including miot_local to force reading and writing in LAN for an account-based integration, miot_cloud for read, write and action, miot_cloud_write and miot_cloud_action for narrower cloud use, check_lan to check the LAN connection while in cloud mode, and miio_properties to expose miio properties as state attributes.

Sub-entities have their own key. sensor_properties on a parent entity creates sensors for named properties such as temperature, humidity and illumination. Translation is a separate concern: the language key currently supports only zh, and the translations block overrides strings globally or per mode, with examples for fan.mode and washer.drying_level. If your devices report modes that Home Assistant shows in Chinese or as raw values, that block is where you change the labels.

How it compares with Xiaomi Miio and Xiaomi Gateway 3 integrations

Home Assistant users who search for Xiaomi Miio or Xiaomi Gateway 3 are usually looking at the alternatives. Xiaomi Miio is the integration built around the miio protocol, which the README of this project names as one of the device classes it handles. The difference in approach is the model layer: this component reads miot-spec definitions to generate entities, while a miio-based integration exposes the properties that protocol defines. For a device whose functions are described in miot-spec, the generated entity set is the reason to pick this component.

Xiaomi Gateway 3 is a different scope again. It concerns the gateway hardware and the devices behind it, which is why the phrase appears alongside ZigBee searches. This component lists ZigBee among the supported device types and recommends Cloud mode for miio, BLE and ZigBee devices, so the two overlap on ZigBee hardware but do not solve the same problem. If your goal is the gateway itself rather than the devices it carries, the gateway-specific integration is the more direct fit; if your goal is a mixed set of Xiaomi devices in one integration, this component is the one that reads the shared specification.

Maintenance, licensing and what to verify before you rely on it

The repository is not archived, and the last push was on 2026-09-22. Releases are not on a fixed cadence: v1.1.3 and v1.1.4 landed a day apart in March 2026, then v1.1.5 arrived on 2026-09-07. Upgrades through HACS are a button press, and the shell_command method exists for people who want the update callable from Developer Tools, but the README does not describe how to pin or revert a version, so treat each update as something you confirm against your own devices.

The licence is Apache-2.0, which permits commercial and private use and requires that copyright and licence notices be preserved. That is the extent of what the repository states; it is not legal advice, and if you redistribute the component inside a product you should read the licence text in the repository yourself. The README also points to a translations contribution path for anyone who wants to add languages beyond the built-in zh dictionary. Before depending on it, verify the two things the README leaves open: whether your specific device models are in the supported list for local connections, and what your setup does when a cloud API call fails, since the README documents the timeout key but not the retry behavior.

Editorial conclusion

Adopt it if your Xiaomi devices are mostly Wi-Fi, BLE or ZigBee models and you want them in Home Assistant through the UI instead of hand-written YAML. Skip it if you cannot put Home Assistant on the same subnet as the devices you want to control locally, or if you need a feature the README does not document, such as rollback to an earlier release. Before committing, install through HACS, add one device with the host and token, and confirm that it reports state and accepts commands in Local mode. If it does not, the connection mode is the first setting to check.

Frequently asked questions

Official sources

1. al-one/hass-xiaomi-miot on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases