Xiaomi’s Open‑Source Home Assistant Integration: Opportunities for Developers & Entrepreneurs

Project Background

ha_xiaomi_home is an open‑source integration for Home Assistant that enables control of Xiaomi IoT devices. It implements the MIoT‑Spec‑V2 protocol and supports local control via Wi‑Fi, MQTT, HTTP and OAuth 2.0.

Technical Requirements

Home Assistant Core version ≥ 2024.4.4

Home Assistant OS version ≥ 13.0

Xiaomi central hub firmware ≥ 3.4.0_0000 or built‑in hub software ≥ 0.8.0 for local control

Supported languages: Simplified Chinese, Traditional Chinese, English and five other languages

Repository Structure

The GitHub repository ( https://github.com/XiaoMi/ha_xiaomi_home) contains three main modules:

miot_core – implementation of MIoT‑Spec‑V2, device discovery and data parsing.

cloud_interface – OAuth 2.0 authentication, cloud API wrappers.

device_manager – entity registration, state handling and service definitions.

Installation Options

Three common installation methods are supported:

Git clone

git clone https://github.com/XiaoMi/ha_xiaomi_home.git
cp -r ha_xiaomi_home/custom_components/ha_xiaomi_home <config_dir>/custom_components/
# Restart Home Assistant

HACS (Home Assistant Community Store) Add the repository URL in HACS → Integrations → “Add custom repository”, select “Integration”, then install.

Manual upload Upload the ha_xiaomi_home folder via Samba or FTPS to <config_dir>/custom_components/ and restart.

Key Technical Features

Supports local control through MIoT‑Spec‑V2, reducing latency and dependence on cloud services.

OAuth 2.0 flow for cloud‑based device management when local hub is unavailable.

Device discovery via multicast DNS (mDNS) and MQTT topics.

Extensible entity model allowing addition of new device types by extending the miot_core module.

Development Considerations

Contribution guidelines require Google style, clear PR descriptions, and passing existing unit tests.

Non‑Xiaomi devices can be integrated only after implementing the MIoT‑Spec‑V2 data model and registering the device type in miot_core.

Some cloud‑only features need a Xiaomi account and are limited to mainland China.

Reference Links

GitHub repository: https://github.com/XiaoMi/ha_xiaomi_home Home Assistant documentation: https://www.home-assistant.io/ MIoT‑Spec official specification:

https://iot.mi.com/new/doc/standard/miot-spec/spec

Illustration