米家接入 Home Assistant：安装、登录与本地控制一次讲清
米家接入 Home Assistant安装、登录与本地控制一次讲清【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_home 是小米官方出品的米家 Home Assistant 集成组件把米家智能设备批量接入 Home Assistant统一看状态、下指令、做自动化。这篇讲 3 种安装方式、登录配置和本地控制怎么开照着走就能跑通适合第一次部署的用户。 前置检查版本与地区先对上号检查项要求Home Assistant Core≥ 2024.4.4Operating SystemHA OS 镜像≥ 13.0服务地区已部署中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个地区首次配置需选自己所在地区网络集成与米家设备尽量同局域网本地控制的前提版本不达标组件装不上地区没选对由于各地小米云数据相互隔离配置完设备列表永远是空的。 最小可行路径4 行命令装完3 种安装方式殊途同归最终都是把组件放进config/custom_components/xiaomi_home方式适合人群后续升级Git 克隆官方推荐能敲几条命令的用户切版本标签后重跑安装脚本HACS习惯用社区商店的用户HACS 内一键更新Samba / FTP 手动复制完全不碰终端的用户手动覆盖文件夹最快的路是 Git 克隆。SSH 登录 Home Assistant 服务器/config是Operating System镜像下的配置目录克隆仓库并执行安装脚本cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config重启 Home Assistant。脚本会先删掉custom_components/xiaomi_home旧版本再复制新版本重启后生效。以后升级在config/ha_xiaomi_home里执行git fetchgit checkout目标版本标签再重跑./install.sh /config回退版本同理。HACS 方式在 HACS 搜索Xiaomi Home进详情页点击下载即可。手动方式用 Samba 或 FTP 把custom_components/xiaomi_home文件夹整体复制到config/custom_components后重启。⚙️ 工作原理云端与本地两条链路状态同步和指令下发靠两条链路。MQTT≈ 设备消息的订阅制快递有消息就主动投递集成不用反复轮询云端。云端链路默认集成向小米云的 MQTT Broker 订阅设备消息设备属性变化或事件触发时云端主动推送状态同步是实时的配置完成时只全量拉取一次设备属性对云端压力很小。控制方向相反集成通过 MIoT 云端 HTTP 接口发指令由云端转发给设备执行。本地链路小米中枢网关内置一个标准 MQTT Broker集成直接经它订阅设备消息控制时把指令发布给 Broker再经网关转发到设备。设备 → 网关 → 集成整条链路在局域网内闭环减少对云端的依赖响应更快。设备怎么变成实体MIoT-Spec-V2相当于小米给每台设备下的标准说明书统一描述设备下的服务、属性、动作与事件。集成先按实例名匹配特殊规则转成空调、扫地机等专用实体未命中时按下表通用规则转换MIoT 类型条件生成的 HA 实体属性可写字符串格式Text属性可写布尔Switch属性可写带枚举值列表Select属性可写带数值范围Number属性只读Sensor事件任意Event 实体事件参数传入触发事件动作无参数Button动作带参数NotifyAction 调试模式开启时额外生成 Text风扇的工作模式枚举属性生成 Select童锁布尔属性生成 Switch长按按键事件生成 Event 实体可直接被自动化订阅。 配置全景必配到可选分三档必配小米账号登录→ 设置 设备与服务 添加集成搜索Xiaomi Home用OAuth 2.0授权登录全程不提交账号密码 → 注意登录成功后设备信息、证书、token 会保存在 HA 配置文件中。选择地区与家庭→ 登录成功弹出选择家庭与设备对话框勾选要导入的米家家庭该家庭下设备批量入网 → 注意地区按实际所在地选选错设备列表为空。推荐中枢网关本地控制→ 准备小米中枢网关固件3.3.0_0023及以上或内置中枢的设备软件0.8.9及以上与 HA 放同一局域网集成发现后自动切本地链路 → 注意中枢网关目前仅中国大陆可用。多账号管理→ 第一个账号配完后在 Xiaomi Home 集成页点添加中枢再走一遍登录接入第二个账号 → 注意不同账号的设备可放进同一个 Home Assistant 区域统一管理。可选局域网控制→ 设置 设备与服务 已配置 Xiaomi Home 配置 更新局域网控制配置让同局域网 IP 设备WiFi/网线走局域网通道 → 注意官方提示该功能可能引起个别异常、不建议开启局域网内已有中枢网关时它自动不生效。Action 调试模式→ 同一配置页开启带参数的设备动作额外显示为文本实体可手动填参数发指令 → 适合测试控制链路测完记得关。实体转换规则与翻译→ 修改miot/specs/目录下的过滤、翻译文件 → 注意改完必须在配置页点更新实体转换规则才生效。️ 边界与风险它做不到什么、已知坑纯蓝牙、红外、虚拟设备不支持→ 需要那台设备的话找同品类 WiFi 或 ZigBee 版本替代。登录后设备信息、证书、token 明文写在 HA 配置文件里→ 保管好配置文件定期到米家 APP 应用授权页检查异常立即撤销。局域网控制功能可能引起异常→ 本地控制优先走中枢网关局域网控制只当最后手段。中枢网关仅中国大陆可用→ 海外用户走云端链路或配合局域网控制覆盖同局域网 IP 设备。中枢网关固件过旧本地控制不生效→ 先在米家 APP 确认网关固件版本并升级到最新。❓ 问题速查新手最常问的 4 个Q1为什么我的蓝牙设备接不进来纯蓝牙、红外和虚拟设备目前不支持。替代方案是选同品类的 WiFi 或 ZigBee 版本设备。Q2没有中枢网关本地控制能用吗完整本地控制需要小米中枢网关固件3.3.0_0023或内置中枢的设备软件0.8.9。没有的话所有指令都走小米云局域网控制能部分替代只覆盖同局域网 IP 设备且官方不建议开启。Q3能同时登多个小米账号吗可以不同账号的设备还能放进同一个 Home Assistant 区域。方法第一个账号配完后在集成页点添加中枢再走一遍登录。Q4海外能用吗可以云服务已部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国。配置时选择自己所在地区对应地区的米家设备就能导入。 源码导航想深挖从哪几个模块入手模块职责何时需要看miot_client.py用户会话管理每加一个账号一个实例排查多账号接入问题miot_cloud.pyOAuth 登录、云端 HTTP 接口封装登录或云端指令失败时miot_device.py设备实体属性、事件、动作处理逻辑实体状态不对、指令不下发时miot_spec.py解析 MIoT-Spec-V2自定义实体转换逻辑miot_lan.py局域网设备发现与控制局域网控制不生效时两个最常用的自定义入口custom_components/xiaomi_home/miot/specs/spec_filter.yaml过滤掉不想转成实体的设备或功能支持通配符匹配。custom_components/xiaomi_home/miot/specs/multi_lang.json本地维护多语言词典可补充或改写厂商翻译生效优先级为本地配置 云端配置 默认英文。延伸让集成与米家设备保持同一局域网用 Home Assistant 区域给设备分组把米家设备事件接进自动化。留意版本更新日志并及时升级设备型号兼容修复多集中在小版本里。官方文档doc/README_zh.md版本更新日志CHANGELOG.md【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考