小米米家 (Xiaomi Home) Home Assistant 官方集成使用教程

前置条件：米家中枢网关+ha服务器

本文应该是比较简单直接的告诉你，如何把米家的设备通过米家官方插件xiaomi home把米家设备对接到home-assistant。

整体设备架构图：

整体设备架构图

本教程将指导您如何安装、配置和使用由小米官方支持的 Home Assistant 米家集成，让您能够方便地在 Home Assistant 中管理和控制您的小米IoT智能设备。

为了简化安装过程，我推荐使用由 Smart Home Fans 团队出品的“智趣盒子”。该盒子已为您预装好 Home Assistant (HAOS) 操作系统，并集成了包括小米米家官方插件在内的多种实用工具。您几乎无需进行复杂的配置，只需插上电源，按照配套的说明进行简单设置即可开始使用，大大降低了入门门槛。

智趣盒子购买的连接：

https://item.taobao.com/item.htm?id=934944608705

目前官方搞活动，他们是硬件工厂原价直出，168元可以pk目前平台上258-358的性能。同时提供免费的技术指引。

当然有技术基础的，也可以自己搜教程自己安装。

简介

小米米家集成（Xiaomi Home Integration）是由小米官方支持的 Home Assistant 组件，旨在将您的米家智能设备无缝接入 Home Assistant 平台，实现统一管理和自动化控制。

开始之前：环境要求

在安装前，请确保您的 Home Assistant 环境满足以下最低版本要求：

• Home Assistant Core: geq 2024.4.4

• Home Assistant Operating System: geq 13.0

安装方法

我采用的智趣盒子，已经预装了这个插件，如果你是新用户，您可以根据自己的偏好选择以下任一方法进行安装：

方法 1：HACS (Home Assistant Community Store) - 推荐

这是最简单、最推荐的安装方式，可以方便地进行后续更新。

1. 一键安装:

   • 点击下方徽章，直接在您的 Home Assistant 实例中打开集成页面进行安装：

2. 手动搜索:

   • 进入 Home Assistant 的 HACS 商店。

   • 在搜索框中输入 "Xiaomi Home"。

   • 在搜索结果中点击 "Xiaomi Home"，进入详情页后点击 "DOWNLOAD"。

方法 2：Git Clone

此方法适合熟悉命令行的进阶用户，便于切换到特定的发行版本。

1. 进入 Home Assistant 的配置目录：

   Bash

   cd config

2. 克隆仓库：

   Bash

   git clone https://github.com/XiaoMi/ha_xiaomi_home.git

3. 进入仓库目录并执行安装脚本：

   Bash

   cd ha_xiaomi_home ./install.sh /config

更新到指定版本 (例如 v0.3.2):

Bash

cd config/ha_xiaomi_home git fetch git checkout v0.3.2 ./install.sh /config

方法 3：手动安装 (通过 Samba / FTPS)

1. 从代码库下载 custom_components/xiaomi_home 整个文件夹。

2. 将下载的 xiaomi_home 文件夹复制到您 Home Assistant 配置目录下的 config/custom_components 文件夹内。

安装完成后，请务必重启 Home Assistant 服务以使集成生效。

配置流程

安装并重启后，请按照以下步骤配置米家集成：

1. 添加集成：

   • 导航至 设置 > 设备与服务 > 添加集成。

   • 搜索 "Xiaomi Home" 并点击进入。

2. 风险告知与基础配置：

   • 风险告知：首次配置时，您会看到一个风险告知页面。请仔细阅读并勾选“我已悉知以上风险并自愿承担...”后方可继续。

   • 基础配置：

     • 登录地区：选择您米家 App 账号所在的服务器地区（如：中国大陆、Europe 等）。

     • 语言：选择集成内实体和设备名称显示的语言。

     • OAuth2 认证跳转地址：通常保持默认的 http://homeassistant.local:8123 即可。重要提示：您的操作设备（如电脑、手机）必须能通过此地址访问到 Home Assistant。

     • 集成网络配置：首次配置时建议勾选此项，以检测网络环境是否满足集成运行的条件。

