小米有格局——官方正式开源「Home Assistant米家集成」

小米在 GitHub 开源了「Home Assistant 米家集成」（Xiaomi Home Integration）项目，这是一个由小米官方提供支持的 Home Assistant 的集成组件，它可以让用户在 Home Assistant 中使用小米 IoT 智能设备。

开源地址：https://github.com/XiaoMi/ha_xiaomi_home

消息收发原理

• 云端控制

图 1：云端控制架构

由于米家集成不需要向云端轮询以获取设备当前的属性值，因此米家集成能第一时间获知设备属性变化或事件发生。

得益于消息订阅机制，米家集成只在配置完成时向云端查询一次所有的设备属性，对云端产生的访问压力很小。

米家集成需要控制设备时，通过小米云 HTTP 接口向设备发送控制消息。设备收到小米云发来的下行消息后做出响应。

• 本地控制

图 2：本地控制架构

小米中枢网关内包含一个标准的 MQTT Broker ，实现了完整的订阅发布机制。

米家集成向小米中枢网关订阅关注的设备消息。当设备属性发生改变或产生设备事件时，设备向小米中枢网关发送上行消息， MQTT Broker 向米家集成推送订阅的设备消息。

米家集成需要控制设备时，向 MQTT Broker 发布设备控制消息，再经由小米中枢网关转发给设备。设备收到小米中枢网关发来的下行消息后做出响应。

米家集成的 Home Assistant 版本要求：

• Core ≥ 2024.11.0

• Operating System ≥ 13.0

• 米家集成是否支持所有的小米米家设备？

米家集成目前支持大部分米家设备品类，但仍有一小部分设备品类（蓝牙、红外及虚拟设备）并不支持。

• 米家集成是否可以同时使用多个小米账号？

是的，米家集成支持多个小米账号同时登录。另外，米家集成还支持不同账号的米家设备添加至同一个 Home Assistant 区域。

• 米家集成是否支持本地化控制？

米家集成支持通过小米中枢网关（固件版本 3.4.0_000 以上）或内置中枢网关（软件版本 0.8.0 以上）的米家设备实现本地化控制。如果没有小米中枢网关或其他带中枢网关功能的设备，那么所有控制指令都会通过小米云发送。支持 Home Assistant 本地化控制的小米中枢网关（含内置中枢网关）的固件尚未发布，固件升级计划请参阅 MIoT 团队的通知。

小米中枢网关仅在中国大陆可用，在其他地区不可用。

米家集成也能通过开启小米局域网控制功能实现部分本地化控制效果。小米局域网控制功能只能控制与 Home Assistant 处于同一局域网内的 IP 设备（使用 WiFi、网线连接路由器的设备），无法控制蓝牙 Mesh、ZigBee 等协议接入的设备。该功能可能会引起一些异常，我们建议不要使用该功能。小米局域网控制功能开启方法：设置 > 设备与服务 > 已配置 > Xiaomi Home > 配置 > 更新局域网控制配置。

小米局域网控制功能不受地区限制，在全球范围内均可用。如果 Home Assistant 所在的局域网内存在中枢网关，那么即便米家集成开启了小米局域网控制功能，该功能也不会生效。

• 米家集成在哪些地区可用？

米家集成所用的云服务接口已部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国共六个地区的机房。

由于用户数据在不同地区的小米云上相互隔离，您需要在配置 Home Assistant 时选择用户所在地区，才能导入相应的米家设备。

米家集成支持将不同地区的米家设备添加至同一个 Home Assistant 区域。

Home Assistant 米家集成安装方法：
https://github.com/XiaoMi/ha_xiaomi_home/blob/main/doc/README_zh.md