如何快速集成小米智能家居到Home Assistant：2024完整指南

小米智能家居集成（ha_xiaomi_home）是由小米官方支持的开源项目，帮助用户将小米IoT智能设备无缝接入Home Assistant平台，实现本地化与云端双重控制方案，支持多区域设备管理和多账号登录。

📋 准备工作：Home Assistant版本要求

• Core ≥ 2024.4.4
• Operating System ≥ 13.0

确保你的Home Assistant满足以上最低版本要求，否则可能出现兼容性问题。

🚀 三种安装方法，新手也能一键搞定

方法1：Git命令行安装（推荐）

通过git clone命令快速部署，支持版本精确控制：

cd config
git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home.git
cd ha_xiaomi_home
./install.sh /config

版本更新示例（以v1.0.0为例）：

cd config/ha_xiaomi_home
git fetch
git checkout v1.0.0
./install.sh /config

方法2：HACS商店一键安装

在Home Assistant社区商店中搜索安装：
HACS > 集成 > 搜索"Xiaomi Home" > 下载

方法3：手动文件部署

1. 下载项目源码
2. 将custom_components/xiaomi_home文件夹复制到Home Assistant的config/custom_components目录下

🔧 详细配置步骤：从登录到设备管理

1. 首次登录配置

1. 进入Home Assistant设置 → 设备与服务 → 添加集成
2. 搜索"Xiaomi Home"并选择
3. 点击登录链接，使用小米账号完成OAuth授权
4. 选择需要导入的米家家庭（支持多家庭导入）

图1：小米智能家居云端控制架构示意图，支持实时消息推送

2. 多账号与多区域管理

• 多账号登录：在集成配置页面点击"添加中枢"，可添加多个小米账号
• 跨区域设备：支持中国大陆、欧洲、美国等6个地区的小米云服务，设备数据自动隔离

3. 高级配置选项

在集成配置页面可调整：

• 用户昵称修改
• 设备列表更新
• Action调试模式（开启后可手动发送设备控制指令）
• 局域网控制开关（需配合小米中枢网关）

🔍 技术原理：本地控制vs云端控制

云端控制（默认模式）

图2：云端控制数据流向，通过MQTT协议实现实时状态同步

• 优势：无需额外硬件，支持所有网络环境
• 原理：通过小米云MQTT Broker订阅设备状态，控制指令经HTTP接口转发

本地控制（需中枢网关）

图3：基于小米中枢网关的本地控制架构，延迟低至10ms

• 硬件要求：小米中枢网关（固件≥3.3.0_0023）
• 优势：断网可用，更低延迟，支持蓝牙/ZigBee设备
• 配置路径：集成设置 → 更新局域网控制配置

🛠️ 核心功能模块解析

设备实体转换逻辑

项目核心转换规则位于custom_components/xiaomi_home/miot/specs/specv2entity.py，实现MIoT-Spec-V2协议到Home Assistant实体的映射：

设备功能类型	转换后实体类型	示例
可写布尔属性	Switch	智能插座开关
取值列表属性	Select	空调模式选择
数值范围属性	Number	亮度调节
无参方法	Button	设备重启按钮

关键代码模块

• miot_client.py：用户会话管理核心
• miot_device.py：设备实体与状态处理
• miot_lan.py：局域网设备发现与控制
• config_flow.py：Home Assistant配置流程实现

❓ 常见问题解答

Q1：支持哪些设备类型？

A：支持WiFi设备（如空气净化器、扫地机器人），需中枢网关支持蓝牙/ZigBee设备。

Q2：如何解决设备离线问题？

A：

1. 检查网络连接与小米云服务状态
2. 重启Home Assistant或重新加载集成
3. 确认设备固件为最新版本

Q3：数据安全性如何保障？

A：所有用户数据存储在本地config/.storage目录，可通过小米账号页面撤销授权。

📚 扩展资源

• 官方文档：doc/README_zh.md
• 贡献指南：CONTRIBUTING.md
• 测试工具：test/目录下包含设备控制测试脚本

通过本指南，您已掌握将小米智能家居设备接入Home Assistant的完整流程。如需进一步定制设备实体转换规则，可修改miot/specs目录下的规范文件。