企业官网建设流程全解析

小米米家设备接入 Home Assistant 完整指南：Xiaomi Home 集成安装、配置与双通道控制教程

【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home

ha_xiaomi_home（Xiaomi Home 集成）是小米官方支持的 Home Assistant 组件，用于把小米米家设备接入 Home Assistant，让灯、插座、温湿度计、空调伴侣等设备进入同一个自动化平台统一调度。这篇指南覆盖安装、小米账号授权、云端与本地两种控制通道的配置方法，以及常见故障的排查思路，适合第一次做小米米家设备接入 Home Assistant 的新手。

接入小米米家设备后，Home Assistant 里能跑起来哪些自动化场景

先看看装好之后能做什么。傍晚你推开门回家，门磁传感器上报状态变化，Home Assistant 自动点亮玄关灯，并把空调调到你预设的舒适温度；你说一句"看电影"，客厅主灯熄灭、氛围灯切成暖色、音响开机，这些动作全部由自动化规则触发，不需要碰米家 App；夜里起身，人体传感器检测到移动，路径灯亮起，几分钟后自动熄灭；早上出门，离家模式关闭所有灯光，空调切到节能。

这些场景的共性是：每个小米设备在 Home Assistant 里都变成了标准实体，可以直接写进自动化、仪表板和脚本，而不用再和米家 App 抢控制权。

为什么小米米家设备不能直接接入 Home Assistant

问题出在生态边界上。米家设备的数据默认只在米家 App 和小米云之间流转，第三方系统想读取状态、下发指令，早期只能靠抓包、逆向协议写插件。这类手段不稳：小米云接口或设备固件一更新，插件就可能全线失效，维护成本全压在用户自己身上。

Xiaomi Home 集成换了个思路：不逆向，直接对接小米官方开放的 MIoT-Spec-V2 协议。MIoT-Spec-V2 可以理解为小米给每类设备规定的一份"能力说明书"，写明设备有哪些属性（比如温度值）、能执行哪些方法（比如开关机）、会发出哪些事件（比如门被打开）。设备按这份说明书自报家门，集成负责把说明书翻译成 Home Assistant 能识别的实体。于是接入动作收敛成"一次授权、自动发现"，不需要为每台设备手写对接逻辑。

Xiaomi Home 集成安装步骤：环境检查、仓库克隆与小米账号登录

安装前检查版本要求

先确认你的 Home Assistant 版本满足最低要求，版本过低会缺少组件依赖的接口，后续排查很麻烦：

• Core ≥ 2024.4.4
• Operating System ≥ 13.0

同时保证系统能正常访问小米云服务，登录授权环节要用到。

方式一：Git 克隆安装（官方推荐）

在 HA 的配置目录下执行以下命令，把组件复制到custom_components目录：

git clone https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home cd ha_xiaomi_home ./install.sh /path/to/config

⚠️ 两个关键点：install.sh只接受一个参数，即 HA 的config目录路径，填错会直接报错退出；执行成功后输出提示"Please restart Home Assistant"，必须重启 HA，组件才会出现在集成列表里。官方推荐这种方式，因为日后想切到某个固定版本，只需git checkout对应 Tag 后重跑一次脚本即可。

方式二：HACS 一键安装

如果已装 HACS，在商店搜索框输入Xiaomi Home，进入详情页点 DOWNLOAD，完成后同样重启 HA。

登录小米账号并选择服务地区

重启后打开 HA 的"设置 → 设备与服务"，点击"添加集成"，搜索 "Xiaomi Home"，按页面提示登录小米账号，然后选择账号所属区域。可选区域共 6 个：中国大陆、欧洲、印度、俄罗斯、新加坡、美国。不同区域的小米云数据相互隔离，选错区域会导致搜不到设备。

登录成功后会弹出"选择家庭与设备"对话框，选择要导入的米家家庭，该家庭内所有设备会批量导入，不需要逐台添加。设备分散在多个账号或多个区域的，也可以通过"添加中枢"继续登录其他小米账号，把不同来源的设备汇到同一个 HA 实例里。

验证设备导入是否成功

回到"设置 → 设备与服务"，Xiaomi Home 条目下应能看到刚导入的设备，每台设备展开后有一组实体（开关、传感器、选择器等）。随手点一个灯的开关，设备状态立刻变化且实体同步刷新，说明导入成功。

小米米家集成云端与本地控制通道原理及实体自动转换机制

云端控制：经小米云完成状态同步与指令下发

云控模式下，集成的两端分别对接小米云的 MQTT Broker 和 HTTP API：设备属性变化、上下线事件由 MQTT Broker 主动推送给集成，集成无需轮询；你在 HA 里发出的控制指令则通过 HTTP API 发到云端，再转发给设备。整个链路对家庭网络环境不挑剔，人在外地也能远程操作家里的设备。

本地控制：小米中枢网关承接局域网内通信

本地模式把通信终点从小米云换成小米中枢网关。网关内置标准 MQTT Broker，设备状态消息和控制指令都在局域网内走一圈，不经过任何外部服务器，响应几乎是瞬时的，传感器联动类自动化尤其受益。

启用本地模式有版本门槛：独立的小米中枢网关需要固件 3.3.0_0023 及以上；内置中枢网关功能的设备需要软件 0.8.9 及以上，且中枢网关目前仅在中国大陆发售。此外，集成还提供"局域网控制"作为降级方案，只能控制通过 WiFi 或网线连接路由器的 IP 设备，管不了 BLE Mesh、ZigBee 设备，官方明确建议谨慎使用；启用局域网控制时，相关模型参数存放在 custom_components/xiaomi_home/miot/lan/profile_models.yaml，按文件内注释修改。

云端控制与本地控制通道对比

MIoT-Spec-V2 实体自动转换：导入即用的实体生成规则

设备导入后最省事的一环，是集成内置的实体转换引擎。它读取每台设备的 MIoT-Spec-V2 说明书，按属性访问方式自动生成对应实体：

• 可写的布尔属性 → Switch（开关）
• 可写的带取值列表属性 → Select（下拉选择）
• 可写的数值范围属性 → Number（数值输入）
• 只读属性 → Sensor（传感器）
• 只读文本属性 → Text
• 设备事件 → Event
• 设备方法 → Button（无参数）或 Notify（带参数）

换句话说，导入完成的那一刻实体就已经能用了，你不需要手写任何映射。转换规则的实现在 custom_components/xiaomi_home/miot/specs/specv2entity.py，配套的过滤和改写规则放在 custom_components/xiaomi_home/miot/specs/ 目录下（如spec_filter.yaml可按设备型号过滤不需要的属性），改动后需在集成"配置 → 更新实体转换规则"中刷新一次。

支持的设备范围、服务地区与界面语言

蓝牙设备、红外设备和虚拟设备暂不支持。界面语言方面，custom_components/xiaomi_home/translations/ 目录维护了简体中文、繁体中文、英文、日文、德文等 13 种语言的翻译，跟随 HA 的语言设置自动切换。

小米米家集成常见故障排查：状态不同步、本地控制失效怎么办

组件后续的版本演进可以看 更新日志，想给翻译或转换规则提改进意见可参考 中文贡献指南。随着设备越接越多，你会发现真正的工作量从"接入"转移到了"编排"——那正是 Home Assistant 最擅长的部分。

【免费下载链接】ha_xiaomi_homeXiaomi Home Integration for Home Assistant项目地址: https://gitcode.com/GitHub_Trending/ha/ha_xiaomi_home