米家设备接入 Home Assistant 完整指南3 种安装方式与本地控制一次讲清【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_home 是小米官方为 Home Assistant 开发的米家集成组件作用很直接把米家生态里的智能设备批量接入 Home Assistant在同一个面板里完成状态查看、指令下发和自动化编排。这篇小米 HA 插件安装教程面向新手也兼顾进阶——从版本要求、3 种安装方式到登录配置、本地控制、MIoT 协议实体映射规则一次讲清。先说结论它能帮你管好一屋子米家设备品类覆盖广绝大多数米家设备品类都能接入只有纯蓝牙、红外和虚拟设备暂不支持。多账号同时接入多个小米账号可以并存不同账号的设备还能放进同一个 Home Assistant 区域。云 本地混合控制默认走小米云配了小米中枢网关后切换为米家本地控制响应更快、更少依赖云端。实体自动标准化基于 MIoT-Spec-V2 协议把设备功能翻译成 Home Assistant 实体属性、事件、动作各归其位不用手写实体配置。顺便解释一下 MIoT-Spec-V2它相当于小米给每台设备下的标准说明书统一描述设备有哪些功能、状态和动作后文会讲它如何映射成实体。动手前版本要求和适用地区先对上号安装前先确认两个硬指标不满足的话配置流程会卡住检查项要求Home Assistant Core≥ 2024.4.4Operating SystemHA 操作系统镜像≥ 13.0地区方面该集成已部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国等地区海外用户同样可用。由于各地区小米云的数据相互隔离首次配置时记得选择自己所在的地区否则设备列表会是空的不同地区的设备之后也可以汇入同一个区域。3 种安装方式怎么选方式适合人群后续升级方式Git 克隆官方推荐愿意敲几条命令的用户git fetch后切到目标版本标签重跑 install.shHACS习惯用社区商店的用户HACS 内一键更新Samba / FTP 手动复制完全不想碰终端的用户手动覆盖custom_components/xiaomi_home文件夹三条路殊途同归最终都是把组件放到config/custom_components/xiaomi_home下。Git 克隆方式cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config官方更推荐这条路以后想升级到某个版本切到对应的 Git 标签tag再执行一次./install.sh /config就行版本回退也一样方便。HACS 方式在 HACS 里搜索Xiaomi Home进入详情页点击下载即可完成 HACS 安装 ha_xiaomi_home全程不用接触命令行。手动复制方式通过 Samba 或 FTP 把custom_components/xiaomi_home文件夹整体复制到 Home Assistant 的config/custom_components目录重启后生效。首次配置从登录到设备入网装好组件并重启 Home Assistant 后接入流程只有三步进入设置 设备与服务 添加集成搜索Xiaomi Home并进入。按页面提示用OAuth 2.0授权登录小米账号——这是一种第三方授权登录全程不用提交你的账号密码。登录成功后弹出选择家庭与设备对话框勾选要导入的米家家庭该家庭下的设备随即批量出现在 Home Assistant 里。到这里设备已经进门剩下几项配置能让它用得顺更多。进阶配置多账号、局域网控制与 Action 调试在设置 设备与服务 已配置 Xiaomi Home 配置里有三个进阶开关值得了解多账号管理第一个账号配置完成后点添加中枢再走一遍登录即可接入第二个小米账号。局域网控制参数更新 LAN 控制配置让同一局域网内的 IP 设备WiFi 或网线连接走局域网通道官方提示该功能可能引起个别异常建议谨慎开启——完整的米家本地控制还是优先依赖中枢网关见下节。Action 调试模式开启后带参数的设备动作会额外显示为一个文本实体你可以手动填参数向设备发送 Action 指令方便测试控制链路是否通畅。状态怎么同步、指令怎么下发云端与本地两条链路云端链路集成向小米云的 MQTT Broker 订阅设备消息MQTT 可以理解为设备消息的订阅制快递。设备属性变化或事件发生时云端主动推送通知集成无需轮询查询状态同步是实时的整套配置完成时它只全量拉取一次设备属性对云端压力很小。控制方向相反集成通过 MIoT 云端的 HTTP 接口发出指令由云端转发给设备执行。本地链路小米中枢网关内置一个标准 MQTT Broker集成直接经它订阅设备消息控制时集成把指令发布给 Broker再由网关转发到设备。整条设备 → 网关 → 集成的链路在局域网内闭环完成米家本地控制由此实现减少了对云端的依赖。MIoT 协议实体映射说明书怎么变成 HA 实体MIoT-Spec-V2 把产品定义为一个设备Device设备下挂多个服务Service服务里再分属性Property、动作Action、事件Event一共五要素。米家 Home Assistant 集成按下面的规则把它们翻译成 Home Assistant 实体MIoT 类型条件生成的 HA 实体属性可写、字符串格式Text属性可写、布尔格式Switch属性可写、带枚举值列表Select属性可写、带数值范围Number属性只读Sensor事件任意Event 实体事件参数会传入触发事件动作无参数Button动作带参数Notify举个例子风扇的工作模式枚举属性生成 Select 实体童锁布尔属性生成 Switch长按按键事件生成带触发参数的 Event 实体可以直接被自动化订阅。多语言显示8 种语言与本地覆盖设备名、属性名的翻译来自两层云端从 MIoT 云端下载设备厂商配置好的多语言文件本地用multi_lang.json维护自己的多语言词典可以补充或改写厂商翻译。生效优先级是本地配置 云端配置 默认英文集成界面本身提供 8 种语言可选。修改了 specs 目录下的文件后别忘了在集成的配置页执行一次更新实体转换规则改动才会生效。安全账OAuth 登录背后的明文令牌登录走OAuth 2.0Home Assistant 里不会保存你的小米账号密码这是好消息。但受平台限制登录成功后账号下的设备信息、证书、token 等会明文写在 HA 配置文件中。这份文件一旦泄露别人可能冒用你的身份登录。建议妥善保管配置文件定期到米家 APP 的应用授权页检查这条授权发现异常立即撤销。新手最常问的 4 个问题Q1为什么我的蓝牙设备接不进来纯蓝牙、红外和虚拟设备目前不支持。如果确实需要那台设备可以看看同品类的 WiFi 或 ZigBee 版本作为替代。Q2没有中枢网关本地控制能用吗完整的本地控制需要小米中枢网关固件 v3.4.0或内置中枢网关的设备软件 v0.8.0。没有的话所有指令都会走小米云。此外还有局域网控制选项可以部分替代但它只覆盖同局域网的 IP 设备。Q3能同时登多个小米账号吗可以而且不同账号的设备允许放进同一个 Home Assistant 区域统一管理。Q4海外能用吗可以云服务已覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国等地区配置时选择自己的地区即可。代码结构与下一步想深入阅读源码或自定义行为这几个模块是入口模块职责miot_client.py用户会话管理每加一个账号就是一个实例miot_cloud.pyOAuth 登录、云端 HTTP 接口封装miot_device.py设备实体处理属性、事件、动作逻辑miot_spec.py解析 MIoT-Spec-V2miot_lan.py局域网设备发现与控制两个常用自定义点spec_filter.yaml可以过滤掉不想转成实体的设备或功能multi_lang.json用来自定义翻译。日常使用建议让 Home Assistant 与米家设备保持同一局域网用 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），仅供参考 米家设备接入 Home Assistant 完整指南：3 种安装方式与本地控制一次讲清
米家设备接入 Home Assistant 完整指南3 种安装方式与本地控制一次讲清【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_home 是小米官方为 Home Assistant 开发的米家集成组件作用很直接把米家生态里的智能设备批量接入 Home Assistant在同一个面板里完成状态查看、指令下发和自动化编排。这篇小米 HA 插件安装教程面向新手也兼顾进阶——从版本要求、3 种安装方式到登录配置、本地控制、MIoT 协议实体映射规则一次讲清。先说结论它能帮你管好一屋子米家设备品类覆盖广绝大多数米家设备品类都能接入只有纯蓝牙、红外和虚拟设备暂不支持。多账号同时接入多个小米账号可以并存不同账号的设备还能放进同一个 Home Assistant 区域。云 本地混合控制默认走小米云配了小米中枢网关后切换为米家本地控制响应更快、更少依赖云端。实体自动标准化基于 MIoT-Spec-V2 协议把设备功能翻译成 Home Assistant 实体属性、事件、动作各归其位不用手写实体配置。顺便解释一下 MIoT-Spec-V2它相当于小米给每台设备下的标准说明书统一描述设备有哪些功能、状态和动作后文会讲它如何映射成实体。动手前版本要求和适用地区先对上号安装前先确认两个硬指标不满足的话配置流程会卡住检查项要求Home Assistant Core≥ 2024.4.4Operating SystemHA 操作系统镜像≥ 13.0地区方面该集成已部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国等地区海外用户同样可用。由于各地区小米云的数据相互隔离首次配置时记得选择自己所在的地区否则设备列表会是空的不同地区的设备之后也可以汇入同一个区域。3 种安装方式怎么选方式适合人群后续升级方式Git 克隆官方推荐愿意敲几条命令的用户git fetch后切到目标版本标签重跑 install.shHACS习惯用社区商店的用户HACS 内一键更新Samba / FTP 手动复制完全不想碰终端的用户手动覆盖custom_components/xiaomi_home文件夹三条路殊途同归最终都是把组件放到config/custom_components/xiaomi_home下。Git 克隆方式cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config官方更推荐这条路以后想升级到某个版本切到对应的 Git 标签tag再执行一次./install.sh /config就行版本回退也一样方便。HACS 方式在 HACS 里搜索Xiaomi Home进入详情页点击下载即可完成 HACS 安装 ha_xiaomi_home全程不用接触命令行。手动复制方式通过 Samba 或 FTP 把custom_components/xiaomi_home文件夹整体复制到 Home Assistant 的config/custom_components目录重启后生效。首次配置从登录到设备入网装好组件并重启 Home Assistant 后接入流程只有三步进入设置 设备与服务 添加集成搜索Xiaomi Home并进入。按页面提示用OAuth 2.0授权登录小米账号——这是一种第三方授权登录全程不用提交你的账号密码。登录成功后弹出选择家庭与设备对话框勾选要导入的米家家庭该家庭下的设备随即批量出现在 Home Assistant 里。到这里设备已经进门剩下几项配置能让它用得顺更多。进阶配置多账号、局域网控制与 Action 调试在设置 设备与服务 已配置 Xiaomi Home 配置里有三个进阶开关值得了解多账号管理第一个账号配置完成后点添加中枢再走一遍登录即可接入第二个小米账号。局域网控制参数更新 LAN 控制配置让同一局域网内的 IP 设备WiFi 或网线连接走局域网通道官方提示该功能可能引起个别异常建议谨慎开启——完整的米家本地控制还是优先依赖中枢网关见下节。Action 调试模式开启后带参数的设备动作会额外显示为一个文本实体你可以手动填参数向设备发送 Action 指令方便测试控制链路是否通畅。状态怎么同步、指令怎么下发云端与本地两条链路云端链路集成向小米云的 MQTT Broker 订阅设备消息MQTT 可以理解为设备消息的订阅制快递。设备属性变化或事件发生时云端主动推送通知集成无需轮询查询状态同步是实时的整套配置完成时它只全量拉取一次设备属性对云端压力很小。控制方向相反集成通过 MIoT 云端的 HTTP 接口发出指令由云端转发给设备执行。本地链路小米中枢网关内置一个标准 MQTT Broker集成直接经它订阅设备消息控制时集成把指令发布给 Broker再由网关转发到设备。整条设备 → 网关 → 集成的链路在局域网内闭环完成米家本地控制由此实现减少了对云端的依赖。MIoT 协议实体映射说明书怎么变成 HA 实体MIoT-Spec-V2 把产品定义为一个设备Device设备下挂多个服务Service服务里再分属性Property、动作Action、事件Event一共五要素。米家 Home Assistant 集成按下面的规则把它们翻译成 Home Assistant 实体MIoT 类型条件生成的 HA 实体属性可写、字符串格式Text属性可写、布尔格式Switch属性可写、带枚举值列表Select属性可写、带数值范围Number属性只读Sensor事件任意Event 实体事件参数会传入触发事件动作无参数Button动作带参数Notify举个例子风扇的工作模式枚举属性生成 Select 实体童锁布尔属性生成 Switch长按按键事件生成带触发参数的 Event 实体可以直接被自动化订阅。多语言显示8 种语言与本地覆盖设备名、属性名的翻译来自两层云端从 MIoT 云端下载设备厂商配置好的多语言文件本地用multi_lang.json维护自己的多语言词典可以补充或改写厂商翻译。生效优先级是本地配置 云端配置 默认英文集成界面本身提供 8 种语言可选。修改了 specs 目录下的文件后别忘了在集成的配置页执行一次更新实体转换规则改动才会生效。安全账OAuth 登录背后的明文令牌登录走OAuth 2.0Home Assistant 里不会保存你的小米账号密码这是好消息。但受平台限制登录成功后账号下的设备信息、证书、token 等会明文写在 HA 配置文件中。这份文件一旦泄露别人可能冒用你的身份登录。建议妥善保管配置文件定期到米家 APP 的应用授权页检查这条授权发现异常立即撤销。新手最常问的 4 个问题Q1为什么我的蓝牙设备接不进来纯蓝牙、红外和虚拟设备目前不支持。如果确实需要那台设备可以看看同品类的 WiFi 或 ZigBee 版本作为替代。Q2没有中枢网关本地控制能用吗完整的本地控制需要小米中枢网关固件 v3.4.0或内置中枢网关的设备软件 v0.8.0。没有的话所有指令都会走小米云。此外还有局域网控制选项可以部分替代但它只覆盖同局域网的 IP 设备。Q3能同时登多个小米账号吗可以而且不同账号的设备允许放进同一个 Home Assistant 区域统一管理。Q4海外能用吗可以云服务已覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国等地区配置时选择自己的地区即可。代码结构与下一步想深入阅读源码或自定义行为这几个模块是入口模块职责miot_client.py用户会话管理每加一个账号就是一个实例miot_cloud.pyOAuth 登录、云端 HTTP 接口封装miot_device.py设备实体处理属性、事件、动作逻辑miot_spec.py解析 MIoT-Spec-V2miot_lan.py局域网设备发现与控制两个常用自定义点spec_filter.yaml可以过滤掉不想转成实体的设备或功能multi_lang.json用来自定义翻译。日常使用建议让 Home Assistant 与米家设备保持同一局域网用 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），仅供参考