ha_xiaomi_home 如何把全屋米家设备接入 Home Assistant从登录到本地控制一次完成【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home这篇文章用倒推法展开先看做出来后的自动化成品再拆三步路径、原理与配置细节。主角是小米官方的 Home Assistant 集成 ha_xiaomi_home它负责把一屋子米家设备批量接入 HA覆盖版本自查、三种安装方式、账号登录、本地控制与实体映射规则读一遍即可完成完整接入。先看成品门磁触发开灯所有设备聚在一个面板读完这节你会知道目标长什么样后面所有步骤都在为它服务。晚上开门回家玄关灯自动亮起面板状态实时刷新点一下灯泡亮度滑块灯当场变暗——全程不打开米家 APP。这些实体和事件从哪来每台米家设备在小米云端都有一份功能说明书ha_xiaomi_home 登录你的账号后把说明书里的功能批量翻译成开关、数值、事件等标准 HA 实体自动化直接可用。接入米家设备的三步路径先记住骨架避免装到一半迷路装组件把组件放到config/custom_components/xiaomi_home目录登录账号OAuth 授权小米账号批量勾选家庭并导入设备选链路默认全走小米云有中枢网关就切本地控制响应更快。第 1 步之前有一道小闸门先做自查。为什么可行说明书与两条消息链路读完这节状态为什么不用轮询指令怎么送达设备就都通了。把设备消息理解成订阅制快递集成提前在消息站订阅设备属性变化或事件发生时会话主动送到门口不用反复跑去看。控制则相反是线上下单由站点代转给设备。云端链路站点是 MIoT 云的 MQTT 中枢。配置完成时集成只全量拉取一次设备属性之后全靠推送对云端压力很小下指令时走 MIoT 云 HTTP 接口由云转发给设备执行。本地链路站点换成屋内的收发室——小米中枢网关。它内置标准 MQTT Broker设备 → 网关 → 集成在局域网内闭环指令不必绕外网一圈响应更快、更不受网络波动影响。安装前自查版本与地区清单一分钟过完这张表不达标就先去升级别硬配。检查项要求Home Assistant Core≥ 2024.4.4Operating System 镜像≥ 13.0HACS仅 HACS 安装时需要≥ 1.34.0地区是软指标但最容易踩坑该集成已在中国大陆、欧洲、印度、俄罗斯、新加坡、美国等地区可用。小米云数据按地区隔离首次配置选错地区设备列表就是空的。不同地区的设备之后可以汇入同一个 HA 区域统一管理。安装 ha_xiaomi_homeGit、HACS、手动复制三条路殊途同归终点都是config/custom_components/xiaomi_home按自己的习惯选。路线一Git 克隆官方推荐。推荐理由是版本切换自由——升级或回退都是切 tag 再跑一次安装脚本cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config以后想换版本cd config/ha_xiaomi_home git fetch git checkout 目标版本tag ./install.sh /config路线二HACS。搜索框输入Xiaomi Home进详情页点 DOWNLOAD一键完成后续在 HACS 里一键更新。路线三手动复制。用 Samba 或 FTP 把custom_components/xiaomi_home文件夹整体拷到 HA 的config/custom_components下重启生效。3 分钟完成登录小米账号授权与家庭批量导入登录只有三个动作全程不用提交账号密码设置 设备与服务 添加集成搜索Xiaomi Home进入按页面提示用OAuth 2.0授权登录小米账号——第三方授权登录HA 不保存你的密码登录成功弹出选择家庭与设备对话框勾选要导入的家庭该家庭下设备批量出现在 HA 里。多个小米账号怎么办在已配置 Xiaomi Home页面点添加中枢再走一遍登录即可不同账号的设备还能放进同一个 HA 区域。同一页面随时可进 CONFIGURE 修改昵称、已导入设备列表等设置。本地控制完整配置中枢网关与局域网控制先给判断完整本地控制只有中枢网关这条路稳LAN 控制只是部分替代官方 README 明确建议不要开启。正式路径——中枢网关需要小米中枢网关固件 ≥ 3.3.0_0023或内置中枢网关功能的设备软件 ≥ 0.8.9。提醒中枢网关目前仅在中国大陆地区可购海外没有这块硬件的话指令全部走云。替代路径——局域网控制配置页里更新 LAN 控制配置只覆盖与 HA 同局域网的 IP 设备WiFi 或网线连接BLE Mesh、ZigBee 管不到。官方提示它可能引起个别异常且局域网内存在中枢网关时它即使开启也不生效。建议只调试时短暂开启。局域网设备发现与控制逻辑在 custom_components/xiaomi_home/miot/miot_lan.py这是负责 LAN 设备发现与控制的模块。一张表看懂实体翻译属性、事件、动作各变什么看完这张表你再看到新实体能立刻判断它为什么是开关而不是滑块。MIoT-Spec-V2 把产品定义为设备设备下挂多个服务服务里分属性、事件、动作三要素。通用转换规则如下说明书要素条件生成的 HA 实体属性可写、字符串Text属性可写、布尔Switch属性可写、带枚举值列表Select属性可写、带数值范围Number属性只读Sensor事件任意Event 实体参数传入触发事件动作无参数Button动作带参数Notify比如风扇工作模式枚举变 Select童锁布尔变 Switch。长按按键事件变 Event 实体小米无线双键开关长按时事件参数会带出按键类型1 表示右键自动化直接订阅就能用。还有一层特定转换集成先按实例名称匹配预定义的设备/服务规则匹配不上才落到上表通用规则规格命名空间不是小米定义非 miot-spec-v2的实体名前会加*标记。解析逻辑在 custom_components/xiaomi_home/miot/miot_spec.py这是解析 MIoT-Spec-V2 的模块。三个自定义入口过滤规则、多语言词典、动作调试想藏掉某些实体、改某处翻译、测试某条指令看这三个入口。1. 过滤实体在spec_filter.yaml里声明某设备哪些服务/属性/事件/动作不参与转换支持通配符urn:miot-spec-v2:device:gateway:0000A019:xiaomi-hub1: services: - 3 # 过滤掉 siid3 的服务 properties: - 4.* # 过滤掉 siid4 服务下的所有属性规则文件是 custom_components/xiaomi_home/miot/specs/spec_filter.yaml。所有设备的设备信息服务默认永不转换。2. 改翻译设备名、属性名默认从云端下载厂商配好的多语言文件本地multi_lang.json可自建词典本地优先级高于云端。配置流程界面本身提供 13 种语言可选。3. 动作调试配置页开启Debug mode for action后带参数的动作会额外生成一个文本实体按实体详情页标注的格式手动填参数如[Hello, true]就能发给设备方便验证控制链路通不通。记住一条改动 specs 目录下任何文件后必须在集成配置页执行一次更新实体转换规则否则不生效。避坑清单6 个开局就要记住的坑 ⚠️每条都容易踩、代价都不小带着清单过一遍。纯蓝牙、红外、虚拟设备不支持。确实需要的话换同品类 WiFi 或 ZigBee 版本。登录后设备列表为空九成是地区选错重走配置选回实际所在地区。令牌是明文存的。OAuth 不存密码是好消息但登录成功后设备信息、证书、token 会明文写在 HA 配置文件里文件泄露可被冒用。务必保管好配置文件怀疑泄露时去米家 APP 我的 账号管理页 基础信息应用删掉 Xiaomi Home 的授权。LAN 控制别急着开。只覆盖同局域网 IP 设备可能引起异常官方建议不用。改了 specs 没生效忘了点更新实体转换规则。某设备实体比预期少甚至没有特定转换要求必需的服务/属性/事件/动作全部匹配缺一个就不生成实体这是规则行为不是故障。高频问题速答蓝牙、本地、多账号、海外Q1纯蓝牙设备能接吗不能。蓝牙、红外、虚拟设备目前都不支持替代方案是用同品类的 WiFi 或 ZigBee 产品。Q2没有中枢网关本地控制能用吗完整本地控制不能。需要中枢网关固件 3.3.0_0023或内置中枢网关的设备软件 0.8.9否则指令全走小米云。LAN 控制可部分替代但只管同局域网 IP 设备。Q3能同时登多个小米账号吗能。集成页面点添加中枢再登录一次即可不同账号的设备可放进同一个 HA 区域。Q4海外能用吗能。云端服务覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国等地区配置时选自己所在地区即可跨地区设备还能汇入同一区域。Q5设备实体一个都没有或比预期少先查两件事是否被 spec_filter.yaml 过滤特定转换规则是否因缺少必需要素而未匹配。都没问题再对照官方文档排查。源码从哪读起以及接下来做什么想深入的话核心代码在custom_components/xiaomi_home/miot/目录四个关键文件custom_components/xiaomi_home/miot/miot_client.py用户会话管理每加一个小米账号就是一个实例custom_components/xiaomi_home/miot/miot_cloud.pyOAuth 登录与云端 HTTP 接口封装状态获取和指令下发的入口miot/miot_device.py设备实体处理属性、事件、动作逻辑doc/README_zh.md官方中文文档细节问题的第一查询处。接下来你可以做三件事用 HA 的区域功能把新导入的设备按房间分组拿门磁或无线开关的长按事件写第一条自动化触发参数开箱即用关注 CHANGELOG.md 的版本更新日志有新版及时升级。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考