ha_xiaomi_home3步把米家设备接进Home Assistant的完整教程【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home小米家电散落在米家App里想集中管理却没有官方入口空气净化器还在米家App里调风速智能灯你想拉进Home Assistant的自动化扫地机的数据想进仪表盘找了一圈社区方案稳定性全看运气。小米官方的答案是ha_xiaomi_home由小米官方维护的米家集成直接把米家设备接入 Home Assistant本地直连、云端两种控制通道都支持现有设备不用换米家App里的配置也不用动。先盘清楚它替你解决了什么一句话定位小米米家设备通往 Home Assistant 的官方桥梁。官方出品集成和它调用的云端接口都由小米官方提供不用赌第三方集成的存活率。本地/云端双通道局域网里有中枢网关就走本地直连没有就走小米云两边都兜得住。状态主动推送设备属性一变就实时推到 Home Assistant不靠定时轮询状态不滞后。实体自动长出来它读每台设备的 MIoT-Spec-V2 功能描述自动生成 switch、sensor、climate 等实体不用手工映射。多账号汇到一处多个小米账号的米家设备可以导入同一个 Home Assistant 实例一个面板统一管理。这几点基本决定了你后面配置顺不顺手。看完这段你应该更关心怎么把它跑起来。三步跑通装组件、登录、勾选家庭第 1 步装组件。在 Home Assistant 所在服务器上操作前提版本是 Core 2024.4.4 及以上、Operating System 13.0 及以上cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/config脚本会把组件目录复制到custom_components下重启 Home Assistant 即装好。第 2 步登录。界面进设置 → 设备与服务 → 添加集成搜Xiaomi Home点下一步会跳到小米账号登录页。登录走 OAuth 2.0密码不落在 Home Assistant 里。注意要选对用户所在地区中国大陆、欧洲、美国等不同地区的设备在不同的云上选错就导不出设备。第 3 步勾选家庭。登录成功后弹出选择家庭与设备勾选要接入的米家家庭该家庭下的设备会被整体导入。刷新实体列表空气净化器和灯应该已经躺在里面了。以后想升级在克隆目录里拉取新 Tag 再跑一遍脚本即可cd config/ha_xiaomi_home git fetch git checkout 要切到的tag ./install.sh /path/to/homeassistant/config设备都接进来之后你大概会好奇它平时是怎么跟设备打交道的原理揭秘它凭什么又快又省心设备动态为什么总是最新订阅推送打个比方它像报刊订阅你订了什么出版社就给你递什么不用天天跑去报刊亭问我的那份到了没。对应到技术上集成在小米云的 MQTT Broker可以理解成一个消息中转站上订阅设备消息通道设备属性变化或事件触发时发出properties_changed、event等上行消息由 Broker 实时推给集成整个配置过程只在初始时向云端查一次全部属性之后不再轮询对云端的访问压力很小。控制指令则走反方向通过 HTTP 接口把set_properties、action消息发到云端再由云端转发给设备。指令怎么不出局域网中枢网关当居委会再打个比方家里的事在居委会就能办不用专门跑区里的大厅。小米中枢网关内置了一个标准 MQTT Broker需固件 3.3.0_0023 及以上集成直接向它订阅设备消息控制指令也发布到这个 Broker由网关转发给设备全程不出局域网。如果本地通道和云端通道同时可用中枢网关的本地控制优先。实体为什么各不相同一份出厂说明书每台 MIoT 设备都带一份 MIoT-Spec-V2 描述相当于出厂说明书写清楚它有哪些属性、事件、方法。集成照着说明书匹配内置映射规则可写的布尔属性变 switch不可读写的变 sensor事件变 event方法变 button 或 notify——这就是不同设备长出不一样实体组合的原因也是后面定制实体的入口。一句话记住状态靠通道推指令走云端或网关实体靠说明书长出来。答疑时间这几个坑先帮你填上 登录了但设备不显示→ 蓝牙、红外和部分虚拟设备暂不支持或登录时选错了用户地区 → 先在米家App确认设备已绑定该账号再在配置流程里选对地区重新导入。点开关要等半天→ 局域网里没有中枢网关指令只能绕道小米云 → 加装中枢网关后本地直连自动优先配置里的局域网控制开关不建议拿来顶替官方文档明确标注它可能引发异常。实体名是英文或者一堆没用的实体→ 云端翻译不全、冗余的 spec 实例没被过滤 → 改 specs 目录下的multi_lang.json和spec_filter.yaml再到集成配置里点更新实体转换规则生效。想同时管两个小米账号→ 一个账号一次只导入一套家庭 → 在 Xiaomi Home 配置页选添加中枢再登录另一个账号即可。想看看内部在干嘛→ 把custom_components.xiaomi_home的日志级别调成 debug推送和控制过程都能在日志里看到。想进一步查 MIoT-Spec-V2 到实体的完整转换表和过滤规则可以看仓库里的中文文档 doc/README_zh.md映射规则文件集中在 custom_components/xiaomi_home/miot/specs/。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考