ha_xiaomi_home：3 步把米家设备接入 Home Assistant，小白也能跑通
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
你买了台空气净化器、一盏智能灯，在米家 App 里控制没问题，想拉进 Home Assistant 的自动化里，却发现没有官方入口，社区方案稳定性全看运气。
ha_xiaomi_home 就是小米官方给出的答案：一个官方支持的集成组件，把米家设备接入 Home Assistant，本地、云端两种控制方式都支持。设备不用换，米家配置也不用改。
能力速览：一个集成收编米家设备
它本质是把小米 IoT 设备接进 Home Assistant 的桥。
- 多账号统一导入：多个小米账号的设备能进同一个实例，一个仪表盘统一管
- 实体自动生成：读设备的MIoT-Spec-V2描述，自动转成 switch、sensor 等实体，不用手工映射
- 实体名多语言：支持 13 种语言，属性名自动翻译，中文界面开箱就是中文
- 本地/云端双通道：局域网有中枢网关走本地直连，没有就走小米云
- 状态推送不轮询：设备属性一变就主动推过来，状态不滞后
实体组合可定制，改 specs 目录 的字典与过滤规则即可。下面把它跑起来。
上手路径：3 步接入
前置条件：Home Assistant Core 2024.4.4 及以上、Operating System 13.0 及以上。第 1 步，拿代码，在 Home Assistant 所在机器执行：
cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/your/config组件被复制到 custom_components 目录，重启后集成列表里出现 Xiaomi Home。
第 2 步，登录。进设置 → 设备与服务 → 添加集成，搜 Xiaomi Home，跳转小米账号登录页。登录走OAuth 2.0，密码不存进 Home Assistant。注意选对用户所在地区，选错就导不出设备。
第 3 步，选家庭。登录成功弹出"选择家庭与设备"，勾选要接入的米家家庭，该家庭下的设备全部导入。
成功信号：刷新设备列表，空气净化器已经躺在实体列表里。升级或回滚：在克隆目录切到目标 tag，再跑一次安装脚本。
跑通之后，你多半会好奇它内部是怎么跑的。
原理拆解：它是怎么跟设备说话的
设备状态从哪来：推送，不是轮询
像快递通知群：不是隔几分钟问快递站"到了没"，而是等派件提醒自己弹出来。
集成在小米云的 MQTT Broker 上订阅设备消息，属性变化或事件触发时 Broker 实时推给集成，只在配置完成时查一次全部属性，之后不再轮询。
控制指令往哪去：本地网关优先
像家里设了个前台，快递不用出城去分拣中心，直接送到前台。
小米中枢网关（固件 3.3.0_0023 及以上）内置标准MQTT Broker，集成直接向网关订阅消息，指令发布到 Broker 后由网关转发给设备，全程不出局域网。没有网关时，指令走HTTP 接口经小米云转发。两条通道同时可用时，本地优先。
一句话记住：状态靠通道推，指令走网关或云端，快和远都有路可走。
排障与进阶 🔧
- 登录后设备不显示→ 蓝牙、红外、虚拟设备暂不支持，或选错用户地区 → 先在米家 App 确认设备绑定，再选对地区重新导入
- 控制响应偏慢→ 局域网里没有中枢网关，指令绕道小米云 → 加装中枢网关后本地直连自动优先
- 实体名是英文、或一堆没用的实体→ 云端翻译不全、冗余 spec 没过滤 → 改 specs 目录的 multi_lang.json 和 spec_filter.yaml，再到集成配置里点"更新实体转换规则"
- 想同时管两个账号→ 在 Xiaomi Home 配置页选"添加中枢"，再登录一次
- 想看内部行为→ 把 custom_components.xiaomi_home 日志级别调成 debug
想深入映射规则，翻 doc/README_zh.md 的"MIoT-Spec-V2 与 Home Assistant 实体的映射关系"一节。
【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
