Xiaomi Official Integration with Open-Source Home Assistant: New Smart Home Experience

title: Xiaomi Official Integration with Open-Source Home Assistant: New Smart Home Experience date: 2025-01-01 slug: mi-home-assistant authors: [kevinpeng] categories: - TV Boxes tags: - Home Assistant - TV Boxes - Xiaomi - IoT description: Detailed explanation of Xiaomi's official Home Assistant integration project. ha_xiaomi_home installation and configuration tutorial, supported device list, solving third-party integration delay issues, new smart home experience. cover: https://res.makeronsite.com/dashen-tech.com/mi-home-assistant-cover.webp

1. Brief Introduction¶

Hello everyone! Today we're talking about a project that excites smart home enthusiasts: Xiaomi Official Home Assistant Integration (ha_xiaomi_home). This project is developed and maintained by Xiaomi officially, aiming to provide Home Assistant users with a smoother and more reliable Xiaomi IoT device control experience.

In the past, although there were some third-party Xiaomi device integrations on the market, they had more or less some problems, such as device status response delays. Now, with official support, we can expect better performance and stronger security.

Home Assistant is an open-source home automation platform known for its powerful compatibility and flexibility, and is very popular among DIY enthusiasts. Now, Xiaomi, a giant in the smart home field, has also joined the Home Assistant ecosystem, which is undoubtedly an exciting thing.

Main Features:

Official Support: Developed and maintained by Xiaomi officially, providing better stability and compatibility.
Home Assistant Integration: Allows users to control and manage Xiaomi smart devices in Home Assistant.
Enhanced User Experience: Aims to provide faster device status response, solving delay issues in third-party integrations.
Wide Device Support: Supports most Xiaomi IoT devices, except Bluetooth, infrared, and virtual devices.
Multi-account and Region Support: Supports multiple Xiaomi accounts, and devices from different regions can be added to the same Home Assistant region.

2. Core Features¶

Multiple Installation Methods: Supports multiple installation methods, including Git clone, HACS, and manual installation. Official recommendation is to use Git clone as it facilitates version management and updates.
- Git Clone Installation: cd config; git clone https://github.com/XiaoMi/ha_xiaomi_home.git; cd ha_xiaomi_home; ./install.sh /config.
OAuth 2.0 Login: Uses OAuth 2.0 login method, does not directly store user passwords in Home Assistant, improving security.
Cloud Control and Local Control: Mainly controlled through Xiaomi cloud. For devices that support local control, can be controlled through Xiaomi gateway or LAN.
- Cloud Control: Communicates and controls through Xiaomi cloud servers.
- Local Control: Communicates directly in the local network through Xiaomi central gateway or LAN, but local control is not available in all regions.
  - Central Gateway: Only available in mainland China.
  - LAN Control: Applicable to all regions, but limited to IP devices only, and is experimental, not recommended for use.
Device Message Subscription Mechanism: Uses message subscription mechanism, when device properties change or events occur, messages are pushed to Home Assistant in real-time, reducing polling pressure on the cloud.
MIoT-Spec-V2 Mapping: Uses Xiaomi IoT protocol MIoT-Spec-V2 to map devices, services, properties, events, and actions to Home Assistant entities, ensuring normal device functionality.

3. Usage Tips¶

Multi-account Management: After completing login and configuration for one Xiaomi account, you can add other Xiaomi accounts through "Add HUB".
Region Selection: When importing Xiaomi devices, be sure to select the correct region, as data from different regions is isolated.
Debug Mode: Enable debug mode for actions to manually send action commands with parameters.
Entity Conversion Rule Updates: If you modify specv2entity.py, spec_filter.json, or multi_lang.json files, you need to update entity conversion rules in the integration configuration page for changes to take effect.
Custom Filtering: Use spec_filter.json file to filter MIoT-Spec-V2 instances that do not need to be converted to Home Assistant.
Localization: multi_lang.json file is used to provide localized translations for device names and other text elements, and takes priority over cloud translations.

4. Application Cases¶

Smart Lighting Control: Control brightness, color, and on/off status of Xiaomi smart bulbs through Home Assistant.
Smart Security: Combine Xiaomi smart cameras and sensors to achieve home security automation, such as sending alerts when abnormal movement is detected.
Environmental Monitoring: Use Xiaomi temperature and humidity sensors to monitor indoor environment in real-time, and automatically adjust air conditioning or heating based on temperature.
Automation Scenarios: Utilize Home Assistant's automation features to set various scenarios, such as "home mode", "away mode", etc., to achieve automated control of smart homes.

5. Security Concerns¶

Although Xiaomi's official integration uses OAuth 2.0 login method to improve security, there are still some security risks:

Plaintext Storage of User Data: Sensitive information such as user device information, certificates, and tokens are stored in plaintext in Home Assistant's configuration files. This means if the configuration files are leaked, others may access your Xiaomi devices.
Protect Configuration Files: You need to ensure your Home Assistant configuration files are properly safeguarded to prevent leakage.
Revoke Authorization: If you suspect OAuth tokens are leaked, you can revoke login authorization through the Xiaomi Home App.

Therefore, be sure to properly safeguard your Home Assistant configuration files to prevent leakage!

6. Common Questions¶

Which devices are not supported?
- Currently does not support Bluetooth devices, infrared devices, and virtual devices.
How to add multiple Xiaomi accounts?
- In the configured Xiaomi Home integration page, click "Add HUB" to add other Xiaomi accounts.
Is local control available in all regions?
- Local control through central gateway is only available in mainland China, while LAN control is applicable to all regions, but limited to IP devices only, and is not recommended for use.
Why does the official recommend Git clone installation?
- Git clone facilitates version switching and updates, easier to manage.
How to update the integration?
- You can switch to a specified version through Git clone, or update using HACS.
How to use custom configuration?
- You can edit spec_filter.json and multi_lang.json files for filtering and translation, and update entity conversion rules