企业官网建设流程全解析

ha_xiaomi_home：3步把米家设备接入Home Assistant，新手可上手

【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home

米家设备进不了 Home Assistant 仪表盘？先找堵点

米家空气净化器、小米灯，App 里都好使，但 PM2.5 进不了 Home Assistant 自动化，灯也没法从面板打开；社区集成不太稳。ha_xiaomi_home 是小米官方的米家设备接入桥，像餐厅：设备是后厨，面板是食客，本地、云端都支持。先看能力清单对路与否。

ha_xiaomi_home 能力一览：谁适合把米家设备接入 Home Assistant

这张表帮你 30 秒判断要不要继续往下看。

场景在表内就往下走；不在——比如蓝牙、红外、虚拟设备暂不支持——就不适合你。

米家设备接入 Home Assistant：3 步配置跑通 🍜

要求 Core 2024.4.4 及以上、Operating System 13.0 及以上。

把仓库克隆到服务器

先把代码放到 Home Assistant 所在的服务器。

cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home

此时你应该看到config/ha_xiaomi_home目录。

克隆完，下一件事是把它拷进组件目录。

跑安装脚本

安装脚本会把集成复制进custom_components。

cd ha_xiaomi_home ./install.sh /path/to/homeassistant/config

此时出现重启提示，重启 Home Assistant 即装好。

装好之后，接着用账号登录。

完成小米账号登录

设置 → 设备与服务 → 添加集成，搜 Xiaomi Home 授权登录。登录走 OAuth 2.0（授权码换取，密码不存进 Home Assistant），记得选对地区，否则设备导不出来。

登录成功后，选家庭。

勾选家庭导入设备

"选择家庭与设备"弹窗里勾选要导入的家庭，该家庭下设备全部进来。此时净化器和灯应已躺在实体列表里。

升级只需进克隆目录git fetch切到新 tag 再跑一次安装脚本；不满意同样切回旧 tag 回滚。流程跑完，值得看看它和设备到底怎么说话。

本地直连与云端推送机制：MQTT 通道原理拆解

拆解状态推送链路

状态像出菜：后厨做好就端上桌，食客不用反复探头问。集成在小米云的 MQTT Broker（消息中间人，把消息推给订阅了某个主题的人）上订阅设备消息，属性变化或事件发生时，properties_changed 等上行消息实时推过来；配置完成后只查一次全部属性，之后不轮询。

走小米云时的链路，状态往下、指令往上。

两条通道共用一条暗线：每台设备都带一份 MIoT-Spec-V2 描述，像后厨的菜单，决定哪些属性变传感器、哪些变开关。

拆解指令下发链路

指令反着走，像传菜单。云端模式经 MIoT Cloud 的 HTTP API（即发请求、对端收到后处理）发出；本地模式发布到中枢网关内置的 MQTT Broker，由网关转给设备，不出局域网。本地要求网关固件 3.3.0_0023 及以上，双通道同时可用时本地优先。

家里有中枢网关时，这条是主路。

记住：状态靠订阅通道往下推，指令从云端或网关往上走。跑起来之前，有几个坑值得提前记一下。

米家设备接入 Home Assistant 踩坑排查速查表 🔍

这张表覆盖接入米家设备时 90% 的常见报错。

想再深一层，把custom_components.xiaomi_home日志级别调成 debug 看内部行为，或改 multi_lang.json 和 spec_filter.yaml 后到集成配置里点"更新实体转换规则"。更细的映射规则，下一章的延伸阅读有。

延伸阅读：实体映射与源码继续深入

• 中文文档：MIoT-Spec-V2 到实体的完整转换表和过滤规则都写在这。
• miot 源码目录：云端、局域网、spec 解析的实现都在这里，看代码比看文档快。
• 英文 README 里另有官方消息原理与多账号配置说明。

跑通之后，把集成配置里的"debug mode for action"打开，手动给智能音箱发一条 Action 指令，完整感受一遍从菜单到实体的链路。

【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home