米家设备接入 Home Assistant安装到跑通指南【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home米家 App 里一套设备Home Assistant 里又一套写个联动还要两头对状态特别烦。ha_xiaomi_home 是小米官方支持的 Home Assistant 集成登录一次小米账号米家设备就整体导入 HA状态同步、控制、触发事件全在一个平台里完成。 安装米家集成组件环境前提先核对一遍Home Assistant Core ≥ 2024.4.4Operating System 部署 ≥ 13.0小米设备已在米家 App 中配好并在线有一个能正常登录的小米账号整体链路是克隆 → 安装 → 重启 → 授权 → 设备导入。先拉代码。把仓库克隆到 HA 配置目录旁边方便后面升级时直接切 Tagcd /config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home执行安装脚本把custom_components/xiaomi_home整个目录复制到 HA 的自定义组件目录第一个参数是你的配置目录路径cd /config/ha_xiaomi_home bash install.sh /config最后一行输出Xiaomi Home installation is completed且/config/custom_components/xiaomi_home目录存在就是装好了。重启 Home Assistant到「设置 设备与服务 添加集成」里能搜到Xiaomi Home说明组件已被识别。报does not exist是配置目录路径没传或传错了报权限错误就换成对该目录有写权限的用户执行。⚡ 理解云端与本地两种控制模式重启后的配置流程是纯界面操作同意条款 → 选择账号地区和语言 → 浏览器里走 OAuth 授权不保存你的账号密码→ 选择要导入的家庭 → 完成。整个交互定义在 config_flow.py 里选家庭那一步还能顺手填房间名同步规则和勾选高级选项。授权成功后集成的工作链路是这样的。默认走云端集成订阅小米云 MQTT Broker 上的设备消息设备属性一变或事件一发生消息就推过来不用轮询控制指令则通过小米云 HTTP 接口下发。如果你有小米中枢网关固件 ≥ 3.3.0_0023目前仅中国大陆可用控制通道就换成局域网网关内置标准 MQTT Broker订阅和发布全在局域网内完成不经过公网。两种模式对比维度云端模式本地模式消息通道小米云 MQTT中枢网关内置 MQTT Broker控制路径HTTP API → 云 → 设备局域网直接发布延迟受公网影响局域网级断外网时不可用可用硬件要求无小米中枢网关固件 ≥ 3.3.0_0023默认控制模式是auto检测到中枢网关就走本地在高级选项里可手动切cloud。核心代码都装在 custom_components/xiaomi_home/ 下和日常操作相关的几处ha_xiaomi_home/ ├── custom_components/xiaomi_home/ # 集成主体install.sh 复制的就是它 │ ├── config_flow.py # 上面走的配置流程 │ └── miot/ # 协议核心miot_client 总控、miot_cloud 云接口、 │ # miot_mips 消息总线、miot_lan 局域网控制 ├── doc/ # 中英文文档 └── test/ # 测试脚本实体是怎么来的小米给每款设备定义了 MIoT-Spec-V2 物模型集成按它生成 HA 实体可写属性变成switch/number/select/text只读属性变sensor事件变 event 实体可直接当自动化触发器无参方法变button带参方法变notify。解析和转换逻辑在 miot_spec.py蓝牙、红外和虚拟设备目前不支持。登录后的证书、token 会明文存在 HA 配置目录里这个目录的权限一定要管好泄露等于账号被冒用。️ 让米家设备真正好用断网时控制不丢前提家里有小米中枢网关固件升级到 3.3.0_0023 以上操作「设置 设备与服务 已配置 Xiaomi Home 配置」把控制模式设为自动默认值效果网关和设备在同一个局域网时状态推送和控制指令全部走局域网外网断了本地联动照跑只导入想要的设备设备多的话别全量导入配置流程里就支持过滤在选择家庭那一步勾选高级选项开启设备过滤支持按房间、连接类型WiFi / 蓝牙 / ZigBee 等、设备型号、单台设备筛选每项都能选包含或排除条件间可用与/或逻辑组合后续想调整进「配置」里的设备更新流程即可让设备名和状态说你想听的话设备实体名来自小米云下发的多语言文件multi_lang.json 可以在本地覆盖它优先级更高。改的是 HA 配置目录里config/custom_components/xiaomi_home/miot/specs/multi_lang.json这份副本格式是设备urn → 语言代码 → 实例代码 → 译文比如给一个设备改服务名{ urn:miot-spec-v2:device:air-purifier:0000A017:xiaomi-mc1: { zh-Hans: { service:002: 净化器, service:002:property:001: 运行模式 } } }同理spec_filter.yaml 可以按设备 urn 排除不想生成的服务、属性、事件格式见文件内注释。改完specs/下任何文件都不生效必须去「Xiaomi Home 配置 更新实体转换规则」触发一次重新加载。手动发 Action 指令调试设备想验证这个方法发过去设备到底怎么响应不用写自动化「Xiaomi Home 配置」里打开 Action 调试模式带参数的方法notify 实体会额外多一个 Text 实体把参数按[值1, 值2]格式填进去发送即可参数格式在 notify 实体详情页的 Attributes 里有例如音箱的播放指令是[文本(str), 静音执行(bool)]填[你好, true]事件侧也一样好试开关、传感器的长按/短按事件都生成了 event 实体在 HA 自动化里直接拿它当 trigger不用碰任何源码。卡住了怎么办现象登录成功但选择家庭与设备里没有设备最可能原因账号注册地和你选的地区不一致米家数据按地区隔离大陆、欧洲、印度、俄罗斯、新加坡、美国各一套。验证去米家 App 确认账号归属地删掉当前集成实例重新添加在认证配置一步选对地区。现象配置流程卡在 OAuth 授权一步最可能原因HA 服务器访问不了小米云或 OAuth 重定向地址被改过。验证在 HA 日志里grep -i Xiaomi Home找ERROR行重点看含oauth的条目。解决确认服务器能正常访问外网重定向地址用配置页预填值别手改。现象家里有中枢网关但日志显示仍走云端最可能原因网关固件版本低于 3.3.0_0023或网关和 HA 不在同一网段。验证米家 App 里看网关固件版本HA 配置页正常情况下会提示发现本地中枢网关没有这条提示就是没发现。解决升级网关固件把网关和 HA 放进同一局域网。现象改了 multi_lang.json实体名没变最可能原因改完没有触发规则重载改的是克隆目录而不是 HA 配置目录里的副本。验证确认文件改在config/custom_components/下。解决「Xiaomi Home 配置 更新实体转换规则」。想继续深入的话看看 doc/CONTRIBUTING_zh.md 了解贡献流程或翻 test/ 目录里的测试脚本它们是最好的源码导读。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/6 20:56:21 · 阅读 1.2k 米家设备接入 Home Assistant：安装到跑通指南
米家设备接入 Home Assistant安装到跑通指南【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home米家 App 里一套设备Home Assistant 里又一套写个联动还要两头对状态特别烦。ha_xiaomi_home 是小米官方支持的 Home Assistant 集成登录一次小米账号米家设备就整体导入 HA状态同步、控制、触发事件全在一个平台里完成。 安装米家集成组件环境前提先核对一遍Home Assistant Core ≥ 2024.4.4Operating System 部署 ≥ 13.0小米设备已在米家 App 中配好并在线有一个能正常登录的小米账号整体链路是克隆 → 安装 → 重启 → 授权 → 设备导入。先拉代码。把仓库克隆到 HA 配置目录旁边方便后面升级时直接切 Tagcd /config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home执行安装脚本把custom_components/xiaomi_home整个目录复制到 HA 的自定义组件目录第一个参数是你的配置目录路径cd /config/ha_xiaomi_home bash install.sh /config最后一行输出Xiaomi Home installation is completed且/config/custom_components/xiaomi_home目录存在就是装好了。重启 Home Assistant到「设置 设备与服务 添加集成」里能搜到Xiaomi Home说明组件已被识别。报does not exist是配置目录路径没传或传错了报权限错误就换成对该目录有写权限的用户执行。⚡ 理解云端与本地两种控制模式重启后的配置流程是纯界面操作同意条款 → 选择账号地区和语言 → 浏览器里走 OAuth 授权不保存你的账号密码→ 选择要导入的家庭 → 完成。整个交互定义在 config_flow.py 里选家庭那一步还能顺手填房间名同步规则和勾选高级选项。授权成功后集成的工作链路是这样的。默认走云端集成订阅小米云 MQTT Broker 上的设备消息设备属性一变或事件一发生消息就推过来不用轮询控制指令则通过小米云 HTTP 接口下发。如果你有小米中枢网关固件 ≥ 3.3.0_0023目前仅中国大陆可用控制通道就换成局域网网关内置标准 MQTT Broker订阅和发布全在局域网内完成不经过公网。两种模式对比维度云端模式本地模式消息通道小米云 MQTT中枢网关内置 MQTT Broker控制路径HTTP API → 云 → 设备局域网直接发布延迟受公网影响局域网级断外网时不可用可用硬件要求无小米中枢网关固件 ≥ 3.3.0_0023默认控制模式是auto检测到中枢网关就走本地在高级选项里可手动切cloud。核心代码都装在 custom_components/xiaomi_home/ 下和日常操作相关的几处ha_xiaomi_home/ ├── custom_components/xiaomi_home/ # 集成主体install.sh 复制的就是它 │ ├── config_flow.py # 上面走的配置流程 │ └── miot/ # 协议核心miot_client 总控、miot_cloud 云接口、 │ # miot_mips 消息总线、miot_lan 局域网控制 ├── doc/ # 中英文文档 └── test/ # 测试脚本实体是怎么来的小米给每款设备定义了 MIoT-Spec-V2 物模型集成按它生成 HA 实体可写属性变成switch/number/select/text只读属性变sensor事件变 event 实体可直接当自动化触发器无参方法变button带参方法变notify。解析和转换逻辑在 miot_spec.py蓝牙、红外和虚拟设备目前不支持。登录后的证书、token 会明文存在 HA 配置目录里这个目录的权限一定要管好泄露等于账号被冒用。️ 让米家设备真正好用断网时控制不丢前提家里有小米中枢网关固件升级到 3.3.0_0023 以上操作「设置 设备与服务 已配置 Xiaomi Home 配置」把控制模式设为自动默认值效果网关和设备在同一个局域网时状态推送和控制指令全部走局域网外网断了本地联动照跑只导入想要的设备设备多的话别全量导入配置流程里就支持过滤在选择家庭那一步勾选高级选项开启设备过滤支持按房间、连接类型WiFi / 蓝牙 / ZigBee 等、设备型号、单台设备筛选每项都能选包含或排除条件间可用与/或逻辑组合后续想调整进「配置」里的设备更新流程即可让设备名和状态说你想听的话设备实体名来自小米云下发的多语言文件multi_lang.json 可以在本地覆盖它优先级更高。改的是 HA 配置目录里config/custom_components/xiaomi_home/miot/specs/multi_lang.json这份副本格式是设备urn → 语言代码 → 实例代码 → 译文比如给一个设备改服务名{ urn:miot-spec-v2:device:air-purifier:0000A017:xiaomi-mc1: { zh-Hans: { service:002: 净化器, service:002:property:001: 运行模式 } } }同理spec_filter.yaml 可以按设备 urn 排除不想生成的服务、属性、事件格式见文件内注释。改完specs/下任何文件都不生效必须去「Xiaomi Home 配置 更新实体转换规则」触发一次重新加载。手动发 Action 指令调试设备想验证这个方法发过去设备到底怎么响应不用写自动化「Xiaomi Home 配置」里打开 Action 调试模式带参数的方法notify 实体会额外多一个 Text 实体把参数按[值1, 值2]格式填进去发送即可参数格式在 notify 实体详情页的 Attributes 里有例如音箱的播放指令是[文本(str), 静音执行(bool)]填[你好, true]事件侧也一样好试开关、传感器的长按/短按事件都生成了 event 实体在 HA 自动化里直接拿它当 trigger不用碰任何源码。卡住了怎么办现象登录成功但选择家庭与设备里没有设备最可能原因账号注册地和你选的地区不一致米家数据按地区隔离大陆、欧洲、印度、俄罗斯、新加坡、美国各一套。验证去米家 App 确认账号归属地删掉当前集成实例重新添加在认证配置一步选对地区。现象配置流程卡在 OAuth 授权一步最可能原因HA 服务器访问不了小米云或 OAuth 重定向地址被改过。验证在 HA 日志里grep -i Xiaomi Home找ERROR行重点看含oauth的条目。解决确认服务器能正常访问外网重定向地址用配置页预填值别手改。现象家里有中枢网关但日志显示仍走云端最可能原因网关固件版本低于 3.3.0_0023或网关和 HA 不在同一网段。验证米家 App 里看网关固件版本HA 配置页正常情况下会提示发现本地中枢网关没有这条提示就是没发现。解决升级网关固件把网关和 HA 放进同一局域网。现象改了 multi_lang.json实体名没变最可能原因改完没有触发规则重载改的是克隆目录而不是 HA 配置目录里的副本。验证确认文件改在config/custom_components/下。解决「Xiaomi Home 配置 更新实体转换规则」。想继续深入的话看看 doc/CONTRIBUTING_zh.md 了解贡献流程或翻 test/ 目录里的测试脚本它们是最好的源码导读。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考