小米智能家居接入 Home Assistant 实战指南
想要将家中的小米智能设备无缝集成到 Home Assistant 平台吗？本文提供一套完整的集成方案，从基础安装到高级配置，指导您实现跨品牌设备的统一管理。通过云端与本地双模式控制，您可以获得更稳定、更快速的体验。
集成前的准备工作
在开始之前，请确认环境满足以下条件：
- Home Assistant 设备（版本建议 ≥2024.4.4）
- 支持 Wi-Fi 或蓝牙的小米智能设备
- 有效的小米账号（用于云端认证）
- 局域网访问权限（用于本地发现）
三种主流安装方案
HACS 一键安装
这是最便捷的方式，适合大多数用户：
- 进入 HACS 界面
- 搜索 "Xiaomi Home" 集成
- 点击安装并重启 Home Assistant
- 在集成页面添加小米设备
Git 仓库克隆
如果您需要灵活管理版本，推荐此方法：
cd /config
git clone https://github.com/ha-xiaomi-home/xiaomi_home.git
cd xiaomi_home
./install.sh /config
手动文件复制
通过 Samba 或 FTP 服务，将 custom_components/xiaomi_home 文件夹复制到 Home Assistant 的 config/custom_components 目录下。
控制模式深度解析
云端控制架构
云端模式通过小米云服务管理设备，优势在于：
- 远程访问：随时随地控制家中设备
- 兼容性强：支持更多类型的小米设备
- 配置简单：适合初次使用的用户
核心配置文件位于：custom_components/xiaomi_home/miot/miot_cloud.py
本地控制架构
本地模式利用小米中枢网关在局域网内直接通信，特点如下：
- 极速响应：指令局域网传输，延迟更低
- 隐私安全：数据不经过云端
- 网络独立：断网也能控制设备
本地控制核心代码文件：custom_components/xiaomi_home/miot/miot_lan.py
配置流程逐步指导
账号登录与认证
在 Home Assistant 设置中，依次选择 "设备与服务" > "添加集成" > 搜索 "Xiaomi Home" > 点击 "小米账号登录"。
设备发现与导入
登录成功后，系统会自动弹出 "选择家庭与设备" 对话框，勾选要导入的设备即可。
多账号管理
完成首个账号配置后，可在已配置的集成页面继续添加其他小米账号，实现多账户统一管理。
支持设备类型
该项目支持丰富的小米智能设备，涵盖：
- 传感器：门窗、人体传感器等
- 照明：智能灯泡、台灯等
- 家电：智能插座、开关等
- 环境：空气净化器、加湿器等
- 清洁：扫地机器人、擦窗机器人等
实用配置技巧
设备发现优化
使用配置流程自动发现局域网设备，在 configuration.yaml 中添加相关配置项以增强稳定性。
多语言界面
项目提供完整的 13 种语言支持，包括简体中文、英文、日语等，配置文件位于 translations/ 目录。
自动化场景
利用 HA 的自动化功能，可创建以下场景：
- 离家模式：自动关闭所有灯光和设备
- 回家模式：根据预设自动开启相应设备
- 睡眠模式：智能调整卧室灯光和温度
常见问题排查
连接故障
- 检查设备网络连接状态
- 确认设备支持的控制协议
- 验证小米账号权限设置
响应延迟
- 优先使用本地控制模式
- 优化家庭网络环境
- 检查设备固件版本更新
高级功能与安全
自定义规格
通过修改设备规格文件，可以扩展支持更多设备类型：custom_components/xiaomi_home/miot/specs/spec_add.json
安全注意事项
集成采用官方 OAuth 2.0 登录流程，不会保存账号密码。但受限于 HA 平台机制，成功登录后小米账号信息将以明文形式保存在配置文件中，请务必妥善保管配置文件。
总结
许多用户已成功实现超过 50 个小米设备的统一管理。建议从基础设备开始集成，测试核心设备稳定性后，再根据实际需求添加高级功能。通过本指南，您可以将小米智能设备完美融入 Home Assistant 生态系统。