3. 授权登录：

   • 点击页面上的链接，将跳转至小米账户登录页面。

   • 输入您的小米账号和密码完成登录授权。成功后，页面会提示您关闭并返回 Home Assistant。

4. 选择家庭与设备：

   • 授权成功后，配置流程会自动进入下一步。

   • 导入设备的家庭：勾选您希望在 Home Assistant 中管理的米家“家庭”。

   • 房间名同步模式：决定设备在 Home Assistant 中的“区域”如何根据米家 App 中的“房间”或“家庭”命名。

   • 点击“下一步”即可完成基本配置。

核心功能与概念

控制方式：云端与本地

米家集成支持两种设备控制方式，您可以在配置时或后续的“选项”中进行选择。

• 云端控制 (Cloud)：所有控制指令通过小米云端服务器进行中转。这是默认和最基本的控制方式。

• 本地控制 (Local)：

  • 中枢网关模式：如果您的局域网内有小米中枢网关（固件版本需达标），集成会自动优先通过它在本地收发指令，速度更快且不依赖外网。此功能目前仅在中国大陆地区可用。

  • 局域网控制 (LAN Control)：对于路由器、部分灯具等IP设备，集成可以尝试通过局域网直接控制，无需中枢网关。此功能可能会引起一些异常，需谨慎使用。

实体映射关系

集成会将米家设备的各种功能（属性、事件、方法）按照一定的规则转换为 Home Assistant 中的实体。

• 通用转换规则：

  • 可读写的布尔值 (bool) 属性 -> Switch 实体。

  • 只读的属性 -> Sensor 实体。

  • 带有取值范围 (value-range) 的可读写数字属性 -> Number 实体。

  • 带有取值列表 (value-list) 的可读写属性 -> Select 实体。

  • 无输入参数的方法 (action) -> Button 实体。

  • 有输入参数的方法 -> Notify 实体，您可以通过调用服务并传入参数来执行。

• 特殊转换规则：对于灯、风扇、扫地机、窗帘等标准设备，集成会根据其服务类型直接创建对应的 Light, Fan, Vacuum, Cover 等实体，提供更完整的原生体验。

高级用法与配置修改

您随时可以修改已添加的集成配置。

• 路径：设置 > 设备与服务 > Xiaomi Home，点击“配置”。

• 可修改选项：

  • 更新设备列表：当您在米家 App 中新增或删除了设备后，通过此选项可以同步设备列表到 Home Assistant。

  • 更新实体转换规则：如果您修改了集成目录下的 spec_filter.yaml 或 multi_lang.json 等文件，需要执行此项来让修改生效。

  • Action 调试模式：开启后，对于带参数的方法会额外生成一个 Text 实体，方便您输入参数直接进行调试。

  • 更新局域网控制配置：用于配置和启用局域网直连功能。

安全与隐私

• 米家集成采用 OAuth 2.0 登录，不会在 Home Assistant 中保存您的小米账号密码。

• 警告：登录成功后获取的用户信息、设备信息和访问令牌（Token）会以明文形式保存在 Home Assistant 的配置文件中。请务必妥善保管您的 Home Assistant 配置文件，防止泄露。

• 如果您怀疑令牌泄露，可以登录米家 App，在 “我的” > 点击头像进入小米账号管理 > “应用授权” 中找到 “Xiaomi Home (Home Assistant Integration)” 并取消授权。

常见问题 (FAQ)

• 是否支持所有小米设备?

  不支持。目前主要支持大部分通过Wi-Fi、Zigbee（需搭配网关）接入的设备。蓝牙、红外遥控和虚拟设备等暂不支持。

• 是否支持多账号登录?

  是。您可以在一个已配置好的米家集成实例中，通过“添加中枢”的入口继续添加其他小米账号。

• 支持哪些地区?

  支持中国大陆、欧洲、印度、俄罗斯、新加坡和美国六个服务器区域。您可以在添加集成时选择对应的地区。

许可证

此集成及其使用的云端接口由小米官方提供，版权归小米公司所有。许可证授权您仅可为非商业目的在 Home Assistant 中使用此集成，禁止用于开发其他任何形式的应用程序或Web服务。

希望这份教程能帮助您顺利地在 Home Assistant 中使用小米米家设备！