小米设备接入 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很多人都有过这样的体验家里的米家灯具、温湿度计、空调伴侣全都乖乖待在米家 App 里想拉进 Home Assistant下称 HA做联动时却不知从何下手。ha_xiaomi_home 正是官方为小米设备接入 Home Assistant这个问题写好的答案登录一次小米账号、选对区域全屋设备批量导入实体自动生成全程不用手写任何映射代码。为什么可信直连官方 MIoT 协议不靠抓包逆向过去想把米家设备塞进 HA绕不开抓包、逆向协议这类野路子。这类方案最大的毛病是不稳定——米家 App 一升级、云端接口一变动插件说坏就坏修起来让人头疼。ha_xiaomi_home 换了一条路直接对接小米官方开放的 MIoT小米物联网协议。好处很直接接口稳定走官方通道不依赖对私有协议的破解不用担心哪天全线失效兼容面广只要设备遵循 MIoT-Spec-V2 规范基本都能被识别接入轻一次账号授权后组件自动发现并批量导入账号下的设备不需要逐台手写对接。说白了它把接入从一件手工活变成了一次性的标准动作。导入即实体specv2entity 引擎替你翻译设备设备导入后很多人以为还要手动配置一番其实这一步已经被做掉了。每台小米设备都自带一份 MIoT-Spec-V2 规格描述行业里叫物模型里面写清了设备有哪些服务、属性、事件和方法。组件内置的转换引擎 specv2entity.py 会读取这份规格按读写属性和数据类型自动生成对应的 HA 实体规则大致是设备规格里的描述自动生成的 HA 实体可写的布尔属性如电源开关Switch 开关只读属性如温湿度读数Sensor 传感器可写且带固定取值列表如模式Select 选项可写且带数值范围如目标温度Number 数值设备事件如按键、状态变化Event 事件无参数的方法如一键动作Button 按钮对使用者的体感就是设备出现在 HA 的那一刻实体就能直接用了传感器进仪表盘、开关进自动化不用再查文档对编号。覆盖面方面照明、开关插座、传感器、温控、风扇、加湿器这些日常高频品类都支持组件平台文件里还能看到窗帘cover、扫地机vacuum、热水器water_heater、音箱media_player等更多领域具体可参考 custom_components/xiaomi_home/ 目录下的平台文件。界面语言上custom_components/xiaomi_home/translations/ 提供了 13 种语言简中、繁中、英、日、德、法、西、俄等会跟随 HA 的语言设置自动切换。云端还是本地控制指令的两种走法指令从哪里走是这个组件里最值得花时间理解的一点。两条通道可以按场景切换不是二选一的单选题。云端通道指令经小米云中转人在外地也能控走云控时小米云负责两件事设备状态一变化云端的 MQTT Broker 就把消息推送给 HA你在 HA 里发出的指令则经 HTTP 接口送到云端、再转发给设备。整个过程不挑网络环境人在公司、在出差路上一样能远程调家里的灯和空调。本地通道中枢网关做中转数据不出局域网家里有小米中枢网关的话通信终点就从云端换成了网关——网关内置一个标准 MQTT Broker状态同步和指令收发都在局域网内完成指令不经过任何外部服务器反馈几乎是瞬时的特别适合传感器联动这类对延迟敏感的本地自动化。两条通道怎么选看这张对比看什么云端控制本地控制指令由谁中转小米云小米中枢网关断外网时依赖外网断网不可用纯局域网照常工作延迟表现受外网波动影响近乎无延迟数据边界状态经云端中转数据不出局域网适合的场景出门在外远程控传感器联动、本地自动化⚠️ 几个版本与范围上的注意点中枢网关本地控制要求网关固件 3.3.0_0023 及以上或内置中枢网关软件 0.8.9 及以上且中枢网关目前仅在中国大陆可用另有一条局域网控制LAN通道只支持 WiFi/以太网连接的 IP 设备官方提示稳定性有限、建议谨慎使用。需要调整局域网控制参数时改 profile_models.yaml 里的内容即可。如果局域网内已有中枢网关会优先走网关通道无需额外配置。从检查版本到全屋上线三步走上手第 1 步先确认版本够新安装前确认 HA 版本不低于 2024.4.4Home Assistant Operating System 不低于 13.0并保证网络能正常访问小米云服务。版本太旧会缺组件依赖的接口后期排查很折腾。第 2 步装组件两条路任选其一HACS 安装在 HACS 里搜索 Xiaomi Home一键下载即可git 克隆安装拉取仓库后执行安装脚本它只接受一个参数——HA 的 config 目录路径git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/config⚠️ 无论哪种方式装完都必须重启 Home Assistant组件才会出现在集成列表里。第 3 步授权账号批量导入设备进入 HA 的设置 → 设备与服务 → 添加集成搜索 Xiaomi Home按提示登录小米账号并选择账号所属区域。可选区域有中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个由于各地区用户数据相互隔离选错区域就看不到对应地区的设备。授权成功后组件自动列出家庭和设备供你选择选中即整户导入。设备分散在多个区域也没关系不同区域的设备可以统一导入同一个 HA 实例集中调度支持多个小米账号同时登录账号多了也能归拢到一起。排障速查三个高频问题怎么解遇到不顺时按这个顺序排查基本都能定位设备连不上✅ 先确认网络能访问小米云可以ping api.io.mi.com试试再到米家 App 确认该账号对设备有控制权限排除设备本身离线。实体状态不同步✅ 依次尝试重启 Xiaomi Home 集成 → 清除.storage/xiaomi_home.*缓存文件 → 检查设备固件是否过旧。本地控制失效✅ 确认中枢网关与 HA 在同一局域网核对网关 IP 与配置是否一致确认设备在本地控制支持范围内WiFi/以太网。 还有一个容易踩的坑如果你改过 custom_components/xiaomi_home/miot/specs/ 下的转换规则文件如过滤、修改、多语言要到集成的配置页里执行一次更新实体转换规则改动才会生效。一夜之间全屋联动这些能力是怎么串起来的接入跑通后看一个具体的晚上傍晚进门门磁先触发回家场景玄关灯亮、空调切到舒适温度说一句看电影主灯暗下、氛围灯转暖色、电视音响同步开机夜里起身人体传感器点亮去卫生间的路径灯回床后自动熄灭早上出门离家模式关掉全部灯光、空调切到节能。这些联动成立的底气正是前面几步的叠加设备经 MIoT 协议顺利导入、云端或本地通道保证状态实时同步、转换引擎把每个设备能力暴露成标准 HA 实体。剩下的场景编排交给 HA 自动化本身就好。如果你手里有米家设备、机器上又跑着 HA那现在就是动手的最好时机——装好组件、授权一次账号全屋自动化的地基就铺完了。更多细节可以对照 官方文档 查看。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考