小米设备接入 Home Assistant 终极指南：ha_xiaomi_home 完整上手

小米设备接入 Home Assistant 终极指南ha_xiaomi_home 完整上手【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home在 Home Assistant 面板上点开关米家的灯纹丝不动温湿度数值要等半分钟才动一下——这个瞬间劝退过太多想把全屋收编进 HA 的人。开源组件 ha_xiaomi_home 就是为此而生的小米官方支持的 Home Assistant 集成组件基于官方 MIoT 协议把小米设备变成标准 HA 实体云端、本地两条控制通道按需使用不抓包、不逆向。三步跑通小米设备接入 Home Assistant 的最短路径最快的路是 git clone 加一条安装脚本全程不写代码。版本要求Home Assistant Core ≥ 2024.4.4Operating System ≥ 13.0。克隆并安装。在 HA 的 config 目录执行下面两条命令install.sh会把集成自动复制到custom_components/xiaomi_homecd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/config⚠️install.sh只接受一个参数——config 目录路径安装完成后必须重启 Home Assistant组件才会出现在集成列表里。添加集成。进入设置 → 设备与服务添加集成搜索Xiaomi Home按页面提示用小米账号登录OAuth 2.0 流程不会保存你的账号密码。选区域、选设备。选择账号所属区域中国大陆、欧洲、印度、俄罗斯、新加坡、美国六选一在选择家庭与设备对话框勾选家庭设备批量导入实体即刻可用。不想走命令行也可以从 HACS 搜索 Xiaomi Home 一键安装详见简体中文 README。双通道控制机制云端管远程本地管即时ha_xiaomi_home 内置两条并行的控制通道它们不互斥组件会根据你的网络环境自动择优。云通道绕道小米云却是远程场景里最稳的路云控模式下状态和指令走两个方向小米云上的 MQTT Broker 把设备状态变化属性变更、事件、上下线实时推送给集成你在 HA 发出的指令则经 HTTP API 送到云端再转发给设备。得益于订阅而非轮询集成只在配置完成时向云端全量查询一次属性对云端压力很小状态却始终是实时的。本地通道把终点换成自己家里指令延迟降到局域网级只要家里有小米中枢网关固件 3.3.0_0023 及以上或内置中枢功能的设备软件 0.8.9 及以上集成会通过 mDNS 自动发现并接管它网关自带标准 MQTT Broker状态订阅与指令下发全部在局域网内完成数据不出家门断网照跑。⚠️ 另有一个不依赖中枢的局域网控制LAN control只能控制同局域网内的 IP 设备WiFi/以太网官方明确提示可能引起异常建议不要使用且局域网内存在中枢网关时该功能会自动失效。对比维度云端控制本地控制中枢网关通信路径设备 → 小米云 → HA设备 → 中枢网关 → HA外部网络依赖需要须保持联网不依赖纯局域网指令延迟受公网波动影响局域网级近乎即时适用场景出门在外的远程操控传感器联动、本地自动化一个藏得很深的亮点specv2entity 自动翻译设备规格如果没有内置的 specv2entity.py 转换引擎每接入一台小米设备你都得人工读懂它的 MIoT-Spec-V2 规格——哪些是属性、哪些是服务、哪些是事件——再逐台手写映射规则。这个引擎把输入到输出做成了一步输入是设备规格输出是一整批标准 HA 实体可写 bool 属性 →Switch只读数值属性 →Sensor带取值列表的属性 →Select带取值范围 →Number事件 →Event无参方法 →Button带参方法 →Notify对扫地机、加湿器、温控器这类常见品类它按设备 服务 属性 通用规则的优先级依次匹配三张映射表匹配不上特殊规则就落入通用属性转换表。对你的意义很直接设备导入完成的那一刻实体就全部能用一行 yaml 都不用写。能力全景速查设备品类、实体覆盖、通道与语言一张表看全维度支持范围设备品类照明、开关插座、传感器、温控、风扇、加湿器、扫地机、音箱等蓝牙、红外、虚拟设备不支持HA 实体覆盖light、switch、sensor、climate、fan、humidifier、vacuum、cover、media_player、button、number、select、text 等控制通道小米云MQTT HTTP、中枢网关本地 MQTT、局域网控制仅 IP 设备账号与区域多小米账号并存六大区域中国大陆/欧洲/印度/俄罗斯/新加坡/美国可跨区导入同一区域界面语言简中、繁中、英、日、德、法、西、俄等 13 种跟随 HA 语言设置自动切换翻译文件位于 translations/实体名称的翻译还可以用 multi_lang.json 在本地补充或覆盖优先级高于云端翻译。避坑手册高频故障与已验证解法下面五条按排查频率排列带 ✅ 的为官方文档验证过的解法。设备连不上→ 先ping api.io.mi.com确认 HA 网络能到达小米云再到米家 App 确认账号对该设备有控制权限、设备本身在线 ✅实体状态不同步→ 依次执行重启 Xiaomi Home 集成 → 清除.storage/xiaomi_home.*缓存文件 → 检查设备固件是否过旧 ✅本地控制不生效→ 确认中枢网关与 HA 处于同一局域网、网关固件 ≥ 3.3.0_0023局域网内已有中枢时局域网控制会被自动禁用别在它身上找原因改了规格规则实体没变→ 修改 specs/ 下任何文件如spec_filter.yaml、multi_lang.json后必须在集成 CONFIGURE 页面执行更新实体转换规则才生效 ✅怀疑令牌泄露→ 到米家 App → 我的 → 小米账号管理 → 应用授权找到 Xiaomi Home (Home Assistant Integration) 取消授权 ✅收尾回到开头那个瞬间ha_xiaomi_home 装好之后面板一按灯真的会亮传感器真的即时上报。下一步值得做的是把人体传感器和玄关灯串成第一条自动化——那才算真正体会到全屋自动化的差别。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考