小米米家接入 Home Assistant 完整指南从安装到本地控制【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_homeXiaomi Home 集成是小米官方提供的米家集成组件运行在 Home Assistant 中让绝大多数米家设备能在同一面板里查看状态、下发指令。本文面向新手与进阶用户覆盖版本自检、三种安装方式、账号登录、云端与本地控制原理、实体映射规则。小米米家集成能做什么决定要不要引入之前先看它的能力边界品类覆盖广多数米家品类可接入蓝牙、红外、虚拟设备除外多账号并存多个小米账号同时登录设备可混排进同一区域云 本地双链路默认走小米云有中枢网关可切本地实体自动生成按 MIoT-Spec-V2 描述自动生成 Switch、Select、Sensor 等实体这里有个术语要先交代MIoT-Spec-V2。可以把它理解为一份“设备零件清单”——每台米家设备出厂前小米就写好了它有哪些功能、哪些状态可查、哪些指令可发。它的正式定义是小米 IoT 平台制定的设备规范化功能描述协议集成正是靠它把设备翻译成 Home Assistant 实体。行动项动手前先确认主力米家设备不是纯蓝牙或红外产品。安装米家集成前先自检 Home Assistant 版本这一节决定你能不能顺利开工花一分钟对照即可。检查项要求不满足会怎样Home Assistant Core≥ 2024.4.4集成无法正常安装Operating SystemOS 镜像≥ 13.0安装流程走不通小米账号已绑定米家设备登录后拉不到设备列表还有一个容易踩的坑小米云数据按地区隔离服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个地区。首次配置时必须选择自己所在区域否则设备列表是空的不同地区的设备之后可以汇入同一个 Home Assistant 区域。另外中枢网关只在中国大陆销售海外用户只能走云端链路。行动项安装前看一眼 Home Assistant 版本号低于要求先升级。三种安装方式与首次登录配置版本对齐后动线是装组件 → 重启 → 登录 → 选家庭 → 设备批量导入。安装方式对比三条路最终都落在config/custom_components/xiaomi_home方式适合谁后续升级怎么做Git 克隆常用终端的用户官方推荐git fetch后切目标版本 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装完重启 Home Assistant。之后想更新到某个版本git fetch后切换到对应 tag再执行一次./install.sh /config即可。HACS 用户只需在 HACS 里搜索Xiaomi Home进详情页下载。手动用户用 Samba 或 FTP 把custom_components/xiaomi_home文件夹拷到 HA 的config/custom_components下重启生效。首次配置步骤进入设置 设备与服务 添加集成搜索Xiaomi Home继续下一步。按页面提示完成 OAuth 2.0 授权用小米账号登录密码不会写入 Home Assistant。登录成功后弹出“选择家庭与设备”对话框勾选要导入的米家家庭该家庭下设备随即批量出现在 Home Assistant 里。设备已经进门面板和自动化可以开始搭了。行动项登录后核对设备数量与米家 APP 里对一遍。米家设备云端与本地控制链路原理新手只需要记住一句话状态“进来”、指令“出去”走的都是同一对链路。云端链路状态推送指令转发默认情况下集成向小米云的 MQTT Broker 订阅设备消息。设备属性变化或事件发生时云端直接推送集成不用轮询整份属性只在配置完成时全量查询一次对云端压力很小。指令方向相反集成通过云端的 HTTP 接口发出set_properties、action由云端转发给设备执行。本地链路中枢网关局域网闭环小米中枢网关固件 ≥ 3.3.0_0023或内置中枢网关的设备软件 ≥ 0.8.9里带一个标准 MQTT Broker。集成直接向它订阅设备消息控制时把指令发布给 Broker再由网关转发到设备。“设备 → 网关 → 集成”整条链路在局域网内闭环少绕云端响应更快。注意没有中枢网关时所有指令都会经小米云发送本地链路不存在。MIoT-Spec-V2 到实体的映射规则协议把一个设备拆成多个服务每个服务下挂属性、事件、动作集成按下表翻译MIoT 要素条件生成的 HA 实体属性可写、字符串Text属性可写、布尔Switch属性可写、带枚举取值列表Select属性可写、带数值范围Number属性只读Sensor事件任意Event参数传入触发事件动作无参数Button动作带参数Notify举例风扇的“工作模式”是枚举属性生成 Select 下拉“童锁”布尔属性生成 Switch温湿度读数生成 Sensor。灯具的开关布尔属性生成 Switch亮度这种带范围的属性生成 Number。无线开关的“长按”事件生成 Event 实体可直接写进自动化触发条件。行动项发现实体缺失或类型不对时先查该设备的 MIoT-Spec-V2 实例再考虑自定义转换规则。多账号、局域网控制与 Action 调试进阶设置基础接入跑通后集成“配置”页里还有几个开关值得了解。多账号管理第一个账号配完后点“添加中枢”再登录即可接入第二个小米账号。不同账号的设备可放进同一个区域统一管理。局域网控制通过“更新局域网控制配置”开启。只覆盖同局域网内的 IP 设备WiFi、网线连接够不到 BLE Mesh、ZigBee 设备。官方提示该功能可能引起个别异常不建议轻易开启局域网内已有中枢网关时该功能也不会生效。Action 调试模式开启后带参数的设备动作会额外生成一个 Text 实体可手动填参数向设备发 Action 指令方便验证控制链路是否通畅。自定义多语言词典用 multi_lang.json 补充或改写云端下载的设备翻译优先级为 本地 云端 默认英文。集成界面本身支持简中、英文等 13 种语言。实体转换过滤用 spec_filter.yaml 按服务号、属性号排除指定实例避免无用实体占满实体列表。更新设备列表米家 APP 里新增了设备到配置对话框选择从米家 APP 更新设备列表即可同步进来。行动项改动 specs 目录下任何文件后到配置页执行一次“更新实体转换规则”才会生效。米家集成的令牌保存与隐私风险这一节说清楚登录凭据到底存在哪、泄漏后怎么办。好消息登录走OAuth 2.0Home Assistant 里不保存你的小米账号密码。⚠️ 风险也真实存在受平台限制登录成功后设备信息、证书、token 等会明文写入 HA 配置文件。这份文件一旦泄露别人可能冒用你的身份登录。两条建议配置文件权限收严备份和同步走可信渠道别丢进公开仓库。定期到米家 APP 检查应用授权我的 → 小米账号 → 应用授权看到“Xiaomi Home (Home Assistant Integration)”出现异常就立即撤销。注意拿到你配置文件的人就等于拿到了你在小米云的身份备份文件要按同一标准保管。蓝牙设备、地区支持与本地控制的常见问题把新手最容易卡住的问题集中回答一遍。蓝牙设备为什么接不进来纯蓝牙、红外和虚拟设备目前不支持。确实需要的话换同品类的 WiFi 或 ZigBee 版本。没有中枢网关本地控制能用吗不能。完整本地控制需要中枢网关固件 ≥ 3.3.0_0023或内置中枢网关的设备软件 ≥ 0.8.9否则所有指令走小米云。局域网控制可部分替代但只覆盖同局域网的 IP 设备。能同时登多个小米账号吗可以不同账号的设备还能放进同一个 Home Assistant 区域统一管理。海外用户能用吗可以。云服务覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个地区首次配置时选对区域即可。米家集成源码结构与日常使用建议想读源码或自定义行为从这几个入口进文件职责miot_client.py用户会话每加一个账号一个实例miot_cloud.pyOAuth 登录、云端 HTTP 接口封装miot_device.py设备实体属性、事件、动作处理miot_spec.py解析 MIoT-Spec-V2miot_lan.py局域网设备发现与控制日常使用四点建议让 HA 与米家设备保持同一局域网用区域功能给设备分组把设备事件接进自动化升级后留意实体转换规则是否有变化。延伸资源官方中文文档 doc/README_zh.md、版本更新日志 CHANGELOG.md、安装脚本 install.sh。行动项把更新日志加入书签每次升级后花两分钟过一遍变更内容。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
小米米家接入 Home Assistant 完整指南：从安装到本地控制
小米米家接入 Home Assistant 完整指南从安装到本地控制【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_homeha_xiaomi_homeXiaomi Home 集成是小米官方提供的米家集成组件运行在 Home Assistant 中让绝大多数米家设备能在同一面板里查看状态、下发指令。本文面向新手与进阶用户覆盖版本自检、三种安装方式、账号登录、云端与本地控制原理、实体映射规则。小米米家集成能做什么决定要不要引入之前先看它的能力边界品类覆盖广多数米家品类可接入蓝牙、红外、虚拟设备除外多账号并存多个小米账号同时登录设备可混排进同一区域云 本地双链路默认走小米云有中枢网关可切本地实体自动生成按 MIoT-Spec-V2 描述自动生成 Switch、Select、Sensor 等实体这里有个术语要先交代MIoT-Spec-V2。可以把它理解为一份“设备零件清单”——每台米家设备出厂前小米就写好了它有哪些功能、哪些状态可查、哪些指令可发。它的正式定义是小米 IoT 平台制定的设备规范化功能描述协议集成正是靠它把设备翻译成 Home Assistant 实体。行动项动手前先确认主力米家设备不是纯蓝牙或红外产品。安装米家集成前先自检 Home Assistant 版本这一节决定你能不能顺利开工花一分钟对照即可。检查项要求不满足会怎样Home Assistant Core≥ 2024.4.4集成无法正常安装Operating SystemOS 镜像≥ 13.0安装流程走不通小米账号已绑定米家设备登录后拉不到设备列表还有一个容易踩的坑小米云数据按地区隔离服务部署在中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个地区。首次配置时必须选择自己所在区域否则设备列表是空的不同地区的设备之后可以汇入同一个 Home Assistant 区域。另外中枢网关只在中国大陆销售海外用户只能走云端链路。行动项安装前看一眼 Home Assistant 版本号低于要求先升级。三种安装方式与首次登录配置版本对齐后动线是装组件 → 重启 → 登录 → 选家庭 → 设备批量导入。安装方式对比三条路最终都落在config/custom_components/xiaomi_home方式适合谁后续升级怎么做Git 克隆常用终端的用户官方推荐git fetch后切目标版本 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装完重启 Home Assistant。之后想更新到某个版本git fetch后切换到对应 tag再执行一次./install.sh /config即可。HACS 用户只需在 HACS 里搜索Xiaomi Home进详情页下载。手动用户用 Samba 或 FTP 把custom_components/xiaomi_home文件夹拷到 HA 的config/custom_components下重启生效。首次配置步骤进入设置 设备与服务 添加集成搜索Xiaomi Home继续下一步。按页面提示完成 OAuth 2.0 授权用小米账号登录密码不会写入 Home Assistant。登录成功后弹出“选择家庭与设备”对话框勾选要导入的米家家庭该家庭下设备随即批量出现在 Home Assistant 里。设备已经进门面板和自动化可以开始搭了。行动项登录后核对设备数量与米家 APP 里对一遍。米家设备云端与本地控制链路原理新手只需要记住一句话状态“进来”、指令“出去”走的都是同一对链路。云端链路状态推送指令转发默认情况下集成向小米云的 MQTT Broker 订阅设备消息。设备属性变化或事件发生时云端直接推送集成不用轮询整份属性只在配置完成时全量查询一次对云端压力很小。指令方向相反集成通过云端的 HTTP 接口发出set_properties、action由云端转发给设备执行。本地链路中枢网关局域网闭环小米中枢网关固件 ≥ 3.3.0_0023或内置中枢网关的设备软件 ≥ 0.8.9里带一个标准 MQTT Broker。集成直接向它订阅设备消息控制时把指令发布给 Broker再由网关转发到设备。“设备 → 网关 → 集成”整条链路在局域网内闭环少绕云端响应更快。注意没有中枢网关时所有指令都会经小米云发送本地链路不存在。MIoT-Spec-V2 到实体的映射规则协议把一个设备拆成多个服务每个服务下挂属性、事件、动作集成按下表翻译MIoT 要素条件生成的 HA 实体属性可写、字符串Text属性可写、布尔Switch属性可写、带枚举取值列表Select属性可写、带数值范围Number属性只读Sensor事件任意Event参数传入触发事件动作无参数Button动作带参数Notify举例风扇的“工作模式”是枚举属性生成 Select 下拉“童锁”布尔属性生成 Switch温湿度读数生成 Sensor。灯具的开关布尔属性生成 Switch亮度这种带范围的属性生成 Number。无线开关的“长按”事件生成 Event 实体可直接写进自动化触发条件。行动项发现实体缺失或类型不对时先查该设备的 MIoT-Spec-V2 实例再考虑自定义转换规则。多账号、局域网控制与 Action 调试进阶设置基础接入跑通后集成“配置”页里还有几个开关值得了解。多账号管理第一个账号配完后点“添加中枢”再登录即可接入第二个小米账号。不同账号的设备可放进同一个区域统一管理。局域网控制通过“更新局域网控制配置”开启。只覆盖同局域网内的 IP 设备WiFi、网线连接够不到 BLE Mesh、ZigBee 设备。官方提示该功能可能引起个别异常不建议轻易开启局域网内已有中枢网关时该功能也不会生效。Action 调试模式开启后带参数的设备动作会额外生成一个 Text 实体可手动填参数向设备发 Action 指令方便验证控制链路是否通畅。自定义多语言词典用 multi_lang.json 补充或改写云端下载的设备翻译优先级为 本地 云端 默认英文。集成界面本身支持简中、英文等 13 种语言。实体转换过滤用 spec_filter.yaml 按服务号、属性号排除指定实例避免无用实体占满实体列表。更新设备列表米家 APP 里新增了设备到配置对话框选择从米家 APP 更新设备列表即可同步进来。行动项改动 specs 目录下任何文件后到配置页执行一次“更新实体转换规则”才会生效。米家集成的令牌保存与隐私风险这一节说清楚登录凭据到底存在哪、泄漏后怎么办。好消息登录走OAuth 2.0Home Assistant 里不保存你的小米账号密码。⚠️ 风险也真实存在受平台限制登录成功后设备信息、证书、token 等会明文写入 HA 配置文件。这份文件一旦泄露别人可能冒用你的身份登录。两条建议配置文件权限收严备份和同步走可信渠道别丢进公开仓库。定期到米家 APP 检查应用授权我的 → 小米账号 → 应用授权看到“Xiaomi Home (Home Assistant Integration)”出现异常就立即撤销。注意拿到你配置文件的人就等于拿到了你在小米云的身份备份文件要按同一标准保管。蓝牙设备、地区支持与本地控制的常见问题把新手最容易卡住的问题集中回答一遍。蓝牙设备为什么接不进来纯蓝牙、红外和虚拟设备目前不支持。确实需要的话换同品类的 WiFi 或 ZigBee 版本。没有中枢网关本地控制能用吗不能。完整本地控制需要中枢网关固件 ≥ 3.3.0_0023或内置中枢网关的设备软件 ≥ 0.8.9否则所有指令走小米云。局域网控制可部分替代但只覆盖同局域网的 IP 设备。能同时登多个小米账号吗可以不同账号的设备还能放进同一个 Home Assistant 区域统一管理。海外用户能用吗可以。云服务覆盖中国大陆、欧洲、印度、俄罗斯、新加坡、美国六个地区首次配置时选对区域即可。米家集成源码结构与日常使用建议想读源码或自定义行为从这几个入口进文件职责miot_client.py用户会话每加一个账号一个实例miot_cloud.pyOAuth 登录、云端 HTTP 接口封装miot_device.py设备实体属性、事件、动作处理miot_spec.py解析 MIoT-Spec-V2miot_lan.py局域网设备发现与控制日常使用四点建议让 HA 与米家设备保持同一局域网用区域功能给设备分组把设备事件接进自动化升级后留意实体转换规则是否有变化。延伸资源官方中文文档 doc/README_zh.md、版本更新日志 CHANGELOG.md、安装脚本 install.sh。行动项把更新日志加入书签每次升级后花两分钟过一遍变更内容。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
