小米设备接入 Home Assistant 实战指南：4 步把全屋米家设备搬进 HA
小米设备接入 Home Assistant 实战指南4 步把全屋米家设备搬进 HA【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home这是一份小米设备接入 Home Assistant 的完整攻略小米官方支持的组件 ha_xiaomi_home 基于 MIoT 协议对接设备提供云端与本地双控制通道一次授权就能把你的米家设备自动导入 HA。接入完成后的家一个晚上的自动化先看接完之后你每天能得到的东西。傍晚推开门门磁先一步把信号送给 HA玄关灯自己亮起空调早已切到你习惯的送风温度窝在沙发上喊一句看电影客厅主灯熄灭、氛围灯带转暖电视和回音壁同时开机半夜起身人体传感器把去卫生间的过灯点亮躺回去之后又自动熄灭清晨出门离家模式关断全部照明空调转入节能档。这些动作你不用去米家 App 里逐个点按钮也不用为每个房间配遥控器它们都写在 HA 的自动化编辑器里。前提只有一个小米设备得先进入 Home Assistant。下面就是完整的做法。ha_xiaomi_home 是什么协议、状态、指令的中转站先弄清这个组件替你做哪些事出了问题才知道该往哪里查。它干三件事而且全自动协议转换——把小米设备的能力规格翻译成 HA 认识的标准实体状态同步——设备状态一变HA 面板上立刻更新指令转发——你在 HA 里发出的开关、调温操作准确送达对应设备。有三个术语第一次出现各解释一句术语一句话解释MIoT 协议小米官方开放的物联网标准每台设备用统一格式声明自己有哪些属性、能收什么指令MQTT Broker消息中介组件在它那里订阅设备消息状态变化主动推送不用反复轮询小米中枢网关米家生态的家用网关内置 MQTT Broker可以在局域网里代理设备通信理解成翻译 快递员即可规格翻译给 HA 看状态实时送到指令按地址发出。ha_xiaomi_home 安装教程环境、安装、授权四步走完按下面四步操作完你的小米设备就会整整齐齐出现在 HA 里全程不需要写代码。先检查这两项别省动手前确认环境能省掉后面一大半排查时间HA 版本官方要求 Core ≥ 2024.4.4Operating System ≥ 13.0版本太旧会缺组件依赖的接口网络连通性确认系统能访问小米云终端执行一条命令即可验证ping api.io.mi.com有回应就继续没有就先解决网络问题。Git 脚本或 HACS 安装二选一方式一Git 克隆官方推荐后续切换版本方便git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/config方式二HACS 安装在 HACS 商店搜索 Xiaomi Home进入详情页一键下载即可。⚠️ 两个容易踩的坑install.sh只接受一个参数就是 HA 的config目录路径传多传少都会直接报错退出无论哪种方式装完必须重启 Home Assistant集成才会出现在列表里。小米账号授权与区域选择进入设置 → 设备与服务 → 添加集成搜索 Xiaomi Home按提示用小米账号登录并选择账号所属区域。可选区域有六个中国大陆、欧洲、印度、俄罗斯、新加坡、美国。授权成功后组件会自动发现账号下的全部设备并批量导入不用逐台添加。两个实用点同一个 HA 可以继续添加其他小米账号不同区域的设备也能导入同一个 HA 实例统一调度。本地控制参数在哪改本地控制相关的参数集中在 custom_components/xiaomi_home/miot/lan/profile_models.yaml需要时按文件内注释修改。⚠️ 官方建议对本地控制模式保持谨慎目前仅支持 WiFi 或以太网局域网 IP连接的设备蓝牙 Mesh、ZigBee 设备不在其列。如果你家里有小米中枢网关组件会自动利用网关的本地代理能力无需额外配置。云控 vs 本地一张表看清两种通道看完这节能根据你的网络环境和生活习惯选定主通道两者不互斥可以按场景混用。对比维度云端控制本地控制通信路径设备 → 小米云 → HA设备 → 中枢网关 → HA网络依赖需保持外网连通纯局域网断外网照常工作响应速度受网络波动影响局域网内几乎无延迟隐私状态数据经云端中转数据不出家门典型场景出远门远程操控传感器联动、本地自动化云控模式下云端的 MQTT Broker 负责把设备状态变更实时推送给组件控制指令则通过云端 HTTP 接口下发人在外地也能指挥全屋本地模式把通信终点换成中枢网关所有数据只在局域网里转一圈。另外说明一点小米中枢网关目前仅在中国大陆销售其他地区只能依赖云控或局域网控制能力。导入即可用MIoT 规格自动转换引擎这是组件里最省事、也最容易被忽略的一环你导入设备那一刻实体就已经生成好了一行代码、一张映射表都不用写。原理是这样的每台小米设备都附带一份 MIoT-Spec-V2 规格像说明书一样描述自己有什么属性、能做什么。组件内置的 specv2entity.py 转换引擎读取这份规格自动判断每项能力的读写属性和数据类型再对号入座生成 HA 实体设备规格里的能力自动生成的 HA 实体可写的布尔属性Switch开关只读属性Sensor传感器带取值范围的数值属性Number数值带固定选项的属性Select下拉选择可写字符串属性Text文本设备事件Event事件无参数的方法Button按钮带参数的方法Notify通知所以温湿度计导入后自动变成传感器、灯变成可开关的灯实体、空调伴侣变成温控实体理解属性 vs 服务 vs 事件这类协议细节的事引擎替你做了。覆盖面速查六大类设备与 13 种语言导入前可以先对一下家里的设备清单高频品类基本都能覆盖设备类别对应 HA 领域典型设备照明设备light智能灯泡、灯带开关插座switch智能插座、墙壁开关传感器sensor温湿度、人体、门窗传感器温控设备climate空调伴侣、智能温控器风扇fan智能风扇、空气循环扇加湿器humidifier各类智能加湿器语言方面translations/ 目录下提供了 13 种语言的翻译文件覆盖简中、繁中、英文、日文、德文、法文、西文、俄文、意大利文、荷兰文、葡萄牙文、巴西葡萄牙文和土耳其文配置界面会跟随 HA 的语言设置自动切换。出问题时怎么办三类高频问题排查清单卡住了别慌按下面的顺序排查大多数问题都能对号入座。设备连不上先ping api.io.mi.com确认网络能到小米云再到米家 App 里确认该账号对这台设备有控制权限最后排除设备本身离线、掉线的情况。实体状态不同步重启 Xiaomi Home 集成仍不行则清除.storage/xiaomi_home.*缓存文件后重启 HA再检查设备固件是否过旧能升级就升级。本地控制失效确认中枢网关与 HA 处于同一局域网核对网关状态与配置是否一致确认设备属于本地控制支持的范围WiFi/以太网蓝牙 Mesh、ZigBee 设备走不了这条路。把接入交给组件把编排留给自己ha_xiaomi_home 的价值在于把智能家居里最繁琐的接入环节做成了标准动作授权一次设备批量导入实体自动生成。小米设备接入 Home Assistant 之后你面对的是同一个可以随意编排的全屋平台而不是两套互相隔离的系统。剩下的场景与联动都是 HA 自动化编辑器里点两下的事。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考