米家接入 Home Assistant 三步完成Xiaomi Home 集成安装步骤与云端本地控制完整指南【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home米家集成Xiaomi Home仓库代号 ha_xiaomi_home是小米官方支持的 Home Assistant 第三方组件作用是把小米 IoT 设备以 MIoT 官方协议接入 HA替代以往靠抓包逆向、插件一更新就失效的第三方桥接方案。结论先行只要 HA Core 版本不低于 2024.4.4、能用小米账号登录米家、网络可达小米云服务部署过程不需要写任何代码设备列表与实体均由组件自动完成。环境预检安装前核对的 3 个条件检查项达标线不达标的影响HA 版本Core ≥ 2024.4.4Operating System ≥ 13.0组件依赖的平台接口缺失加载即报错网络出口能访问 io.mi.com 域名的 HTTP/HTTPS 与 8883 端口OAuth 登录与云端订阅均会超时小米账号目标设备已出现在该账号的米家家庭内授权后看不到设备导入列表为空⚠️ 版本检查入口HA 右上角头像处可查 Core 版本。若低于达标线先升级再安装避免在旧版本上排查依赖问题。米家集成安装步骤两种主流方式任选其一。共同点是装完后必须重启 Home Assistant集成才会出现在列表里。方式 Agit clone官方推荐便于按 tag 回退版本git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/configinstall.sh只接受一个参数——HA 的config目录绝对路径。脚本行为固定先删除目标位置的旧版custom_components/xiaomi_home再复制新版最后打印完成提示。要锁定或回退版本在克隆目录内执行git fetch加git checkout切到对应 tag再重跑一次脚本即可。方式 BHACS在 HACS 搜索框输入Xiaomi Home进入详情页点击下载随后重启 HA。还有第三种手动方式把custom_components/xiaomi_home目录整体复制到 HA 配置目录下的custom_components/内适合不方便执行脚本的容器环境。小米账号授权与设备导入动线安装完成重启后全部操作在 HA 界面内点击完成设置 → 设备与服务 → 添加集成 → 搜索Xiaomi Home→ 下一步点击登录按钮用小米账号完成 OAuth 2.0 授权组件不保存你的账号密码选择账号所属区域候选机房为中国大陆、欧洲、印度、俄罗斯、新加坡、美国在选择家庭与设备对话框中勾选要导入的米家家庭该家庭下所有设备批量进入 HA无需逐台添加。多账号场景进入已配置页设置 → 设备与服务 → 已配置 → Xiaomi Home点添加中枢可再登录另一个小米账号。不同账号、不同区域机房的设备可以并入同一个 HA 区域统一管理。导入后的常用入口都在集成配置页CONFIGURE里修改用户昵称、刷新设备列表、开启 Action 调试模式开启后带参方法会以文本实体形式暴露可手动下发调试指令。米家集成云端控制原理没有中枢网关时所有通信经小米云中转分工如下状态上行组件在云端 MQTT Brokerha.mqtt.io.mi.com上订阅指定设备的消息。属性变更、事件触发、上下线都会实时推送过来组件不轮询——它只在配置完成时向云端拉取一次全量属性值之后的访问压力接近于零。指令下行HA 里发出的控制请求走云端 HTTP 接口ha.api.io.mi.com由云转发到设备。代价是链路多一跳状态新鲜度受公网质量影响出门在外时可用但对延迟敏感的本地联动不是最优解。米家集成本地控制原理与限制局域网路径有两条能力与适用范围差异很大中枢网关通道推荐小米中枢网关固件 3.3.0_0023 及以上或内置中枢能力的设备软件 0.8.9 及以上内嵌标准 MQTT Broker。组件通过 zeroconf 发现网内的_miot-central._tcp.local.服务后自动切换状态订阅与指令发布全部发生在局域网内。局域网直连通道谨慎直接走 UDP 与 WiFi/以太网设备对话不依赖网关全区域可用。但它管不到蓝牙 Mesh、Zigbee 设备且官方提示可能引起异常只要网内存在中枢网关该通道自动让位不生效。⚠️ 中枢网关通道目前仅限中国大陆区域组件源码custom_components/xiaomi_home/miot/const.py中SUPPORT_CENTRAL_GATEWAY_CTRL只列了cn。海外账号请默认走云端链路。两种链路的取舍远程可达性选云端响应速度与数据不出内网选中枢网关两者对上层实体完全透明切换不改变 HA 里的任何配置。实体自动生成规则MIoT-Spec-V2 如何映射成 HA 实体小米设备的能力描述遵循 MIoT-Spec-V2小米物联网物模型协议设备 → 服务 → 属性/事件/方法。组件用 custom_components/xiaomi_home/miot/specs/specv2entity.py 把这份描述翻译成 HA 实体设备导入完成即实体就绪。核心映射MIoT-Spec-V2 元素条件生成的 HA 实体属性Property可写 字符串类型Text属性Property可写 布尔类型Switch属性Property可写 非字符串/布尔 有取值列表Select属性Property可写 非字符串/布尔 无取值列表但有取值范围Number属性Property只读Sensor事件Event事件参数透传至实体触发回调Event方法Action入参为空Button方法Action入参非空Notify调试模式下另加 Text 实体三条容易踩坑的细节转换分两层先按实例名称匹配特殊规则如识别出 climate、vacuum 等特定领域匹配不上才落到上表的一般规则设备缺少规则要求的必备服务/属性/事件时不生成实体这是预期行为而非故障非小米定义的命名空间如厂商自定义实体名前会带星号标记。规则文件都在 custom_components/xiaomi_home/miot/specs/ 下spec_filter.yaml屏蔽不想要实例multi_lang.json是本地多语言词典优先级高于云端下发的翻译spec_modify.yaml修正属性行为。改完任意文件后必须到集成配置页点更新实体转换规则才生效。设备覆盖范围与多语言支持实体侧已实现 18 个平台模块覆盖 custom_components/xiaomi_home/ 下的 light、switch、sensor、climate、fan、humidifier、cover、vacuum、water_heater、media_player、binary_sensor、number、select、text、button、event、device_tracker、notify。不支持的品类只有三类蓝牙设备、红外设备、虚拟设备。语言方面custom_components/xiaomi_home/translations/目录内置 13 种界面语言简中、繁中、英、日、德、法、西、俄、意、荷、葡、巴西葡、土耳其配置向导页面随 HA 语言自动切换实体名称的翻译则来自云端多语言文件叠加本地词典。米家集成排障顺序按故障现象对号入座从上往下逐项排除设备列表为空 / 登录失败确认 HA 能访问 io.mi.com确认目标设备挂在这个小米账号的米家家庭下共享设备需在米家 App 中确认授权换一次授权重试。实体状态不更新先重启集成 → 再清除.storage目录下 xiaomi_home 相关缓存文件后重启 → 最后检查设备固件是否过旧。本地控制不通确认中枢网关与 HA 同网段网关固件 ≥ 3.3.0_0023被控设备必须是 WiFi 或以太网接入Mesh/ZigBee 设备不在直连范围若网内已有中枢网关不要指望局域网直连生效。疑似授权泄露HA 的配置文件里明文存放设备信息与 tokenOAuth 流程不存密码一旦怀疑泄露到米家 App → 我的 → 账号管理 → 应用授权移除 Xiaomi Home (Home Assistant Integration) 的授权。⚠️ 因此 HA 配置目录的访问权限要管好拿到配置目录的人等同于拿到你米家账号的设备控制权。一套能跑起来的晚间联动把这些能力串成一个具体画面傍晚门磁实体触发回家自动化玄关灯light 实体点亮、空调伴侣climate 实体切到舒适档位——若家里部署了中枢网关这组触发与执行全程在局域网内完成夜里人体传感器sensor 实体检测到活动走廊灯亮起静止两分钟后由同一条自动化的延时条件关灯出门前一键场景Button 实体触发的自动化关全部灯光、空调转节能。整条链路里设备导入靠一次 OAuth 授权状态同步靠云端或本地 MQTT 推送能力暴露靠 MIoT-Spec-V2 映射——用户唯一需要写的是 HA 自动化编辑器里那几条条件。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 米家接入 Home Assistant 三步完成：Xiaomi Home 集成安装步骤与云端本地控制完整指南
米家接入 Home Assistant 三步完成Xiaomi Home 集成安装步骤与云端本地控制完整指南【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home米家集成Xiaomi Home仓库代号 ha_xiaomi_home是小米官方支持的 Home Assistant 第三方组件作用是把小米 IoT 设备以 MIoT 官方协议接入 HA替代以往靠抓包逆向、插件一更新就失效的第三方桥接方案。结论先行只要 HA Core 版本不低于 2024.4.4、能用小米账号登录米家、网络可达小米云服务部署过程不需要写任何代码设备列表与实体均由组件自动完成。环境预检安装前核对的 3 个条件检查项达标线不达标的影响HA 版本Core ≥ 2024.4.4Operating System ≥ 13.0组件依赖的平台接口缺失加载即报错网络出口能访问 io.mi.com 域名的 HTTP/HTTPS 与 8883 端口OAuth 登录与云端订阅均会超时小米账号目标设备已出现在该账号的米家家庭内授权后看不到设备导入列表为空⚠️ 版本检查入口HA 右上角头像处可查 Core 版本。若低于达标线先升级再安装避免在旧版本上排查依赖问题。米家集成安装步骤两种主流方式任选其一。共同点是装完后必须重启 Home Assistant集成才会出现在列表里。方式 Agit clone官方推荐便于按 tag 回退版本git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/homeassistant/configinstall.sh只接受一个参数——HA 的config目录绝对路径。脚本行为固定先删除目标位置的旧版custom_components/xiaomi_home再复制新版最后打印完成提示。要锁定或回退版本在克隆目录内执行git fetch加git checkout切到对应 tag再重跑一次脚本即可。方式 BHACS在 HACS 搜索框输入Xiaomi Home进入详情页点击下载随后重启 HA。还有第三种手动方式把custom_components/xiaomi_home目录整体复制到 HA 配置目录下的custom_components/内适合不方便执行脚本的容器环境。小米账号授权与设备导入动线安装完成重启后全部操作在 HA 界面内点击完成设置 → 设备与服务 → 添加集成 → 搜索Xiaomi Home→ 下一步点击登录按钮用小米账号完成 OAuth 2.0 授权组件不保存你的账号密码选择账号所属区域候选机房为中国大陆、欧洲、印度、俄罗斯、新加坡、美国在选择家庭与设备对话框中勾选要导入的米家家庭该家庭下所有设备批量进入 HA无需逐台添加。多账号场景进入已配置页设置 → 设备与服务 → 已配置 → Xiaomi Home点添加中枢可再登录另一个小米账号。不同账号、不同区域机房的设备可以并入同一个 HA 区域统一管理。导入后的常用入口都在集成配置页CONFIGURE里修改用户昵称、刷新设备列表、开启 Action 调试模式开启后带参方法会以文本实体形式暴露可手动下发调试指令。米家集成云端控制原理没有中枢网关时所有通信经小米云中转分工如下状态上行组件在云端 MQTT Brokerha.mqtt.io.mi.com上订阅指定设备的消息。属性变更、事件触发、上下线都会实时推送过来组件不轮询——它只在配置完成时向云端拉取一次全量属性值之后的访问压力接近于零。指令下行HA 里发出的控制请求走云端 HTTP 接口ha.api.io.mi.com由云转发到设备。代价是链路多一跳状态新鲜度受公网质量影响出门在外时可用但对延迟敏感的本地联动不是最优解。米家集成本地控制原理与限制局域网路径有两条能力与适用范围差异很大中枢网关通道推荐小米中枢网关固件 3.3.0_0023 及以上或内置中枢能力的设备软件 0.8.9 及以上内嵌标准 MQTT Broker。组件通过 zeroconf 发现网内的_miot-central._tcp.local.服务后自动切换状态订阅与指令发布全部发生在局域网内。局域网直连通道谨慎直接走 UDP 与 WiFi/以太网设备对话不依赖网关全区域可用。但它管不到蓝牙 Mesh、Zigbee 设备且官方提示可能引起异常只要网内存在中枢网关该通道自动让位不生效。⚠️ 中枢网关通道目前仅限中国大陆区域组件源码custom_components/xiaomi_home/miot/const.py中SUPPORT_CENTRAL_GATEWAY_CTRL只列了cn。海外账号请默认走云端链路。两种链路的取舍远程可达性选云端响应速度与数据不出内网选中枢网关两者对上层实体完全透明切换不改变 HA 里的任何配置。实体自动生成规则MIoT-Spec-V2 如何映射成 HA 实体小米设备的能力描述遵循 MIoT-Spec-V2小米物联网物模型协议设备 → 服务 → 属性/事件/方法。组件用 custom_components/xiaomi_home/miot/specs/specv2entity.py 把这份描述翻译成 HA 实体设备导入完成即实体就绪。核心映射MIoT-Spec-V2 元素条件生成的 HA 实体属性Property可写 字符串类型Text属性Property可写 布尔类型Switch属性Property可写 非字符串/布尔 有取值列表Select属性Property可写 非字符串/布尔 无取值列表但有取值范围Number属性Property只读Sensor事件Event事件参数透传至实体触发回调Event方法Action入参为空Button方法Action入参非空Notify调试模式下另加 Text 实体三条容易踩坑的细节转换分两层先按实例名称匹配特殊规则如识别出 climate、vacuum 等特定领域匹配不上才落到上表的一般规则设备缺少规则要求的必备服务/属性/事件时不生成实体这是预期行为而非故障非小米定义的命名空间如厂商自定义实体名前会带星号标记。规则文件都在 custom_components/xiaomi_home/miot/specs/ 下spec_filter.yaml屏蔽不想要实例multi_lang.json是本地多语言词典优先级高于云端下发的翻译spec_modify.yaml修正属性行为。改完任意文件后必须到集成配置页点更新实体转换规则才生效。设备覆盖范围与多语言支持实体侧已实现 18 个平台模块覆盖 custom_components/xiaomi_home/ 下的 light、switch、sensor、climate、fan、humidifier、cover、vacuum、water_heater、media_player、binary_sensor、number、select、text、button、event、device_tracker、notify。不支持的品类只有三类蓝牙设备、红外设备、虚拟设备。语言方面custom_components/xiaomi_home/translations/目录内置 13 种界面语言简中、繁中、英、日、德、法、西、俄、意、荷、葡、巴西葡、土耳其配置向导页面随 HA 语言自动切换实体名称的翻译则来自云端多语言文件叠加本地词典。米家集成排障顺序按故障现象对号入座从上往下逐项排除设备列表为空 / 登录失败确认 HA 能访问 io.mi.com确认目标设备挂在这个小米账号的米家家庭下共享设备需在米家 App 中确认授权换一次授权重试。实体状态不更新先重启集成 → 再清除.storage目录下 xiaomi_home 相关缓存文件后重启 → 最后检查设备固件是否过旧。本地控制不通确认中枢网关与 HA 同网段网关固件 ≥ 3.3.0_0023被控设备必须是 WiFi 或以太网接入Mesh/ZigBee 设备不在直连范围若网内已有中枢网关不要指望局域网直连生效。疑似授权泄露HA 的配置文件里明文存放设备信息与 tokenOAuth 流程不存密码一旦怀疑泄露到米家 App → 我的 → 账号管理 → 应用授权移除 Xiaomi Home (Home Assistant Integration) 的授权。⚠️ 因此 HA 配置目录的访问权限要管好拿到配置目录的人等同于拿到你米家账号的设备控制权。一套能跑起来的晚间联动把这些能力串成一个具体画面傍晚门磁实体触发回家自动化玄关灯light 实体点亮、空调伴侣climate 实体切到舒适档位——若家里部署了中枢网关这组触发与执行全程在局域网内完成夜里人体传感器sensor 实体检测到活动走廊灯亮起静止两分钟后由同一条自动化的延时条件关灯出门前一键场景Button 实体触发的自动化关全部灯光、空调转节能。整条链路里设备导入靠一次 OAuth 授权状态同步靠云端或本地 MQTT 推送能力暴露靠 MIoT-Spec-V2 映射——用户唯一需要写的是 HA 自动化编辑器里那几条条件。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考