打开格局、拥抱开源，米家智能设备接入 Home Assistant 平台技术原理和操作实战

原创 * 2024-12-30 08:19 上海

开源让世界更美好！

米家构建智能家居生态的新思路

近日，小米米家智能官方在GitHub上开源了“Home Assistant米家集成”项目，支持将小米米家 IoT 智能设备接入Home Assistant，实现云端控制和局域网控制，支持多账号登录，支持中国大陆、欧洲、印度、俄罗斯、新加坡和美国等多个地区，这也标志着米家在智能家居领域的进一步开放和合作。

Home Assistant 米家集成

Home Assistant 米家集成核心功能：

支持米家设备导入到 Home Assistant 管理

支持多账号同时登录

支持本地控制和云端控制

支持 Action 调试模式

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

Core ≥ 2024.4.4Operating System ≥ 13.0

米家官方推荐使用 Git 安装米家集成，便于版本更新管理

# 进入 Home Assistant 配置目录cd config
# 克隆项目代码git clone https://github.com/XiaoMi/ha_xiaomi_home.git
# 进入项目目录并运行安装脚本cd ha_xiaomi_home./install.sh /config

通过 Git 更新到特定版本，例如 v1.0.0：

cd config/ha_xiaomi_homegit checkout v1.0.0./install.sh /config

ha_xiaomi_home 目录结构：

miot：核心代码。miot/miot_client：每添加一个用户需要增加一个 miot_client 实例。miot/miot_cloud：云服务相关功能，包括 OAuth 登录、 HTTP 接口功能（获取用户信息、发送设备控制指令等）。miot/miot_device：设备实体，包含设备信息以及属性、事件、方法的处理逻辑。miot/miot_mips：消息总线，用于订阅和发布消息。miot/miot_spec：解析 MIoT-Spec-V2 。miot/miot_lan: 设备局域网控制，包括设备发现、设备控制等。miot/miot_mdns: 中枢网关服务局域网发现。miot/miot_network：获取网络状态和网络信息。miot/miot_storage: 集成文件存储。miot/test：测试脚本。config_flow：配置流程。

Home Assistant 米家集成原理

云端控制模式

Home Assistant 米家集成云端控制模式使用了MQTT Broker与小米云通信，支持实时设备状态更新。

米家集成向小米云 MQTT Broker 订阅关注的设备消息。当设备属性发生改变或产生设备事件时，设备向小米云发送上行消息， MQTT Broker 向米家集成推送订阅的设备消息。由于米家集成不需要向云端轮询以获取设备当前的属性值，因此米家集成能第一时间获知设备属性变化或事件发生。得益于消息订阅机制，米家集成只在配置完成时向云端查询一次所有的设备属性，对云端产生的访问压力很小。

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

本地控制模式

Home Assistant 米家集成本地控制模式需要设备与Home Assistant 保持在同一局域网内。

小米中枢网关内包含一个标准的 MQTT Broker ，实现了完整的订阅发布机制。米家集成向小米中枢网关订阅关注的设备消息。当设备属性发生改变或产生设备事件时，设备向小米中枢网关发送上行消息， MQTT Broker 向米家集成推送订阅的设备消息。

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

米家智能家居生态平台

小米米家智能已经接入了超过261个品类，6000多个型号的智能设备，设备激活量已超过5.27亿，为用户提供了丰富的产品选择。作为一个全面开放的平台，小米米家已经成为9000+企业的信任与选择。

小米米家的“Home Assistant米家集成”开源项目，为用户提供了更多的选择和可能性，用户能够根据自己的需求和喜好，创建属于自己的智能家居环境。例如，设置在特定时间段进行开关灯、洗衣服、煮饭等操作。

小米米家“Home Assistant米家集成”开源项目，已支持设备汇总：

智能灯泡和插座：如 Philips Hue、LIFX、Yeelight 等。

温控设备：如 Nest、Ecobee、Xiaomi 米家、Sonoff 等。

安防系统：如 Ring、Nest Camera、Xiaomi 门窗传感器等。

语音助手：支持与 Google Assistant、Amazon Alexa、Siri 等进行集成。

智能家电：如智能冰箱、洗衣机等。

传感器和监控设备：包括温度、湿度、空气质量、烟雾探测等。

Home Assistant 米家集成操作实战

小米账号登录

设置 > 设备与服务 > 添加集成 > 搜索“Xiaomi Home” > 下一步 > 请点击此处进行登录 > 使用小米账号登录。

修改跳转地址为我们本地IP即可访问

添加 MIoT 设备

登录成功后，会弹出会话框“选择家庭与设备”。您可以选择需要添加的米家家庭，该家庭内的所有设备将导入 Home Assistant 。

修改配置项

在会话框“配置选项”中，可选择需要变更的配置项。您可以修改用户昵称或更新从米家 APP 导入的设备列表。

方法：设置 > 设备与服务 > 已配置 > Xiaomi Home > 配置 > 选择需要变更的配置项

Action 调试模式

开启Action 调试模式后，您可手动向设备发送带参数的 Action 控制指令。发送带参数的 Action 控制指令的用户入口显示为一个文本实体。

方法：设置 > 设备与服务 > 已配置 > Xiaomi Home > 配置 > Action 调试模式

账号安全性

小米米家集成及其使用的云端接口都由小米官方提供，用户在使用时需要使用小米账号登录来获取设备列表。不过由于Home Assistant平台的限制，登录成功后，用户的小米用户信息（包括设备信息、证书、token等）会明文保存在Home Assistant的配置文件中。因此，你需要妥善保管自己的配置文件，防止信息泄露。