小米设备接入Home Assistant全指南：官方集成双模式架构与实战避坑

小米设备接入Home Assistant全指南官方集成双模式架构与实战避坑【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home在智能家居圈小米设备接入Home Assistant曾经约等于折腾两个字翻教程、抓 Token、逆向协议折腾一晚上第二天设备可能就掉线。而如今小米官方维护的 ha_xiaomi_home 集成把这条路修成了高速路——基于官方 MIoT 协议云端与本地双模式并存登录、发现、实体转换几乎全自动。这篇文章不按安装教程的老套路走而是从设计原理出发带你看懂它为什么好用以及什么情况下该走哪条路。从逆向破解到官方下场这条接入路径的含金量在哪小米设备接入 Home Assistant 的第三方方案不少但大多是社区逆向而来抓包取 Token、猜协议字段一旦小米调整协议就集体失灵。ha_xiaomi_home 的不同之处只有三个字——官方做。协议是官方认证的。它直接对接小米 MIoT 协议与新一代 MIoT-Spec-V2不需要抓包、不需要猜字段。协议升级时官方会跟着适配而不是等你发现设备失联才去找补丁。登录是官方授权的。整个登录流程走 OAuth 2.0组件不保存你的小米账号密码和手动填 Token的方案安全性不在一个量级。边界是诚实说清的。官方文档明确列出不支持的类型蓝牙设备、红外设备、虚拟设备不在支持范围内。提前把话说清楚反而让人更放心。接入前的环境门槛也不高Home Assistant Core 需 2024.4.4 及以上版本Home Assistant OS 需 13.0 及以上。界面支持 13 种语言简体中文和英文由开发者人工校对其余由社区与机器翻译共同维护。一条控制指令的两种走法双模式架构是怎么设计的这个集成最巧妙的设计是它没有逼你在云端和本地之间二选一而是把两条路都修通让状态消息走订阅推送、让控制指令走各自该走的通道。云端模式下组件在小米云的 MQTT Broker 上订阅自己关心的设备消息。设备属性一变云端立刻把消息推过来组件无需反复轮询只在配置完成时全量查询一次设备列表——对云端压力极小响应却很及时。你下发控制指令时指令通过 MIoT 云的 HTTP 接口转发给设备。一句话概括这张图状态靠订阅推送指令走 HTTP 下发。人在外面用手机远程关灯走的就是这条路。本地模式则把 MQTT Broker 装进了小米中枢网关。组件直接订阅局域网内的设备消息控制指令也通过网关内置的 Broker 发布整个链路在家庭网络里闭环不经过云端中转。本地路径的价值很直观毫秒级响应、不依赖外网、数据不出家门。人体传感器触发灯光这类讲究即时感的场景本地模式几乎是唯一解。但有个前提必须认清本地模式依赖小米中枢网关固件 3.3.0_0023 以上或自带中枢网关功能的设备软件 0.8.9 以上而且中枢网关目前仅限中国大陆发售海外用户默认只能走云端。设备为什么开箱就懂MIoT-Spec-V2 到实体的自动翻译你可能好奇那么多不同品牌、不同功能的设备接入后为什么 Home Assistant 能自动生成合适的实体秘密藏在custom_components/xiaomi_home/miot/specs/specv2entity.py这个转换引擎里。MIoT-Spec-V2 把每台设备描述成服务 属性 事件 动作的结构转换引擎按一套通用规则映射成 Home Assistant 实体MIoT 属性特征生成的实体可写的布尔属性Switch 开关可写的字符串属性Text 文本可写的枚举值列表Select 选择器可写的数值范围Number 数字只读属性Sensor 传感器设备事件Event 事件实体无参数的指令动作Button 按钮带参数的指令动作Notify 通知举个例子小米无线双键开关的长按事件会变成一个真实可触发的事件实体长按时日志里能看到Press and hold, attributes: {Button Type: 1}明确指出是哪个按键被长按。这种原生事件能力是很多第三方集成给不了的。对于厂商自定义的协议非 miot-spec-v2 命名空间转换时会在实体名前加一个*星号提醒你它来自第三方定义。如果发现某些设备转换出了多余实体还可以在spec_filter.yaml里按 iid 精确过滤支持通配符。从下载到全家上线一条完整的接入路径原理弄懂了剩下的就是动手。整个流程其实只有三个环节装组件、登账号、选设备。装组件三选一。最推荐 Git 克隆方式以后想固定到某个版本时切换很方便git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/config想固定到指定版本时git fetch后git checkout v0.4.7再跑一次 install 脚本即可。习惯用 HACS 的话在 HACS 商店搜索 Xiaomi Home 一键下载或者直接把custom_components/xiaomi_home目录拷贝到 Home Assistant 的custom_components目录下。登账号走 OAuth。在设置 设备与服务中添加集成搜索 Xiaomi Home点击登录后跳转小米账号授权。因为走 OAuth 2.0密码不会被组件保存。但有一个安全细节要留意受 Home Assistant 平台限制登录后设备信息、证书、Token 会以明文形式存进配置文件——请务必保管好配置目录。若怀疑 Token 泄露可在米家 App 的账号管理页面一键吊销授权。选设备按区域。登录成功后对话框会列出账号下的家庭勾选想导入的即可。设备区域支持中国大陆、欧洲、印度、俄罗斯、新加坡和美国而且不同区域的设备可以导入到同一个区域统一管理。如果你有多个小米账号还能在已配置的集成页面继续绑定实现多账号共存。 小提示如果后续手工改动了spec_filter.yaml、multi_lang.json等转换规则文件记得在集成的配置页执行更新实体转换规则改动才会生效。云端还是本地用这张清单做决策配好之后很多人纠结要不要开本地控制。与其纠结不如对照这张清单过一遍使用场景建议模式原因人在外面远程控制云端本地模式只覆盖家庭局域网远程必须走云人体感应、灯光联动等即时场景本地毫秒级响应无外网依赖家中有小米中枢网关本地自动优先网关固件 3.3.0_0023 以上即可身在海外云端中枢网关仅中国大陆发售想控制 BLE Mesh / ZigBee 设备云端LAN 控制只支持 WiFi/以太网 IP 设备这里特别提醒一个容易踩的坑集成还提供小米 LAN 控制功能能让部分 IP 设备WiFi 或网线连接走局域网控制但官方明确提示该功能可能引发异常建议不要开启且控制不了 BLE Mesh、ZigBee 设备。更关键的是只要局域网里存在中枢网关即使开启 LAN 控制也不会生效——中枢网关会优先接管。所以想追求本地化正确路径是上中枢网关而不是开 LAN 控制。如果遇到实体状态不同步按这个顺序排查先确认能正常访问小米云服务再检查设备在米家 App 里是否响应正常最后在集成配置页更新一次实体转换规则并重启集成。写在最后ha_xiaomi_home 的价值不在于它支持多少种设备而在于它把接入这件事从逆向工程变成了官方工程协议是官方的登录是官方的转换规则还允许按需裁剪。云端与本地两条路并存的设计也让不同地区的用户都能找到适合自己的接入方式。想开始的话从克隆仓库装好组件、接入你的第一盏灯开始。当它稳稳出现在 Home Assistant 的仪表盘上被你的一条自动化指令控制时你会真切感受到官方支持这四个字的分量。✅【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考