尧图网页设计 
米家设备接入 Home Assistantha_xiaomi_home 三种安装方式与本地控制实操【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_homeXiaomi Home是小米官方的 Home Assistant 集成登录小米账号后把米家设备批量导入为可在 HA 里控制和自动化的实体。本文覆盖安装路径选择、登录配置、本地控制与进阶开关写给想装起来、装完能用的人。能力速览先给结论一句话结论它能把绝大多数米家设备管起来装完一小时左右可以全部跑通。品类广主流米家品类基本都支持纯蓝牙、红外和虚拟设备除外。多账号多个小米账号可同时在线设备还能放进同一个 HA 区域。控制双链路默认走小米云有小家中枢网关后可切到全本地链路。实体自动生成按 MIoT-Spec-V2 描述自动生成 Text、Switch、Select 等实体不用手写实体配置。13 种语言集成界面与设备名翻译支持简体中文、英文等 13 种语言本地可扩充。工作原理状态和指令的两条链路先搞懂集成和设备之间怎么对话再选安装方式。云端链路集成向小米云的 MQTT Broker 订阅设备消息。MQTT 你可以理解成设备消息的订阅制报纸属性变化或事件发生时设备推一条上行消息Broker 转给集成HA 立刻知道全程不轮询整个配置过程只全量查询一次属性。指令方向反过来HA 通过云端 HTTP 接口发命令云端转发给设备执行。本地链路小家中枢网关内置一个标准 MQTT Broker集成直接向它订阅发指令时集成把命令发布到 Broker由网关转发给设备。设备 → 网关 → HA整段在局域网内闭环不依赖外网。设备的能力描述来自 MIoT-Spec-V2 协议一个设备挂多个服务服务里再分属性、事件、方法。集成按固定规则把它们转成 HA 实体MIoT 概念条件生成的 HA 实体属性可写字符串格式Text属性可写布尔格式Switch属性可写带枚举取值列表Select属性可写带数值范围Number属性只读Sensor事件任意Event参数传给触发事件方法无输入参数Button方法带输入参数Notify比如无线开关的长按事件会生成 Event 实体按键被长按时触发自动化事件参数里带着是哪一个键。硬性条件动手前先核对检查项要求不满足会卡在哪Home Assistant Core≥ 2024.4.4组件装上了但版本校验不过集成无法启动Operating System 镜像≥ 13.0官方硬性门槛低了安装与配置流程不保证可用HACS≥ 1.34.0HACS 商店里装不了该集成地区云服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个地区首次配置时选的地区和设备实际所在区域不一致设备列表为空最后一项最容易踩各地区小米云数据互相隔离首次配置务必选自己所在区域选错只能重配。路径选择三种安装方式对照方式适合人群后续升级Git 克隆官方推荐习惯命令行的用户git fetch后切到目标 tag重跑安装脚本HACS全程想点界面的用户HACS 内一键更新Samba / FTP 手动复制完全不碰终端的用户手动覆盖custom_components/xiaomi_home文件夹三条路终点相同组件落在config/custom_components/xiaomi_home。推荐 Git 克隆理由在升级那栏——版本切换和回退都是改一行 tag 的事。Git 克隆进入 HA 的 config 目录克隆仓库并执行官方安装脚本输出 Xiaomi Home installation is completed 即成功cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config以后想固定到某个版本切 tag 再跑一次脚本即可例如固定到 v0.5.0cd config/ha_xiaomi_home git fetch git checkout v0.5.0 ./install.sh /config脚本无报错输出即切换成功重启 HA 后实体按该版本规则生成。HACS在 HACS 搜索框输入Xiaomi Home进入详情页点 DOWNLOAD稍后回到集成列表就能搜到它。Samba / FTP 手动复制把仓库里的custom_components/xiaomi_home文件夹整体拷到 HA 的config/custom_components下重启生效。每次更新都要手动覆盖一次最省事也最费手适合完全不碰终端的人。️ 上手流程从登录到设备入网重启 Home Assistant进集成搜索页能看到 Xiaomi Home说明组件加载成功。设置 设备与服务 添加集成搜索Xiaomi Home下一步点登录链接。用 OAuth 2.0 授权登录小米账号——走小米的第三方授权页HA 里不输入你的密码。登录成功后弹出选择家庭与设备勾选目标米家家庭该家庭下设备批量导入。打开任意一个导入的实体比如灯开关一次HA 里的状态和米家 App 里同步变化即链路通了。之后的所有操作都在Xiaomi Home 配置页完成。进阶配置四个高频开关多账号第一个账号配完后设置 设备与服务 已配置 Xiaomi Home 添加中枢再走一遍登录。两个账号的设备可以放进同一个区域统一管理。局域网控制配置页执行更新局域网控制配置后同一局域网内的 IP 设备WiFi 或网线连接可走局域网通道。官方明确该功能可能引起异常、不建议使用且局域网内已有中枢网关时它不会生效。建议有中枢网关就别开确实没中枢又嫌云端慢再试。Action 调试模式开启后带输入参数的设备方法会额外生成一个文本实体手动填参数就能向设备发 Action 指令适合验证某个 Notify 实体的控制链路。更新实体转换规则改过custom_components/xiaomi_home/miot/specs/下任何文件如spec_filter.yaml、multi_lang.json后必须到配置页执行更新实体转换规则才生效。其中multi_lang.json用于本地补充或改写设备名翻译优先级高于云端多语言文件。❓ 高频问题Q有些设备导入不了为什么结论在前纯蓝牙、红外和虚拟设备目前不支持。如果你的型号属于这几类集成内没有解法只能换同品类的 WiFi 或 ZigBee 版本。Q没有中枢网关还算本地控制吗不算。完整本地控制要求中枢网关固件 ≥ 3.3.0_0023或内置中枢的设备软件 ≥ 0.8.9没有中枢所有指令都走小米云。上面的局域网控制开关只覆盖同局域网 IP 设备蓝牙 Mesh、ZigBee 设备它管不到。Q能同时登多个小米账号吗能。多账号并存且不同账号的设备可以添加进同一个 HA 区域。Q海外能用吗能。云服务覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个地区配置时选自己所在区域即可之后不同地区的设备也能汇入同一区域。⚠️ 提醒与自保别把配置文件弄丢或外泄。OAuth 登录后设备信息、证书、token 会明文存在 HA 配置文件里文件一旦泄露他人可冒用你的身份登录备份要管好。定期核对应用授权。怀疑 token 泄露时米家 App → 我的 → 用户名进入小米账号页 → 应用授权 → Xiaomi Home → 取消授权。中枢网关仅中国大陆可用。其他地区想走本地控制只能依赖内置中枢网关功能的设备。局域网控制默认建议不开。官方 README 已提示可能引起异常开启后若设备行为诡异先关掉它再排查。源码入口与日常建议模块职责miot_client.py用户会话管理每加一个账号一个实例miot_cloud.pyOAuth 登录与云端 HTTP 接口封装miot_device.py设备实体属性、事件、方法处理逻辑miot_spec.py解析 MIoT-Spec-V2 并做实体转换miot_lan.py局域网设备发现与控制miot_mips.py消息总线订阅与发布日常使用建议保持 HA 与米家设备在同一局域网用区域功能给设备分组把设备事件接进自动化每次升级前先看 CHANGELOG.md 确认本版本改了什么。官方中文文档见 doc/README_zh.md安装、配置、映射规则和目录结构都在这一处。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 米家设备接入 Home Assistant：ha_xiaomi_home 三种安装方式与本地控制实操
米家设备接入 Home Assistantha_xiaomi_home 三种安装方式与本地控制实操【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_homeXiaomi Home是小米官方的 Home Assistant 集成登录小米账号后把米家设备批量导入为可在 HA 里控制和自动化的实体。本文覆盖安装路径选择、登录配置、本地控制与进阶开关写给想装起来、装完能用的人。能力速览先给结论一句话结论它能把绝大多数米家设备管起来装完一小时左右可以全部跑通。品类广主流米家品类基本都支持纯蓝牙、红外和虚拟设备除外。多账号多个小米账号可同时在线设备还能放进同一个 HA 区域。控制双链路默认走小米云有小家中枢网关后可切到全本地链路。实体自动生成按 MIoT-Spec-V2 描述自动生成 Text、Switch、Select 等实体不用手写实体配置。13 种语言集成界面与设备名翻译支持简体中文、英文等 13 种语言本地可扩充。工作原理状态和指令的两条链路先搞懂集成和设备之间怎么对话再选安装方式。云端链路集成向小米云的 MQTT Broker 订阅设备消息。MQTT 你可以理解成设备消息的订阅制报纸属性变化或事件发生时设备推一条上行消息Broker 转给集成HA 立刻知道全程不轮询整个配置过程只全量查询一次属性。指令方向反过来HA 通过云端 HTTP 接口发命令云端转发给设备执行。本地链路小家中枢网关内置一个标准 MQTT Broker集成直接向它订阅发指令时集成把命令发布到 Broker由网关转发给设备。设备 → 网关 → HA整段在局域网内闭环不依赖外网。设备的能力描述来自 MIoT-Spec-V2 协议一个设备挂多个服务服务里再分属性、事件、方法。集成按固定规则把它们转成 HA 实体MIoT 概念条件生成的 HA 实体属性可写字符串格式Text属性可写布尔格式Switch属性可写带枚举取值列表Select属性可写带数值范围Number属性只读Sensor事件任意Event参数传给触发事件方法无输入参数Button方法带输入参数Notify比如无线开关的长按事件会生成 Event 实体按键被长按时触发自动化事件参数里带着是哪一个键。硬性条件动手前先核对检查项要求不满足会卡在哪Home Assistant Core≥ 2024.4.4组件装上了但版本校验不过集成无法启动Operating System 镜像≥ 13.0官方硬性门槛低了安装与配置流程不保证可用HACS≥ 1.34.0HACS 商店里装不了该集成地区云服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个地区首次配置时选的地区和设备实际所在区域不一致设备列表为空最后一项最容易踩各地区小米云数据互相隔离首次配置务必选自己所在区域选错只能重配。路径选择三种安装方式对照方式适合人群后续升级Git 克隆官方推荐习惯命令行的用户git fetch后切到目标 tag重跑安装脚本HACS全程想点界面的用户HACS 内一键更新Samba / FTP 手动复制完全不碰终端的用户手动覆盖custom_components/xiaomi_home文件夹三条路终点相同组件落在config/custom_components/xiaomi_home。推荐 Git 克隆理由在升级那栏——版本切换和回退都是改一行 tag 的事。Git 克隆进入 HA 的 config 目录克隆仓库并执行官方安装脚本输出 Xiaomi Home installation is completed 即成功cd config git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /config以后想固定到某个版本切 tag 再跑一次脚本即可例如固定到 v0.5.0cd config/ha_xiaomi_home git fetch git checkout v0.5.0 ./install.sh /config脚本无报错输出即切换成功重启 HA 后实体按该版本规则生成。HACS在 HACS 搜索框输入Xiaomi Home进入详情页点 DOWNLOAD稍后回到集成列表就能搜到它。Samba / FTP 手动复制把仓库里的custom_components/xiaomi_home文件夹整体拷到 HA 的config/custom_components下重启生效。每次更新都要手动覆盖一次最省事也最费手适合完全不碰终端的人。️ 上手流程从登录到设备入网重启 Home Assistant进集成搜索页能看到 Xiaomi Home说明组件加载成功。设置 设备与服务 添加集成搜索Xiaomi Home下一步点登录链接。用 OAuth 2.0 授权登录小米账号——走小米的第三方授权页HA 里不输入你的密码。登录成功后弹出选择家庭与设备勾选目标米家家庭该家庭下设备批量导入。打开任意一个导入的实体比如灯开关一次HA 里的状态和米家 App 里同步变化即链路通了。之后的所有操作都在Xiaomi Home 配置页完成。进阶配置四个高频开关多账号第一个账号配完后设置 设备与服务 已配置 Xiaomi Home 添加中枢再走一遍登录。两个账号的设备可以放进同一个区域统一管理。局域网控制配置页执行更新局域网控制配置后同一局域网内的 IP 设备WiFi 或网线连接可走局域网通道。官方明确该功能可能引起异常、不建议使用且局域网内已有中枢网关时它不会生效。建议有中枢网关就别开确实没中枢又嫌云端慢再试。Action 调试模式开启后带输入参数的设备方法会额外生成一个文本实体手动填参数就能向设备发 Action 指令适合验证某个 Notify 实体的控制链路。更新实体转换规则改过custom_components/xiaomi_home/miot/specs/下任何文件如spec_filter.yaml、multi_lang.json后必须到配置页执行更新实体转换规则才生效。其中multi_lang.json用于本地补充或改写设备名翻译优先级高于云端多语言文件。❓ 高频问题Q有些设备导入不了为什么结论在前纯蓝牙、红外和虚拟设备目前不支持。如果你的型号属于这几类集成内没有解法只能换同品类的 WiFi 或 ZigBee 版本。Q没有中枢网关还算本地控制吗不算。完整本地控制要求中枢网关固件 ≥ 3.3.0_0023或内置中枢的设备软件 ≥ 0.8.9没有中枢所有指令都走小米云。上面的局域网控制开关只覆盖同局域网 IP 设备蓝牙 Mesh、ZigBee 设备它管不到。Q能同时登多个小米账号吗能。多账号并存且不同账号的设备可以添加进同一个 HA 区域。Q海外能用吗能。云服务覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国 6 个地区配置时选自己所在区域即可之后不同地区的设备也能汇入同一区域。⚠️ 提醒与自保别把配置文件弄丢或外泄。OAuth 登录后设备信息、证书、token 会明文存在 HA 配置文件里文件一旦泄露他人可冒用你的身份登录备份要管好。定期核对应用授权。怀疑 token 泄露时米家 App → 我的 → 用户名进入小米账号页 → 应用授权 → Xiaomi Home → 取消授权。中枢网关仅中国大陆可用。其他地区想走本地控制只能依赖内置中枢网关功能的设备。局域网控制默认建议不开。官方 README 已提示可能引起异常开启后若设备行为诡异先关掉它再排查。源码入口与日常建议模块职责miot_client.py用户会话管理每加一个账号一个实例miot_cloud.pyOAuth 登录与云端 HTTP 接口封装miot_device.py设备实体属性、事件、方法处理逻辑miot_spec.py解析 MIoT-Spec-V2 并做实体转换miot_lan.py局域网设备发现与控制miot_mips.py消息总线订阅与发布日常使用建议保持 HA 与米家设备在同一局域网用区域功能给设备分组把设备事件接进自动化每次升级前先看 CHANGELOG.md 确认本版本改了什么。官方中文文档见 doc/README_zh.md安装、配置、映射规则和目录结构都在这一处。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考