企业官网建设流程全解析

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 里控，灯你想拉进 Home Assistant 的自动化里，却发现没有官方入口，只能翻社区的各种野路子。小米官方的答案是ha_xiaomi_home：把米家设备直接接入 Home Assistant，本地、云端两种控制方式都支持，现有设备不用换。

跑通它其实就三步。

核心能力速览：它能干多少事

一句话定位：把米家设备接入 Home Assistant 的桥。

• 设备统一面板：多个小米账号的米家设备可导入同一个 Home Assistant，一个仪表盘统一管理。
• 本地/云端双通道：局域网有中枢网关就本地直连，没有就走小米云，两边都兜得住。
• 状态推送不轮询：设备属性一变就主动推过来，状态不滞后。
• 实体自动生成：读每台设备的 MIoT-Spec-V2 描述，自动转成 switch、sensor、climate 等实体，不用手工映射。
• 实体名多语言：支持 13 种语言，属性名自动翻译，中文界面开箱就是中文。

这 5 点决定了你后面跑通它的速度。

安装步骤：3 步装好 ha_xiaomi_home 集成

第 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 /config

install.sh 会把组件复制到 Home Assistant 的custom_components目录，/config换成你实际的路径即可，之后重启 Home Assistant 就装好了。

装好之后，登录一下账号。

第 2 步，登录小米账号

界面进设置 → 设备与服务 → 添加集成，搜Xiaomi Home点下一步，会跳到小米账号登录页。登录走 OAuth 2.0（标准授权方式，第三方只申请它需要的权限），密码不会存进 Home Assistant。

⚠️ 要选对用户所在地区（中国、欧洲、美国等）。不同地区的设备在不同云上，选错就导不出设备。

登录成功，就差最后一步了。

第 3 步，选择家庭

弹出"选择家庭与设备"会话框，勾选要接入的米家家庭，该家庭下的设备全部导入。刷新设备列表，空气净化器和灯应该已经躺在实体列表里了。

以后想升级版本，进克隆目录config/ha_xiaomi_home执行（以 v1.0.0 为例）：

git fetch git checkout v1.0.0 ./install.sh /config

原理拆解：ha_xiaomi_home 怎么跟设备说话

设备状态为什么总最新：推送而不是查询

它像快递通知群：不是每隔几分钟打一次快递站问"到了没"，而是等派件提醒自己弹出来。技术上是这么回事：集成在小米云的 MQTT Broker（负责收发、转发消息的中间件）上订阅设备消息通道，设备属性变化或事件触发时，Broker 实时把properties_changed、event等上行消息推给集成；配置完成时只向云端查一次全部属性，之后不再轮询。控制指令走反方向，通过 HTTP API 发set_properties或action消息到云端，再由云端转发给设备。

一句话记住：状态靠通道推，指令走 HTTP 下发。

如果局域网里有中枢网关，还有更快的路。

本地直连配置：中枢网关里的 MQTT Broker

你可以理解为家里设了个前台：快递不用出城去分拣中心，直接送到前台就行。小米中枢网关（固件 3.3.0_0023 及以上）内置了一个标准 MQTT Broker，集成直接向网关订阅设备消息，控制指令发布到 Broker 后由网关转发给设备，全程不出局域网。两条通道同时可用时，中枢网关的本地控制优先。

一句话记住：局域网里有前台，控制不出家门，更快更稳。

通道解决的是"怎么说话"，还有件事决定"生成哪些实体"。

不同设备为什么生成不同实体：MIoT-Spec-V2

每台设备都带一份 MIoT-Spec-V2 描述，相当于一张设备"说明书"，列清楚它有哪些属性、事件和方法。集成拿描述去匹配内置映射规则：属性变成 sensor 或 switch，事件变成 event 实体，方法变成 button——这也是你后面定制实体的入口。

一句话记住：spec 是说明书，实体是按说明书自动装配出来的。

常见问题与进阶玩法 🔧

• 登录后台设备不显示→ 蓝牙、红外和部分虚拟设备暂不支持 → 先在米家 App 确认设备已绑定该账号，再选对地区重新导入。
• 控制指令响应偏慢→ 局域网里没有小米中枢网关，指令只能绕道小米云 → 加装中枢网关后本地直连自动优先。
• 实体名是英文，或者一堆没用的实体→ 云端翻译不全，冗余的 spec 实例默认没被过滤 → 改specs目录下的multi_lang.json和spec_filter.yaml，再到集成配置里点"更新实体转换规则"生效。
• 想看内部到底在干嘛→ 默认日志粒度太粗 → 把custom_components.xiaomi_home的日志级别调成debug。

进阶提示：想同时管多个小米账号，在 Xiaomi Home 配置页选"添加中枢"再登录一次即可，不同账号的设备可以加进同一个 Home Assistant 区域。

延伸阅读

想查 MIoT-Spec-V2 到实体的完整映射表和过滤规则，看 中文文档 就够，里面都写全了。

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