突破智能家居壁垒：小米IoT设备无缝接入Home Assistant全攻略
项目地址: https://gitcode.com/gh_mirrors/ha/ha_xiaomi_home 你是否还在为小米智能家居设备无法与Home Assistant完美协同而烦恼？是否经历过设备响应延迟、控制不稳定的糟糕体验？本文将带你深入了解Xiaomi Home Integration for Home Assistant与物联网平台的集成方案，通过本地化与云端双模式控制架构，实现小米生态设备与Home Assistant的无缝对接。读完本文，你将掌握从安装配置到高级调试的全流程技能，轻松构建稳定高效的智能家居系统。
方案概述：小米IoT与Home Assistant的完美融合
Xiaomi Home Integration for Home Assistant是由小米官方支持的Home Assistant集成组件，它允许用户在Home Assistant中使用小米IoT智能设备。该方案通过MIoT（小米IoT）协议实现设备通信，支持云端控制与本地控制两种模式，为不同网络环境和隐私需求的用户提供灵活选择。
项目核心优势：
- 官方支持：小米官方提供的集成方案，兼容性与稳定性有保障
- 双模控制：同时支持云端和本地控制，兼顾便利性与隐私安全
- 广泛兼容：支持全球多个地区
- 多语言支持：提供简体中文、繁体中文、英文等8种语言界面
环境准备与安装指南
系统要求
在开始安装前，请确保你的Home Assistant环境满足以下要求：
- Core版本 ≥ 2024.4.4
- Operating System版本 ≥ 13.0
这些要求在项目的manifest.json文件中有明确定义，确保了组件能够正常运行并与Home Assistant核心功能兼容。
安装方法
方法一：Git克隆安装（推荐）
这种安装方法便于后续版本更新和标签切换，执行以下命令：
cd config
git clone https://gitcode.com/gh_mirrors/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
方法二：通过HACS安装
- 在HACS中搜索"Xiaomi Home"
- 点击进入详情页并下载
- 重启Home Assistant
方法三：手动安装
- 下载项目文件
- 将
custom_components/xiaomi_home文件夹复制到Home Assistant的config/custom_components目录下 - 重启Home Assistant
配置流程：从登录到设备管理
账户登录与设备导入
- 进入Home Assistant设置 > 设备与服务 > 添加集成
- 搜索"Xiaomi Home"并点击下一步
- 点击登录链接，使用小米账号登录
- 登录成功后，在弹出的"选择家庭和设备"对话框中，选择要导入Home Assistant的设备所在家庭
图1：小米IoT设备云控制架构示意图
多用户登录配置
在完成一个小米账号的登录和配置后，你可以继续添加其他小米账号：
- 进入设置 > 设备与服务 > 已配置 > Xiaomi Home
- 点击"添加中枢" > 下一步
- 点击登录链接，使用其他小米账号登录
这种多账户管理功能特别适合管理不同家庭成员或不同地区的小米设备，所有设备可以统一显示在Home Assistant的同一区域中。
配置更新与调试模式
你可以在"配置选项"对话框中更改配置，包括更新用户昵称和从小米家庭APP导入的设备列表等：
- 进入设置 > 设备与服务 > 已配置 > Xiaomi Home
- 点击"配置" > 选择要更新的选项
当启用动作调试模式时，你可以手动向设备发送带参数的动作命令消息。发送动作命令的用户界面以文本实体形式显示，便于开发者和高级用户进行设备调试。
控制模式解析：云端与本地控制架构
云端控制架构
小米家庭集成在MIoT Cloud的MQTT Broker上订阅感兴趣的设备消息。当设备属性发生变化或设备事件发生时，设备向MIoT Cloud发送上行消息，MQTT Broker将订阅的设备消息推送到小米家庭集成。这种消息订阅机制使小米家庭集成在完成集成配置时仅从云端查询一次所有设备的属性，大大减轻了云端访问压力。
小米家庭集成通过MIoT Cloud的HTTP接口向设备发送命令消息以控制设备。设备在收到MIoT Cloud转发的下行消息后做出反应并响应。
图1：云控制架构示意图
本地控制架构
小米中央中枢网关包含标准的MQTT Broker，实现了完整的订阅-发布机制。小米家庭集成通过小米中央中枢网关订阅感兴趣的设备消息。当设备属性发生变化或设备事件发生时，设备向小米中央中枢网关发送上行消息，MQTT Broker将订阅的设备消息推送到小米家庭集成。
当小米家庭集成需要控制设备时，它向MQTT Broker发布设备命令消息，然后由小米中央中枢网关转发给设备。设备在收到网关的下行消息后做出反应并响应。
图2：本地控制架构示意图
两种模式对比与选择建议
| 控制模式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 云端控制 | 配置简单，无需额外硬件 | 依赖互联网连接，可能有延迟 | 无中央网关，对隐私要求不高 |
| 本地控制 | 响应速度快，保护隐私 | 需要小米中央中枢网关，仅限特定地区 | 有网关设备，注重隐私和响应速度 |
小米中央中枢网关仅在部分地区可用，其他地区用户可通过启用小米LAN控制功能实现部分本地控制。LAN控制功能只能控制与Home Assistant在同一局域网内的IP设备（通过WiFi或以太网电缆连接到路由器的设备），不能控制BLE Mesh、ZigBee等设备。
MIoT协议与Home Assistant实体映射
MIoT-Spec-V2协议解析
MIoT-Spec-V2（小米IoT规范版本2）是小米IoT平台制定的一种IoT协议，用于对IoT设备进行标准功能描述。它包括功能定义（其他IoT平台称为数据模型）、交互模型、消息格式和编码。
在MIoT-Spec-V2协议中，一个产品被定义为一个设备。一个设备包含多个服务。一个服务可能有一些属性、事件和动作。小米家庭集成根据MIoT-Spec-V2创建Home Assistant实体。
协议详细规范可参考MIoT-Spec-V2官方文档。
通用实体转换规则
小米家庭集成将MIoT设备的属性、事件和动作转换为Home Assistant实体，转换规则如下：
属性转换
| 访问权限 | 数据格式 | 值列表 | 值范围 | Home Assistant实体 |
|---|---|---|---|---|
| 可写 | 字符串 | - | - | Text（文本） |
| 可写 | 布尔值 | - | - | Switch（开关） |
| 可写 | 非字符串&非布尔值 | 存在 | - | Select（选择器） |
| 可写 | 非字符串&非布尔值 | 不存在 | 存在 | Number（数字） |
| 不可写 | - | - | - | Sensor（传感器） |
事件转换
MIoT-Spec-V2事件转换为Home Assistant中的Event（事件）实体。事件的参数也会传递给实体的_trigger_event。
例如，小米无线双键开关的MIoT-Spec-V2包含siid=2的开关传感器服务。当长按按钮时，服务的eiid=1014长按事件被触发，调试级别日志将打印Press and hold, attributes: {'Button Type': 1}，表示长按了右键。
动作转换
| 输入参数 | Home Assistant实体 |
|---|---|
| 空 | Button（按钮） |
| 非空 | Notify（通知） |
如果启用了动作调试模式，当动作规范中的"in"字段不为空时，将创建Text实体。实体详情页中的"属性"项显示输入参数的格式，为有序列表，用方括号[]括起来。列表中的字符串元素用双引号""括起来。
特定转换规则与示例
MIoT-Spec-V2使用URN定义类型，格式为urn:<namespace>:<type>:<name>:<value>[:<vendor-product>:<version>]，其中name是描述设备、服务、属性、事件和动作实例的人类可读单词或短语。
小米家庭集成首先根据实例的名称确定是否将MIoT-Spec-V2实例转换为特定的Home Assistant实体。对于不符合特定转换规则的实例，使用通用转换规则进行转换。
实体转换的具体实现可参考项目中的specv2entity.py文件。
高级功能与自定义配置
多语言支持与配置
小米家庭的配置流程语言选项有8种语言可供选择，包括简体中文、繁体中文、英文、西班牙语、俄语、法语、德语和日语。配置流程页面的简体中文和英文版已由开发者手动审核，其他语言为机器翻译。
如果你想修改配置流程页面中的词句，需要修改custom_components/xiaomi_home/translations/和custom_components/xiaomi_home/miot/i18n/目录中特定语言的json文件。
例如，中文翻译文件位于custom_components/xiaomi_home/translations/zh-Hans.json。
实体转换规则自定义
用户可以通过修改custom_components/xiaomi_home/miot/specs目录下的文件来自定义实体转换规则：
spec_filter.yaml: 用于过滤不会转换为Home Assistant实体的MIoT-Spec-V2实例spec_modify.yaml: 修改MIoT-Spec-V2实例的属性multi_lang.json: 补充或修改设备的多语言翻译
修改示例（spec_filter.yaml）：
urn:miot-spec-v2:device:television:0000A010:xiaomi-rmi1:
services:
- '*' # 过滤所有服务，相当于完全忽略具有此类MIoT-Spec-V2的设备
urn:miot-spec-v2:device:gateway:0000A019:xiaomi-hub1:
services:
- '3' # 过滤siid=3的服务
properties:
- '4.*' # 过滤siid=4服务中的所有属性
events:
- '4.1' # 过滤siid=4服务中的eiid=1事件
actions:
- '4.1' # 过滤siid=4服务中的aiid=1动作
修改任何规则文件后，需要在集成的配置页面更新实体转换规则才能生效：设置 > 设备与服务 > 已配置 > Xiaomi Home > 配置 > 更新实体转换规则。
调试与故障排除
当遇到设备连接或控制问题时，可通过以下步骤进行调试：
- 启用调试日志：在configuration.yaml中添加以下配置
logger:
default: critical
logs:
custom_components.xiaomi_home: debug
- 检查设备是否在支持列表中：参考项目文档或设备支持列表
- 验证网络连接：确保设备与Home Assistant在同一网络或可通过互联网访问
- 检查账号权限：确保小米账号具有设备控制权限
- 更新集成组件：确保使用最新版本的Xiaomi Home Integration
详细故障排除指南可参考项目的贡献指南。
安全与隐私保护
小米家庭集成及附属云接口由小米官方提供。用户需要使用小米账号登录才能获取设备列表。小米家庭集成实现了OAuth 2.0登录流程，不在Home Assistant应用中保存用户账号密码。
但由于Home Assistant平台的限制，成功登录后，小米账号的用户信息（包括设备信息、证书、令牌等）将以明文形式保存在Home Assistant配置文件中。用户需要确保Home Assistant配置文件的安全存储，配置文件的泄露可能导致他人以用户身份登录。
如果怀疑OAuth 2.0令牌已泄露，可通过以下步骤撤销小米账号的登录授权：小米家庭APP -> 我的 -> 点击用户名进入小米账号管理页面 -> 基本信息：应用 -> Xiaomi Home (Home Assistant Integration) -> 移除。
完整的安全说明可参考项目的LICENSE.md文件。
总结与展望
Xiaomi Home Integration for Home Assistant为用户提供了一个强大而灵活的解决方案，实现了小米IoT设备与Home Assistant的无缝集成。通过本文介绍的安装配置、设备管理、模式选择和高级自定义功能，用户可以构建一个稳定、高效且符合个人需求的智能家居系统。
随着物联网技术的不断发展，我们有理由相信未来小米与Home Assistant的集成将更加深入，带来更多创新功能和更好的用户体验。例如，更完善的本地化控制、更丰富的设备支持以及更智能的自动化场景。
如果你在使用过程中遇到任何问题或有改进建议，欢迎参与项目贡献，可通过CONTRIBUTING.md了解贡献指南。
最后，如果你觉得本文对你有帮助，请点赞、收藏并关注，以便获取更多关于智能家居集成的实用教程和最新动态！下期我们将带来"小米IoT设备自动化场景高级配置"，敬请期待。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
