米家设备接入 Home Assistant 完整教程3 种装法让小米设备全部上线【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home想把家里一堆米家设备都收进同一个智能家居系统ha_xiaomi_home 是小米官方支持的集成组件它负责把米家设备成批搬进 Home Assistant接入之后看状态、发指令、做自动化都在同一块面板里完成。这篇教程从装前检查一路讲到本地控制和实体映射每一步都有明确操作。能接入什么米家 Home Assistant 集成覆盖范围 这个集成的核心动作是“批量导入”登录小米账号、勾选一个家庭该家庭下的设备会一次性出现在 Home Assistant 中各项能力自动转成实体不需要手写任何设备配置。覆盖面大致如下能用绝大多数米家设备品类多个小米账号可并存不同账号的设备能放进同一个 Home Assistant 区域。不能用纯蓝牙设备、红外设备、虚拟设备。手里的设备如果正好落在这三类里可以找同品类走联网连接的产品替代。装前自查2 个版本号与 1 个地区选择检查项最低要求Home Assistant Core2024.4.4Operating SystemOS 镜像13.0版本不够时配置流程会直接卡住先在“设置 → 系统 → 关于”里核对不达标就先升级。第二个容易踩的坑是地区。集成的云服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国共 6 个机房各地区的用户数据互相隔离——首次配置时必须选自己所在的地区否则登录成功也看不到任何设备。之后来自不同地区的设备也能汇入同一个区域统一管理。ha_xiaomi_home 安装教程3 条路线三条路线的终点一致把组件放到config/custom_components/xiaomi_home重启 Home Assistant 生效。路线适合谁以后怎么升级Git 克隆官方推荐会用终端切到目标 tag 后重跑 install.shHACS习惯社区商店HACS 内一键更新Samba / FTP 手动复制不想碰终端手动覆盖 xiaomi_home 文件夹路线一Git 克隆cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config官方文档推荐这条路理由在版本管理升级或回退时只需切到对应标签再跑一次 install.sh。以下面的示例标签 v1.0.0 为例cd config/ha_xiaomi_home git fetch git checkout v1.0.0 ./install.sh /config路线二HACS在 HACS 里搜索Xiaomi Home进入详情页点 Download 即完成安装全程不碰命令行。路线三Samba / FTP 手动复制通过 Samba 或 FTP 把custom_components/xiaomi_home文件夹整体拷进 Home Assistant 的config/custom_components目录重启即可。米家 HA 集成配置三步完成登录与设备入网装完重启后做三件事进入设置 → 设备与服务 → 添加集成搜索Xiaomi Home并进入。按页面提示完成OAuth 2.0授权登录。这是“第三方授权”流程小米只把读取账号设备数据的权限交给 Home Assistant账号密码全程不输入、不保存。登录成功后弹出“选择家庭与设备”对话框勾选要导入的米家家庭该家庭的设备随即批量出现在实体列表里。⚠️ 一句安全提醒密码确实不落地但登录成功后账号下的设备信息、证书、token 会以明文写在 HA 配置文件中。保管好这份文件并定期到米家 APP 的“应用授权”页检查发现异常立即撤销授权。进阶选项配置页里的 3 个开关入口设置 → 设备与服务 → 已配置 → Xiaomi Home → 配置。多账号。第一个账号配置完成后点“添加中枢”再走一遍登录即可加第二个小米账号不同账号的设备可放入同一区域统一管理。更新局域网控制配置。让与 HA 同一局域网的 IP 设备WiFi 或网线连接改走局域网通道绕开云端。注意两点它只覆盖 IP 设备蓝牙 Mesh、ZigBee 等协议的设备够不着局域网里若已有中枢网关这个开关也不会生效。官方提示该功能可能引起异常不建议随意开启。Action 调试模式。开启后带参数的设备动作会额外生成一个 Text 实体可以手动填参数直接向设备发指令用来验证控制链路是否通畅。消息怎么流动小米云与米家本地控制的两条路线 先看一张默认状态下的图先补一个名词MQTT Broker 可以理解为消息的“订阅制驿站”——事先登记好关心哪些设备之后设备状态一变驿站自己把消息送过来集成不用反复去查。默认走的是云端路线消息两个方向走不同通道状态同步集成在小米云的 MQTT Broker 上登记订阅设备属性变化或事件发生时由云端主动推送HA 实时更新。整个流程只在配置完成时全量拉取一次设备属性不做轮询云端压力很小。指令下发指令经 MIoT 云的 HTTP 接口发出由云端转发设备收到后执行。家里有小米中枢网关时可以切到本地路线中枢网关内置一个标准 MQTT Broker集成把订阅对象换成这个网关设备消息照样实时到手下发指令时只需发布到网关的 Broker再由网关转给设备。状态与指令都不再绕道云端整条链路在局域网内完成。完整本地控制的硬件门槛硬件最低版本小米中枢网关固件 3.3.0_0023 及以上内置中枢网关的设备软件 0.8.9 及以上注意中枢网关目前仅在中国大陆可用。没有中枢网关时所有指令都会经小米云发送。实体从哪来MIoT-Spec-V2 的映射规则实体不是手写的是按规则生成的。MIoT-Spec-V2 是小米 IoT 平台定义的“设备能力描述语言”结构分三层设备Device下挂多个服务Service服务里再分属性Property、动作Action、事件Event。集成把这几个要素翻译成 Home Assistant 实体的规则固定如下MIoT 要素条件生成的 HA 实体属性可写字符串格式Text属性可写布尔格式Switch属性可写带取值列表value-listSelect属性可写带数值范围value-rangeNumber属性只读Sensor事件任意Event参数随触发事件传入动作无输入参数Button动作有输入参数Notify几个具体例子风扇的“档位/模式”自然风、正常风等枚举→Select风扇的“童锁”开/关→Switch智能无线开关的“长按”事件 →Event触发时携带“按键类型”参数可直接用作自动化的触发条件智能音箱“播放文本”动作带 2 个参数 →Notify实体详情页 Attributes 会显示参数格式例如[Text Content(str), Silent Execution(bool)]照格式填[Hello, true]即可实体调优specs 目录里的两个文件最常用的两个“旋钮”都在 custom_components/xiaomi_home/miot/specs/ 下文件作用multi_lang.json本地多语言词典可补充或改写云端翻译spec_filter.yaml实体过滤器排除不想转换的服务与属性关于翻译实体名的翻译有两层来源——云端是设备厂商在 MIoT 云配置的多语言文件本地是你在multi_lang.json里维护的词典。生效优先级为本地 云端 默认英文。集成配置页本身提供 13 种语言可选含简体中文、英文、日语等。关于过滤在spec_filter.yaml里按设备 URN 登记再列出要排除的服务、属性、事件、动作的实例号iid支持通配符services写*即整台设备全部过滤。⚠️ 最后一步别漏修改 specs 目录下任何文件后要到集成配置页执行一次“更新实体转换规则”改动才会生效。高频疑问解答问蓝牙设备为什么不出现在实体列表答纯蓝牙、红外、虚拟设备目前不在支持范围内。如果确实离不开那台设备换同品类走联网连接的产品作为替代。问家里没有中枢网关会怎样答所有指令都会经小米云发送拿不到局域网闭环。想要完整本地控制需要中枢网关固件 3.3.0_0023 及以上或内置中枢网关的设备软件 0.8.9 及以上。“局域网控制”能部分改善体验但只覆盖同局域网的 IP 设备官方并不建议开启。问多个小米账号能并存吗答可以。第一个账号配置完成后再走一遍“添加中枢”的登录流程即可加第二个账号不同账号的设备可以放进同一个 Home Assistant 区域。问海外用户能用吗答能用。云服务覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个机房首次配置时选对自己的地区就能正常导入对应设备。源码读哪里5 个模块与自定义点想深入源码入口集中在 miot 目录模块职责miot_client.py用户会话管理每加一个账号多一个实例miot_cloud.pyOAuth 登录、云端 HTTP 接口封装miot_device.py设备实体属性、事件、动作的处理逻辑miot_spec.py解析 MIoT-Spec-V2miot_lan.py局域网设备发现与控制日常最常动的还是前面提到的两个文件spec_filter.yaml过滤实体、multi_lang.json改翻译。更多细节可查官方中文文档 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），仅供参考 米家设备接入 Home Assistant 完整教程：3 种装法让小米设备全部上线
米家设备接入 Home Assistant 完整教程3 种装法让小米设备全部上线【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home想把家里一堆米家设备都收进同一个智能家居系统ha_xiaomi_home 是小米官方支持的集成组件它负责把米家设备成批搬进 Home Assistant接入之后看状态、发指令、做自动化都在同一块面板里完成。这篇教程从装前检查一路讲到本地控制和实体映射每一步都有明确操作。能接入什么米家 Home Assistant 集成覆盖范围 这个集成的核心动作是“批量导入”登录小米账号、勾选一个家庭该家庭下的设备会一次性出现在 Home Assistant 中各项能力自动转成实体不需要手写任何设备配置。覆盖面大致如下能用绝大多数米家设备品类多个小米账号可并存不同账号的设备能放进同一个 Home Assistant 区域。不能用纯蓝牙设备、红外设备、虚拟设备。手里的设备如果正好落在这三类里可以找同品类走联网连接的产品替代。装前自查2 个版本号与 1 个地区选择检查项最低要求Home Assistant Core2024.4.4Operating SystemOS 镜像13.0版本不够时配置流程会直接卡住先在“设置 → 系统 → 关于”里核对不达标就先升级。第二个容易踩的坑是地区。集成的云服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国共 6 个机房各地区的用户数据互相隔离——首次配置时必须选自己所在的地区否则登录成功也看不到任何设备。之后来自不同地区的设备也能汇入同一个区域统一管理。ha_xiaomi_home 安装教程3 条路线三条路线的终点一致把组件放到config/custom_components/xiaomi_home重启 Home Assistant 生效。路线适合谁以后怎么升级Git 克隆官方推荐会用终端切到目标 tag 后重跑 install.shHACS习惯社区商店HACS 内一键更新Samba / FTP 手动复制不想碰终端手动覆盖 xiaomi_home 文件夹路线一Git 克隆cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config官方文档推荐这条路理由在版本管理升级或回退时只需切到对应标签再跑一次 install.sh。以下面的示例标签 v1.0.0 为例cd config/ha_xiaomi_home git fetch git checkout v1.0.0 ./install.sh /config路线二HACS在 HACS 里搜索Xiaomi Home进入详情页点 Download 即完成安装全程不碰命令行。路线三Samba / FTP 手动复制通过 Samba 或 FTP 把custom_components/xiaomi_home文件夹整体拷进 Home Assistant 的config/custom_components目录重启即可。米家 HA 集成配置三步完成登录与设备入网装完重启后做三件事进入设置 → 设备与服务 → 添加集成搜索Xiaomi Home并进入。按页面提示完成OAuth 2.0授权登录。这是“第三方授权”流程小米只把读取账号设备数据的权限交给 Home Assistant账号密码全程不输入、不保存。登录成功后弹出“选择家庭与设备”对话框勾选要导入的米家家庭该家庭的设备随即批量出现在实体列表里。⚠️ 一句安全提醒密码确实不落地但登录成功后账号下的设备信息、证书、token 会以明文写在 HA 配置文件中。保管好这份文件并定期到米家 APP 的“应用授权”页检查发现异常立即撤销授权。进阶选项配置页里的 3 个开关入口设置 → 设备与服务 → 已配置 → Xiaomi Home → 配置。多账号。第一个账号配置完成后点“添加中枢”再走一遍登录即可加第二个小米账号不同账号的设备可放入同一区域统一管理。更新局域网控制配置。让与 HA 同一局域网的 IP 设备WiFi 或网线连接改走局域网通道绕开云端。注意两点它只覆盖 IP 设备蓝牙 Mesh、ZigBee 等协议的设备够不着局域网里若已有中枢网关这个开关也不会生效。官方提示该功能可能引起异常不建议随意开启。Action 调试模式。开启后带参数的设备动作会额外生成一个 Text 实体可以手动填参数直接向设备发指令用来验证控制链路是否通畅。消息怎么流动小米云与米家本地控制的两条路线 先看一张默认状态下的图先补一个名词MQTT Broker 可以理解为消息的“订阅制驿站”——事先登记好关心哪些设备之后设备状态一变驿站自己把消息送过来集成不用反复去查。默认走的是云端路线消息两个方向走不同通道状态同步集成在小米云的 MQTT Broker 上登记订阅设备属性变化或事件发生时由云端主动推送HA 实时更新。整个流程只在配置完成时全量拉取一次设备属性不做轮询云端压力很小。指令下发指令经 MIoT 云的 HTTP 接口发出由云端转发设备收到后执行。家里有小米中枢网关时可以切到本地路线中枢网关内置一个标准 MQTT Broker集成把订阅对象换成这个网关设备消息照样实时到手下发指令时只需发布到网关的 Broker再由网关转给设备。状态与指令都不再绕道云端整条链路在局域网内完成。完整本地控制的硬件门槛硬件最低版本小米中枢网关固件 3.3.0_0023 及以上内置中枢网关的设备软件 0.8.9 及以上注意中枢网关目前仅在中国大陆可用。没有中枢网关时所有指令都会经小米云发送。实体从哪来MIoT-Spec-V2 的映射规则实体不是手写的是按规则生成的。MIoT-Spec-V2 是小米 IoT 平台定义的“设备能力描述语言”结构分三层设备Device下挂多个服务Service服务里再分属性Property、动作Action、事件Event。集成把这几个要素翻译成 Home Assistant 实体的规则固定如下MIoT 要素条件生成的 HA 实体属性可写字符串格式Text属性可写布尔格式Switch属性可写带取值列表value-listSelect属性可写带数值范围value-rangeNumber属性只读Sensor事件任意Event参数随触发事件传入动作无输入参数Button动作有输入参数Notify几个具体例子风扇的“档位/模式”自然风、正常风等枚举→Select风扇的“童锁”开/关→Switch智能无线开关的“长按”事件 →Event触发时携带“按键类型”参数可直接用作自动化的触发条件智能音箱“播放文本”动作带 2 个参数 →Notify实体详情页 Attributes 会显示参数格式例如[Text Content(str), Silent Execution(bool)]照格式填[Hello, true]即可实体调优specs 目录里的两个文件最常用的两个“旋钮”都在 custom_components/xiaomi_home/miot/specs/ 下文件作用multi_lang.json本地多语言词典可补充或改写云端翻译spec_filter.yaml实体过滤器排除不想转换的服务与属性关于翻译实体名的翻译有两层来源——云端是设备厂商在 MIoT 云配置的多语言文件本地是你在multi_lang.json里维护的词典。生效优先级为本地 云端 默认英文。集成配置页本身提供 13 种语言可选含简体中文、英文、日语等。关于过滤在spec_filter.yaml里按设备 URN 登记再列出要排除的服务、属性、事件、动作的实例号iid支持通配符services写*即整台设备全部过滤。⚠️ 最后一步别漏修改 specs 目录下任何文件后要到集成配置页执行一次“更新实体转换规则”改动才会生效。高频疑问解答问蓝牙设备为什么不出现在实体列表答纯蓝牙、红外、虚拟设备目前不在支持范围内。如果确实离不开那台设备换同品类走联网连接的产品作为替代。问家里没有中枢网关会怎样答所有指令都会经小米云发送拿不到局域网闭环。想要完整本地控制需要中枢网关固件 3.3.0_0023 及以上或内置中枢网关的设备软件 0.8.9 及以上。“局域网控制”能部分改善体验但只覆盖同局域网的 IP 设备官方并不建议开启。问多个小米账号能并存吗答可以。第一个账号配置完成后再走一遍“添加中枢”的登录流程即可加第二个账号不同账号的设备可以放进同一个 Home Assistant 区域。问海外用户能用吗答能用。云服务覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个机房首次配置时选对自己的地区就能正常导入对应设备。源码读哪里5 个模块与自定义点想深入源码入口集中在 miot 目录模块职责miot_client.py用户会话管理每加一个账号多一个实例miot_cloud.pyOAuth 登录、云端 HTTP 接口封装miot_device.py设备实体属性、事件、动作的处理逻辑miot_spec.py解析 MIoT-Spec-V2miot_lan.py局域网设备发现与控制日常最常动的还是前面提到的两个文件spec_filter.yaml过滤实体、multi_lang.json改翻译。更多细节可查官方中文文档 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），仅供参考