将小米设备接入 Home Assistantha_xiaomi_home 集成上手指南【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home如果你希望把家里的小米智能家居设备灯光、插座、空调、扫地机器人等纳入 Home Assistant 统一管理ha_xiaomi_home是一个由小米官方支持的集成组件。它通过 MIoT 协议把设备解析成 Home Assistant 的实体并提供云端与本地两种控制路径。下面从安装、配置到使用建议带你跑通第一条接入链路。需要接入小米设备的常见场景小米生态里的设备通常分散在各自的小程序或 App 中跨品牌联动和自动化编写并不方便。当你遇到下面这类需求时这套集成比较合适想把不同小米设备的状态集中到 Home Assistant统一做开关、读取传感器数值希望基于设备属性变化或事件触发自动化如人体感应后开灯需要在家外通过 Home Assistant 查看或控制家中设备家里有多个小米账号、不同地区的设备想归到同一个区域里管理。ha_xiaomi_home 覆盖的能力与使用边界该组件按 MIoT-Spec-V2 协议把设备的属性、事件、动作转换成 Home Assistant 实体可写属性映射为 Switch、Select、Number、Text只读属性映射为 Sensor事件映射为 Event 实体。它支持多小米账号登录允许把不同账号、不同地区的设备导入同一区域。需要明确几个边界避免选型时产生误解暂不支持蓝牙设备、红外设备和虚拟设备可用的地区包括中国大陆、欧洲、印度、俄罗斯、新加坡、美国导入时需在配置流程中选择对应地区完整本地控制依赖小米中枢网关固件 3.3.0_0023 及以上或内置中枢功能的设备软件 0.8.9 及以上其中小米中枢网关目前仅在中国大陆可用。从安装到首次设备导入的落地步骤前置条件Home Assistant 版本需满足Core ≥ 2024.4.4、Operating System ≥ 13.0并准备好小米账号。安装组件有三种方式按习惯选择Git 克隆官方推荐便于切换 tag 更新版本在config目录执行git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home进入目录后运行./install.sh /config。HACS 一键安装在 HACS 搜索框输入Xiaomi Home进入详情页下载安装。手动安装将custom_components/xiaomi_home文件夹复制到 Home Assistant 的config/custom_components目录。登录与首次验证安装后重启 Home Assistant进入 设置 设备与服务 添加集成搜索Xiaomi Home并选择 OAuth 登录小米账号。登录成功后会弹出“Select Home and Devices”对话框勾选包含目标设备的家庭完成导入。验证方式在设备页确认目标设备已出现且生成了可操作的实体如灯光的 Switch、传感器的 Sensor。用 Home Assistant 的界面控制一次灯光或插座能立即看到设备响应即代表接入链路正常。云端控制与本地控制的取舍云端控制组件在 MIoT 云端的 MQTT Broker 上订阅设备消息设备属性变化或事件发生时由云端推送控制命令则通过 MIoT 云的 HTTP 接口下发。这种方式无需局域网适合出门在外查看和控制家中设备是大多数用户的默认路径。本地控制本地控制借助小米中枢网关内置的标准 MQTT Broker 完成订阅与发布指令在局域网内直达设备减少了对云端的依赖。它要求网关或内置中枢设备固件/软件达到指定版本且网关仅在中国大陆销售。此外组件还提供了“小米局域网控制”开关但它只能控制与 Home Assistant 同网段的 IP 设备WiFi 或网线接入无法覆盖 BLE Mesh、ZigBee 设备官方并不建议默认开启。多账号与区域完成一个账号的配置后可在集成的配置页继续添加其它小米账号并将不同账号、不同地区的设备加入同一区域便于统一编组与自动化。排障提示与后续入口设备导入后不显示确认账号选择的地区与设备归属一致检查小米 App 中的家庭共享设置必要时重启网关与 Home Assistant 后重新导入。本地控制不生效核对中枢网关固件/软件版本是否达标、网关是否在中国大陆、目标设备是否为 IP 设备存在中枢网关时局域网控制开关可能不会生效。配置安全组件采用 OAuth 2.0 登录不保存账号密码但登录后的用户信息设备信息、证书、令牌等会明文写入配置文件请妥善保管该目录怀疑令牌泄露时可在小米账号管理中取消授权。文档与源码入口中文文档见 doc/README_zh.md变更记录见 CHANGELOG.md配置流程语言包位于 custom_components/xiaomi_home/translations/设备名称多语言字典在custom_components/xiaomi_home/miot/specs/自动化与转换规则可用spec_filter.yaml、multi_lang.json调整改动后需在集成配置页更新实体转换规则组件测试脚本位于 test/可用于验证云端、局域网、MDNS 等模块行为。【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考