小米官方开源「Home Assistant米家集成」小米 IoT 智能设备接入HA的方法

type

date

status

slug

summary

米家Home assistant官方开源地址

https://github.com/XiaoMi/ha_xiaomi_home

项目介绍显示，米家集成及其使用的云端接口由小米官方提供。用户需要使用小米账号登录以获取设备列表。

米家集成使用 OAuth 2.0 的登录方式，不会在 Home Assistant 中保存用户的小米账号密码。

但由于 Home Assistant 平台的限制，登录成功后，用户的小米用户信息（包括设备信息、证书、 token 等）会明文保存在 Home Assistant 的配置文件中。

因此，用户需要保管好自己 Home Assistant 配置文件。一旦该文件泄露，其他人可能会冒用用户的身份登录。

消息收发原理

云端控制

图 1：云端控制架构

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

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

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

本地控制

图 2：本地控制架构

小米中枢网关内包含一个标准的 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 所在的局域网内存在中枢网关，那么即便米家集成开启了小米局域网控制功能，该功能也不会生效。