ha_xiaomi_home：小米设备接入 Home Assistant 快速上手教程-平芜编程栈

ha_xiaomi_home：小米设备接入 Home Assistant 快速上手教程

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

小米设备一多，每个都有自己的 App，来回切换很折腾。ha_xiaomi_home 是小米官方支持的 Home Assistant 集成组件，把分散的设备控制收进一个面板。这是写给想在 5 分钟内把小米设备接进 Home Assistant 的零基础上手教程。

打开手机，一半图标是米家系 App，想收拢到 Home Assistant，第一道坎常常是"没有官方组件"。ha_xiaomi_home 是小米官方支持的组件：用小米账号登录后，账号下的设备可以直接导入 Home Assistant，一个面板管全部。

还有人用第三方方式手动加过设备，结果实体名称混乱、属性不全，写自动化条件时很头疼。这个组件按小米 MIoT 规范把设备自动转换成灯、开关、传感器等标准实体，开箱就有"正经名字"，场景可直接引用。

还有常见的担心：走云控制慢、不稳定，网络一断就不灵。如果你家里有小米中枢网关，指令可以直接在局域网下发，不必绕出公网。

环境满足条件后，5 步就能让第一台设备出现在 Home Assistant 里。前提：核心版本 ≥ 2024.4.4，且设备已在米家 App 中完成绑定。

📌第 1 步：克隆项目代码

把仓库放到 Home Assistant 配置目录下：

cd <HA 配置目录> git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home

📌第 2 步：运行安装脚本

脚本参数是 HA 配置目录的绝对路径，组件会被复制进 custom_components 子目录：

cd ha_xiaomi_home bash install.sh /config

[!TIP] 运行完脚本后需重启 Home Assistant。日后更新只需切到新版本的 tag 再跑一次脚本，旧版本会由脚本自动处理。

📌第 3 步：添加集成并登录小米账号

进入设置 → 设备与服务 → 添加集成，搜索 Xiaomi Home，用小米账号完成 OAuth 登录。官方组件不会保存你的账号密码。

📌第 4 步：选择要导入的家居和设备

在"选择家居和设备"弹窗中勾选要导入的家居，确认后设备列表会陆续出现在 Home Assistant 中。

[!TIP] 多个小米账号的设备不能同时登录：在已配置好的 Xiaomi Home 页面点"添加中枢"再登第二个账号，不同账号的设备可以放进同一房间。

📌第 5 步：分配房间并写第一条自动化

在集成的 CONFIGURE 页可以修改房间归属、设备名称，从此就能写"传感器触发 → 开灯"这类场景。

集成跑起来后，值得先搞清一件事：指令从哪里发出去，状态又从哪里回来？

ha_xiaomi_home 支持两条通道，且都是"消息驱动"，而不是"定期挨个问"：

云端通道：状态上行、指令下行。设备属性变化（properties_changed）由小米云里的 MQTT Broker 推送给集成，控制指令走 HTTP 下发。配置完成时拉取一次全量设备，之后不再有轮询压力。
本地通道：有小米中枢网关时，MQTT Broker 就摆在网关上，状态与指令全程走局域网，延迟明显更低。集成靠 mDNS 广播发现网关（逻辑见miot_mdns.py），消息收发走内部消息总线miot_mips.py。

把它想成家庭配电箱：每个设备占一路，这一路有变化时，配电箱对应位置立刻贴上"告示"（MQTT 主题），Home Assistant 不用挨个插座巡视，只订阅告示即可；要控制设备时，往同一路上贴一张"回执单"，设备自然收到。