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凌晨三点你起床去洗手间。人体传感器感知到你走廊灯悄悄亮起回床后自动熄灭。这些米家设备如果都在 Home Assistant下称 HA一个开源智能家居平台灯、空调、传感器共存于同一面板并可在自己的自动化里互相联动里这类联动不过是几行自动化规则的事——可它们现在只存在于米家 AppHA 面板里找不到。ha_xiaomi_home 是小米官方支持的集成组件基于小米官方 MIoT 协议把米家智能设备接入 Home Assistant提供云端与本地两条控制通道支持大部分设备品类多账号、多区域设备都能导进同一个 HA 实例。凌晨三点的洗手间米家设备为什么非得留在米家 App 里问题不在设备在于它们住错了房子。米家 App 与 HA 各有一本设备台账、一套自动化编辑器你没法在 HA 自动化里直接引用一个米家温湿度计查一个数据要来回切两个 App。也有人用抓包、逆向协议的方式打通结果协议一变插件就瘫等于每次推倒重来。ha_xiaomi_home 的价值正在于把协议对接这一步做成了官方动作你授权一次小米账号账号下的设备、状态、控制能力整体进入 HA至于怎么联动交给 HA 自己的自动化引擎你不用为任何一台设备手写对接代码。为什么不是逆向协议官方 MIoT-Spec-V2 才是钥匙官方两个字为什么重要ha_xiaomi_home 走的是小米官方开放的 MIoT-Spec-V2 协议。它是小米 IoT 平台制订的物联网协议让每台设备用标准格式描述自己的能力有哪些属性灯的开合、亮度、会发出哪些事件有人走动、能被调用哪些方法开始清扫。好比每台设备随身带一张字段固定、格式统一的设备名片读懂名片就不用猜协议接口也稳定得多。授权走 OAuth 2.0一种标准网页授权流程你用小米账号完成一次授权即可HA 不保存你的密码。登录成功后组件自动发现账号下的设备列表不用逐台添加。⚠️ 安全要点OAuth 2.0 登录不会在 HA 里存你的小米账号密码但登录成功后设备信息、证书、token 等数据会明文保存在 HA 的配置文件中务必保管好该文件。怀疑 token 泄露时可在米家 App → 我的 → 小米账号页面 → 应用授权中撤销对 Xiaomi Home 的授权。最快安装路径两种方式为 HA 添加 Xiaomi Home 集成前提是 Home Assistant 版本不低于 Core 2024.4.4Operating System 13.0 以上。版本不够先升级否则集成装上也无法被正确识别。选一种安装方式。最省事的是 HACSHA 的社区应用商店搜索 Xiaomi Home点下载。官方更推荐 git clone因为更新到某个指定版本时可以直接切换 tag执行git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home进入目录后运行./install.sh /path/to/homeassistant/config把组件文件复制到 HA 的 config 目录。还有一种手动方式把custom_components/xiaomi_home整个文件夹拷进 HA 配置目录下的custom_components中。重启 Home Assistant。这一步最容易被漏掉——不重启集成不会出现在集成列表里。⚠️install.sh只接受一个参数HA 配置目录的路径且该路径必须真实存在传错脚本会直接退出不会帮你猜。小米账号授权登录后要做什么区域怎么选进入设置 → 设备与服务 → 添加集成搜索 Xiaomi Home。页面会引导你登录小米账号随后弹出选择家庭与设备对话框选中一个家庭该家庭下的设备就整体导入 HA。不需要逐个录入也不用查设备型号。容易踩的两个点区域必须选对。小米云数据按区域隔离接口部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国共 6 个区域。你选的区域要和账号归属一致否则设备列表是空的。多账号也支持。第一个账号配置完成后可以在集成配置页继续添加其他小米账号不同账号、甚至不同区域的设备可以放进同一个 HA 实例参与同一套自动化。云端控制还是本地控制两条通道怎么选设备进来之后下一个问题是指令怎么走。ha_xiaomi_home 有两条通道二者不是二选一而是可以并存。云端控制小米云上的 MQTT Broker可以理解为消息中转站——设备把状态变化发出去订阅方即时收到HA 无需反复轮询把设备状态变化实时推给集成你在 HA 发出的控制指令则经小米云 HTTP API 下发到设备。配置完成后集成只向云端查询一次所有设备属性之后全靠订阅推送对云端的访问压力很小。本地控制通信终点从云端换成小米中枢网关固件 3.3.0_0023 以上版本内置标准 MQTT Broker状态同步与指令收发全部在局域网内闭环不经过外部服务器带内置中枢功能软件版本 0.8.9 以上的设备同样适用。注意中枢网关目前仅在中国大陆发售。对比维度云端控制本地控制中枢网关通信路径设备 → 小米云 → HA设备 → 中枢网关 → HA对外网依赖需要必须保持联网不需要纯局域网指令响应受公网波动影响近乎即时数据路径状态经云端中转数据不出局域网典型场景出门在外的远程操控居家传感器联动、本地自动化硬性条件无特殊要求需中枢网关固件 3.3.0_0023 以上且仅中国大陆可购还有一条叫局域网控制的路径直接在局域网里控制 WiFi 或网线接入的设备。官方态度很明确它只支持 IP 设备到不了蓝牙 Mesh、Zigbee 设备且可能引发异常不建议开启如果局域网里已有中枢网关这条路径会自动让位、不生效。判断很简单家里有中枢网关就用本地控制跑居家自动化、云端留作远程兜底没有网关默认云端控制即可开箱体验已经完整。不用写一行映射代码specv2entity 如何把规格变成立即可用的实体设备导入后最容易被忽略、其实最省钱的一步是内置的转换引擎 custom_components/xiaomi_home/miot/specs/specv2entity.py。你可能要问集成怎么知道一个米家属性该变成开关、还是该变成数值框答案就是读设备上那张 MIoT-Spec-V2名片按固定规则转换MIoT-Spec-V2 里的定义转换后的 HA 实体可写的布尔属性Switch开关可写、带取值范围的数值属性Number数值调节可写、带离散取值列表的属性Select下拉选项可写的字符串属性Text文本输入只读属性Sensor传感器事件如有人走动Event事件不带输入参数的方法Button按钮带输入参数的方法Notify通知匹配顺序按 设备级规则 服务级规则 属性级规则 通用规则 逐层回退像扫地机这种形态清晰的设备先整体命中设备级规则没命中再逐层降级。某台设备有多余的属性不想转换用spec_filter.yaml一类的过滤文件排除即可同样不用改代码。实体名称本身支持 13 种语言并跟随 HA 的语言设置显示个别翻译不准时本地字典multi_lang.json的优先级高于云端文件可以覆盖修正。导入完成的那一刻实体就已经可用。这是它与抓包式接入最大的体验差距。连不上、不同步设备接入与状态排查清单遇到问题按下面的顺序查基本能覆盖绝大多数情况✅设备连不上、实体列表是空的先确认网络能通到小米云终端里 pingapi.io.mi.com看是否可达再到米家 App 里确认该账号对这台设备有控制权限、设备本身在线仍不行就重新选择区域后再次导入。✅实体状态与实际不同步重启 Xiaomi Home 集成仍卡住则清除.storage下该集成的存储缓存文件后再重启还不行再检查设备固件是否过旧。✅本地控制不生效确认中枢网关与 HA 在同一局域网确认网关固件不低于 3.3.0_0023确认要控的设备是 WiFi 或网线接入蓝牙 Mesh 设备走不了这条路径。更完整的多语言配置、过滤规则等进阶内容可以延伸阅读 doc/README_zh.md。从接入到联动最繁琐的那段路 ha_xiaomi_home 已经替你走完剩下的问题只有一个你的家想怎么动。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考