3 步把小米设备装进 Home Assistantha_xiaomi_home 接入指南与本地控制说明【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home如果你家里已经有一批小米智能设备想统一收进 Home Assistant 里做自动化那 ha_xiaomi_home 就是目前最顺手的官方集成。它支持小米官方出品负责把小米云上的设备清单拉进 Home Assistant并把 MIoT-Spec-V2 协议描述翻译成你熟悉的开关、传感器、空调等实体在拥有小米中枢网关时还能把控制链路整个搬回局域网。云与本地先弄清你的控制命令从哪条路走很多人装完发现能控制但感觉慢了半拍根源就在于控制链路的选择。ha_xiaomi_home 里其实存在两条路差别可以从延迟、隐私、可用性三个维度看维度走小米云走中枢网关本地延迟依赖外网质量偶有波动局域网内直连稳定且快隐私控制消息经过小米云端指令不出局域网可用性断外网也能看缓存状态但控制要恢复联网断外网不影响断局域网才失效用个比方云端模式像是给设备打电话信号好不好听天由命本地模式则像设备就在隔壁房间喊一嗓子就行。云端链路订阅收状态HTTP 发指令没有网关时集成走的是标准云端流程状态变化属性变更、事件、上下线通过小米云里的 MQTT 消息推送过来所以它不需要轮询设备——配置完成时批量查一次之后全靠推送而控制指令通过 HTTP 接口发往云端再转发给设备。这条链路的完整形态见下图本地链路中枢网关内嵌一个 MQTT Broker家里有小爱中枢网关固件 3.3.0_0023 及以上或自带中枢功能的设备软件 0.8.9 及以上时集成会自动发现它并切到本地链路网关内部跑着一个标准 MQTT Broker状态推送和指令下发全部在局域网内完成。 提示官方说明小米中枢网关目前仅在中国大陆发售。海外地区还有一条局域网控制退路但官方明确不推荐——它只能控制同网段的 IP 设备对 BLE Mesh、Zigbee 设备无效且可能引入异常。局域网里一旦存在中枢网关局域网控制也会自动失效。 本节要点本地链路要硬件门槛中枢网关或内置中枢的设备云端链路靠 MQTT 订阅收状态不轮询云压力小海外用户只能走云端LAN 控制仅作了解即可3 步完成设备接入以下按 Home Assistant Core ≥ 2024.4.4Operating System ≥ 13.0为前提。第 1 步拿到集成代码三条安装路径按顺手程度任选Git 克隆官方推荐方便以后切 tag 更新版本cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /configinstall.sh 会把custom_components/xiaomi_home复制到 Home Assistant 配置目录下的custom_components中装完重启一次 Home Assistant。通过 HACS 商店搜索Xiaomi Home一键安装。手动把custom_components/xiaomi_home整个文件夹拷进配置目录Samba / FTP 都行。第 2 步登录小米账号打开 Home Assistant进入设置 → 设备与服务 → 添加集成搜索Xiaomi Home按提示跳转登录使用小米账号完成授权注意这里走的是 OAuth 2.0 流程不需要也不保存你的小米密码。但登录后的用户信息、设备清单、token 会以明文存在 HA 配置目录里所以配置目录本身的权限要管好怀疑 token 泄露时可以在小米家 App 里找到对应授权并移除。第 3 步选择家居与设备登录成功后弹出Select Home and Devices对话框选择设备所在的家居一个账号管理多个家时按需勾选按提示选择接入区域中国大陆、欧洲、印度、俄罗斯、新加坡、美国确认后设备以实体形式出现在 Home Assistant 中 提示一个 Home Assistant 里可以同时挂多个小米账号、多个区域的设备——在已配置的Xiaomi Home → 添加中枢里继续登录另一个账号即可不同账号的设备还能放进同一个区域。 本节要点安装用install.sh一条命令之后切 tag 就能回滚版本登录走 OAuth密码不落盘但配置目录要保密多账号、跨区域设备可在同一实例内共存实体是怎么变出来的MIoT-Spec-V2 到 HA 实体的规则设备能变成什么实体不是集成随手拍的而是按小米的 MIoT-Spec-V2 协议规格逐条翻译的。规则按设备级 → 服务级 → 属性级 → 通用规则的顺序匹配映射表就在 miot/specs/specv2entity.py 里。几条最常用的通用转换方便你看到实体后反推它的来历MIoT 属性特征生成的 HA 实体可写 字符串Text可写 布尔Switch可写 数值 有取值列表Select可写 数值 有取值范围Number只读Sensor另外设备的事件event变成 HA 的 Event 实体动作action变成 Button 或 Notify 实体——比如小爱音箱执行文本指令这个动作就会变成一个 Notify你在实体详情里按[Text Content(str), Silent Execution(bool)]的格式填入参数即可。如果翻译结果不理想你有三个本地可调的旋钮都在 miot/specs/ 目录下spec_filter.yaml按 URN 和 iid 过滤掉不想要的服务、属性、事件、动作支持通配符spec_modify.yaml改写规格实例如取值范围、访问模式multi_lang.json本地维护的实体名翻译优先级高于云端下发的多语言文件支持 13 种语言代码改完任何 specs 文件后记得去Xiaomi Home → 配置 → 更新实体转换规则刷新生效否则白改。 本节要点实体类型由 MIoT-Spec-V2 规格决定规则匹配优先级设备 服务 属性 通用specs 目录的三个文件是官方留给你自定义的入口改动后必须手动触发更新实体转换规则连不上、控制慢按这个顺序排查官方 FAQ 里明确了几条边界先对照一下能省很多事蓝牙设备、红外设备、虚拟设备本身就不在支持范围内其余绝大多数品类传感器、家电、音箱、电视、扫地机等都已支持具体机型清单可以查 CHANGELOG 中新增/修复机型的历史记录。现象一登录成功但设备列表是空的或找不到设备可能原因选错了区域小米云的用户数据按区域隔离区域选错就查不到设备设备不在所选家居分组里一个账号多个家时只在当前勾选的家里找设备在小米 App 里就已离线或未绑定解决办法重新走一遍配置流程在区域选择处确认与设备实际归属一致换勾选另一个家居分组再试打开小米 App 确认设备在线、且账号绑定正常现象二能看状态控制指令无响应或延迟明显可能原因当前走的是云端链路而外网波动大有中枢网关但固件/软件版本不够没吃到本地链路设备固件过旧解决办法确认网关固件 ≥ 3.3.0_0023、内置中枢设备软件 ≥ 0.8.9版本到位后本地链路会自动优先于局域网控制升级设备固件打开集成调试日志定位卡在哪一环在configuration.yaml中加logger: default: critical logs: custom_components.xiaomi_home: debug再对照日志里 MQTT 订阅和 HTTP 指令的收发记录就能区分是状态没推上来还是指令没送出去。 本节要点空设备列表先查区域和家居分组而不是怀疑账号控制慢优先核对网关版本把本地链路真正用起来debug 日志是定位链路问题的最后一招接下来往哪走动手调规则从 spec_filter.yaml 开始过滤掉你家里那台设备多余的冗余实体感受一次按 URN 定制的完整闭环给集成加功能阅读 贡献指南按feat:/fix:的提交规范提 PR代码风格遵循 Google Python Style Guide可用pylint自检验证改动项目自带测试集先装pip install pytest pytest-asyncio zeroconf paho.mqtt psutil cryptography slugify然后跑pytest -v -s ./test/test_spec.py验证规格解析pytest -v -s -m github ./test/跑全量含规则格式检查 check_rule_format.py深入了解架构速览在 CLAUDE.md 里整理得最完整核心包 miot/ 按云通信 / 本地链路 / 规格解析 / 存储分文件组织各文件职责一目了然【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考