3 分钟把米家设备装进 Home Assistant官方小米 Home 集成 ha_xiaomi_home 新手完整指南【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home深夜你在 Home Assistant 里布好的自动化终于触发了“门锁一开客厅灯亮起。”结果灯没反应——那盏小米灯压根不在 HA 里它还是只能在米家 App 里戳一戳的设备。这就是ha_xiaomi_home补上的那块拼图小米官方出品的集成把米家设备直接接进 Home Assistant本地直连与云端通道都支持还能按设备的能力清单自动生成实体现有设备不用换。定位速览米家与 Home Assistant 之间的官方桥梁一句话定位小米官方支持的 Home Assistant 集成组件“集成”就是 HA 里负责把外部平台设备引进来的组件。给谁用家里有米家设备灯、净化器、扫地机、空调、音箱……又想用 HA 统一看板、跑自动化的你。核心价值登录一次账号勾选一个家庭整屋设备自动变成本地可用的 HA 实体局域网有中枢网关走直连没有就兜底走小米云。门槛全程在 HA 的设置页面点选完成不用手写配置、不用敲代码。桥搭稳了具体能干什么按接入、控制、实体三个维度一次看全。能力全景设备接入、双通道控制、自动生成实体维度能做什么设备接入多账号共存多个小米账号可同时登录不同账号的设备可放进同一个 HA 区域按家庭圈选勾选要管的家庭整屋设备打包导入支持中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个云区设备控制推送更新不轮询设备属性一变HA 实时收到通知面板永远新鲜双通道自动兜底有中枢网关走局域网直连没有则经小米云转发实体生成实体自动生成读取每台设备的 MIoT-Spec-V2 描述相当于设备的“能力清单”自动转成 switch、sensor、climate 等实体13 种语言名称属性名自动翻译中文界面原生显示中文一个提醒蓝牙、红外和虚拟设备暂时不在支持范围内。能力看明白了剩下就是把它跑起来。跟手上手三步安装米家集成并导入设备前置条件Home Assistant Core 2024.4.4 及以上、Operating System 13.0 及以上。第①步拉代码装组件。在运行 HA 的机器上克隆仓库并执行安装脚本它会把集成复制到custom_components/下随后重启 HA 即可cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/your/HA/config第②步小米账号登录。设置 → 设备与服务 → 添加集成搜Xiaomi Home。登录走 OAuth 2.0一种“只授权、不留存密码”的方式你的密码不会存进 HA。注意选对账号所在地区不同地区的设备躺在不同的云上选错就导不出来。第③步圈选家庭导入。登录成功后弹出“选择家庭与设备”页面勾选要接入的米家家庭该家庭下的设备全部自动导入并转换成 HA 实体。刷新设备列表你的净化器和灯已经躺在里面了。以后想升级版本回到克隆目录git fetch、切到目标 tag、再跑一次安装脚本就行。三步走通了你可能好奇面板上的状态为什么总是一副“刚发生”的样子答案藏在消息通道的走向里。幕后原理状态为什么实时控制为什么快状态更新厨房“出菜喊一嗓子”最容易误解的一点HA 是不是每隔几秒去问一遍设备“你变了吗”不是。好比去餐厅吃饭——厨师做好一道菜就自己喊一声服务员听见就端走从没有人站在出餐口问“菜好了没”。技术上集成在小米云的 MQTT Broker云端的“消息分发中心”上订阅设备消息设备属性变化或事件发生时Broker 实时推给集成整个配置过程只在完成时向云端查一次全部属性之后不再反复轮询。控制指令走反方向经 HTTP API 发给云端由云端转发给设备。本地直连中枢网关里的“屋内布告栏”家里要是有台小米中枢网关固件 3.3.0_0023 及以上就像在屋里设了块布告栏设备自己把状态贴到栏上HA 直接读栏下指令则是往栏上贴一张通知网关把通知送到对应设备手里。全程不出局域网响应快一个档次。两条通道同时在线时本地控制自动优先。实体生成按“说明书”分座位每台米家设备都自带一份 MIoT-Spec-V2 规格文档像出厂说明书把属性、事件、方法列得清清楚楚。集成拿它对照内置映射规则“分座位”说明书里写的在 HA 里拿到的座位可写的布尔属性开/关switch 开关可写的数值属性档位、目标温度number 数值只读属性温度、湿度sensor 传感器事件长按、门窗打开event 事件方法重启、自清洁button 按钮这就是不同设备生成不同实体组合的原因也是你后面定制实体的入口。想让它长期跑得顺先看看别人踩过的坑。避坑手册导入与控制最常碰到的问题 登录后设备不显示→ 蓝牙、红外及部分虚拟设备暂不支持或登录时选错了地区各地区的用户数据在云上相互隔离→ 先在米家 App 确认设备已绑定该账号再在配置流程里选对地区重新导入。控制明显偏慢→ 局域网里没有中枢网关指令只能绕道小米云 → 加装中枢网关后本地直连自动生效配置里的“局域网控制”开关不建议用来顶替官方文档明确标注它可能引发异常。实体名是英文或冒出一堆没用的实体→ 该设备的云端翻译不全冗余的规格实例默认没被过滤 → 修改 specs/multi_lang.json 和 specs/spec_filter.yaml再到集成配置页点“更新实体转换规则”生效。想同时管两个小米账号、或想看看内部在干嘛→ 在 Xiaomi Home 配置页选“添加中枢”再登录一次把Xiaomi Home的日志级别调成 debug内部消息就都摊在日志里了。进阶入口完整的实体转换表与过滤规则语法在 doc/README_zh.md每个版本改了什么见 CHANGELOG.md想补翻译、提修复看 doc/CONTRIBUTING_zh.md。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考