2025.3.4
首页 ▸ Integrations ▸

Matter

Matter 集成允许您控制本地 Wi-Fi 或 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 网络上的 Matter 设备。

为了与 Matter 设备进行通信，Home Assistant 集成运行自己的 “Matter 控制器” 作为附加组件。这个 Matter 服务器附加组件作为单独的进程运行控制器软件，连接您的 Matter 网络（在技术术语中称为 Fabric）和 Home Assistant。Home Assistant 的 Matter 集成通过 WebSocket 连接到此服务器。

介绍 - 什么是 Matter？

Matter 是一种新的智能家居连接标准，用于家居自动化产品和物联网（IoT）设备，请参阅它的 维基百科文章。

Matter 的初始版本 1.0 于 2022 年 10 月发布。Matter 仍在智能家居市场中的采用过程中。由于其跨所有生态系统的互操作性承诺，它获得了很多关注。谷歌、苹果和亚马逊等大型科技公司联手在 CSA（Connectivity Standards Alliance）的框架下开发这个新的智能家居连接标准。已经活跃于家庭自动化市场的最大科技公司已宣布他们正在或将要开发支持 Matter 的产品，并加入开发工作。

Matter 产品在本地运行，并始终允许本地控制，设备控制不需要任何互联网连接或云服务。从技术角度来看，您可以在不连接到特定厂商云服务的情况下使用支持 Matter 的设备与 Home Assistant 配合使用。然而，一些厂商可能需要您在启用某些产品的 Matter 支持之前先设置一个账号（尤其是对于商业制造商自有品牌的网关/桥接器/集线器/控制器）。

与其他常见的基于无线电的 IoT 协议（如 Zigbee、Z-Wave 和蓝牙）不同，Matter 标准规范本身不包含其专有无线电协议或网络传输协议，而是一个在现有网络基础设施上以应用层形式运行的服务控制协议，所有 Matter 设备都通过您现有的 局域网（例如 Wi-Fi 和以太网） 或 线程（低功耗无线个人区域网络） 进行标准的基于 IP 的（IPv6）通信，具体取决于设备类型。

Home Assistant 是 Matter 生态系统中的所谓 “控制器”，意味着它可以控制基于 Matter 的设备。其他 Matter 控制器的例子有 Google Nest 产品、Apple HomePod 音箱、Samsung SmartThings Station 和一些较新的 Amazon Echo 设备。

线程与 Matter 有什么关系？

ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 是一种低功耗无线网状网络技术。很像 Zigbee，但主要区别在于它是 可寻址的 IP，使其成为 Matter 的合适传输协议选项。

下图说明了 MatterMatter 是一个开源标准，定义了如何在 Wi-Fi 或 Thread 网络上控制智能家居设备。 [Learn more]、ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 和边界路由器的关系。线程边界路由器将线程网络中设备的流量转发到网络外部的设备。

image

图片来自 Thread Group 的 线程智能家居事实表。

有关线程的更多信息，请参考 线程文档。

线程设备不一定支持 Matter

市场上的许多设备使用 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 进行无线通信，并将 Matter 作为控制协议。但这并非保证。一些基于线程的设备支持 Apple HomeKit 或其他厂商特定的通信协议。还有少数情况需要您申请（测试版）固件更新以启用 Matter 作为通信协议。

看到设备上有线程标志并不要假设它支持 Matter。请始终查找 Matter 标志（在 Wi-Fi/以太网设备或 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 上）或制造商确认设备支持 Matter 的其他说明。

启动期间使用蓝牙

大多数（如果不是全部）符合 Matter 的设备都有一块蓝牙芯片以简化 commissioning在 Matter 设备的上下文中，调试是将设备添加到 Matter 控制器的过程。它相当于在 Zigbee 或 Z-Wave 中配对设备。 [Learn more]。蓝牙不用于控制，而是在拆箱后或重置后将设备配对。Home Assistant 控制器使用 Home Assistant Companion 应用进行 commissioning在 Matter 设备的上下文中，调试是将设备添加到 Matter 控制器的过程。它相当于在 Zigbee 或 Z-Wave 中配对设备。 [Learn more]。在启动期间，您需要将手机靠近设备。然后控制器通过蓝牙将您的网络凭据发送到设备。一旦完成，设备通过其原生接口进行通信：Wi-Fi 或线程。

Note

尽管您的 Home Assistant 服务器可能在其上有蓝牙适配器供控制器使用以 commission在 Matter 设备的上下文中，调试是将设备添加到 Matter 控制器的过程。它相当于在 Zigbee 或 Z-Wave 中配对设备。 [Learn more] 设备，但 Home Assistant 不会利用该适配器。这主要是为了防止与内置蓝牙集成产生问题，同时因为将移动设备带到 Matter 设备附近比将设备带到服务器更为方便。

多法abric：加入多个控制器

Matter 的一个重要特性是所谓的 多法abric 功能：您可以将同一设备加入多个控制器。例如，同时将其添加到 Google Home、Apple Home 和 Home Assistant。标准描述每个设备应至少能够同时支持 5 个不同的 fabric。

对于 Home Assistant 提供本地集成（带本地 API）的设备，Matter 可能不是最佳选择。Matter 作为一个通用标准，可能没有特定于产品协议的细微功能。一个好的例子是 Philips Hue：通过 Matter 的通信仅提供基本的灯光控制，而官方的 Hue 集成 提供了所有独特的 Hue 特性，如（动态）场景、娱乐模式等。

支持的安装类型

建议在 Home Assistant OS 上运行 Matter 附加组件。这是当前唯一支持的选项。其他安装类型不受支持，风险自负。

如果您在容器中运行 Home Assistant，可以运行 Matter 服务器 的 Docker 镜像。有关您主机设置的要求和说明，请参见该 GitHub 页面。

不支持在 Home Assistant Core 安装上运行 Matter。

将 Matter 设备添加到 Home Assistant

每个 Matter 网络称为 fabric。每个控制 Matter 设备的家居自动化控制器都有自己的 “fabric”。您可以将设备直接添加到 Home Assistant 实例的 fabric，或从另一个 fabric（例如来自 Google 或 Apple）共享到 Home Assistant 的 fabric。接下来我们将探讨所有这些选项。

注意：以下部分提到第三方线程边界路由器，例如 Nest Hub（第二代）或 HomePod Mini。这并不意味着您必须将设备添加到这些生态系统中。Home Assistant 只使用它们来访问线程无线网络。Home Assistant Matter 控制器与您的 Matter 设备之间的通信是加密的。线程边界路由器只是传递数据，无法读取其内容。

前提条件

在尝试将 Matter 设备添加到 Home Assistant 之前，请确保准备好所有这些组件。

准备 Home Assistant

  • 确保已安装最新版本的 Home Assistant 安装。
  • 在 Home Assistant 中，确保安装了 Matter 集成。
    • 进入 设置 > 设备和服务。
    • 添加 Matter 集成。
    • 当提示选择连接方法时：
      • 如果您在常规设置中运行 Home Assistant OS：选择 提交。
        • 这将安装官方 Matter 服务器附加组件。
        • 请注意，官方 Matter 服务器附加组件不支持 32 位平台。
      • 如果您已经在另一个附加组件中运行 Matter 服务器，或者在自定义容器中：
        • 取消选中该复选框，然后选择 提交。
        • 在下一步中，提供您 Matter 服务器的 URL。

检查设备上的标志

  • 在设备包装上，检查 Matter 标志以及 Wi-Fi 或 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 标志。
  • 检查设备上是否有二维码或数字设置代码。
    • 如果您重置设备，您将需要二维码 或 数字设置代码来 commission在 Matter 设备的上下文中，调试是将设备添加到 Matter 控制器的过程。它相当于在 Zigbee 或 Z-Wave 中配对设备。 [Learn more] 该设备！没有这些信息，将无法进行启动。
    • 如果二维码或数字设置代码仅在附带文档中，则最好拍下二维码和/或数字设置代码的备份，最好连同设备一起参考，并将代码存放在安全的地方。

准备 Android 或 iPhone

  • 准备好 Android 或 iPhone，并启用蓝牙。有关为什么需要蓝牙的信息，请参阅 启动期间使用蓝牙 部分：
    • Android：
      • 至少需为 Android 8.1。推荐使用 12 版本或更高版本。
      • 安装来自 Play 商店的 Home Assistant Companion 应用的最新版本（完整版本）。
      • 如果您使用 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more]：确保在您的家庭网络中有一个线程边界路由器设备（Nest Hub（第二代）或 Nest Wi-Fi Pro 或安装 OpenThread 边界路由器附加组件的 Home Assistant）。
        • 如果您使用 OpenThread（对于 Connect ZBT-1/SkyConnect）作为边界路由器，请确保按照 线程文档 中的步骤进行操作。
    • iPhone
      • iOS 版本需为 16 或更高版本。
      • 安装最新版本的 Home Assistant Companion 应用。
      • 如果您使用 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more]：确保在您的家庭网络中有一个线程边界路由器设备（HomePod Mini 或 V2、Apple TV 4K 或安装 OpenThread 边界路由器附加组件的 Home Assistant）。
        • 如果您使用 OpenThread（对于 Connect ZBT-1/SkyConnect）作为边界路由器，请确保按照 线程文档 中的步骤进行操作。
  • 确保手机在边界路由器和您的设备的近距离内。
  • 如果您要添加的是基于 Wi-Fi 的 Matter 设备：Matter 设备通常在 Wi-Fi 上使用 2.4 GHz 频率。因此，请确保您的手机在您希望操作设备的相同 2.4 GHz 网络中。

通过 iOS Companion 应用添加新设备

本指南描述了如何添加新设备。将利用您的手机的蓝牙连接来添加设备。

  1. 在手机上打开 Home Assistant 应用。
  2. 进入 设置 > 设备和服务。
  3. 在 设备 选项卡上，选择 添加设备 按钮，然后选择 添加 Matter 设备。
  4. 在对话框中选择 不，它是新的。
  5. 使用手机相机扫描 Matter 设备的二维码，或选择 更多选项… 手动输入委员会代码。
  6. 选择 添加到 Home Assistant。
    • 这将开始启动过程，可能需要几分钟。
  7. 如果您添加的是测试板或测试设备，您可能会收到有关 未认证配件 的提示。在此对话框中，选择 仍然添加。
  8. 如果提示，输入自定义 配件名称。
    • 您可以在这里输入任何您想要的内容。
    • 这是 iOS 的内部参考，不会在 Home Assistant 中可见。
    • 输入名称后，选择 继续。
  9. 一旦过程完成，选择 完成。
    • 您将被重定向到 Home Assistant 中的设备页面。它已准备好使用。

通过 Android Companion 应用添加新设备

本指南描述了如何添加新设备。将利用您的手机的蓝牙连接来添加设备。

  1. 在手机上打开 Home Assistant 应用。
  2. 通过插入电源或添加电池为设备供电。大多数设备现在会进入配对模式。
    • 对于某些设备，您需要启用配对模式（就像处理 Z-Wave 或 Zigbee 设备一样）。
    • 有关如何将设备设置为配对模式的说明通常可以在设备文档中找到。
  3. 对于某些设备，此时，您的手机会显示一个弹出窗口，提示您 扫描二维码。
    • 扫描二维码。
    • 当提示选择应用时，请确保选择 Home Assistant。
    • 完成后，选择 完成，然后选择 添加设备。
  4. 如果您没有看到弹出窗口，请转到 设置 > 设备和服务。
    • 在 设备 选项卡上，选择 添加设备 按钮，然后选择 添加 Matter 设备。
    • 在对话框中选择 不，它是新的。
    • 使用手机相机扫描 Matter 设备的二维码，或选择 没有二维码设置 手动输入委员会代码。
      • 这将开始启动过程，可能需要几分钟。
    • 如果您正在添加测试板（例如运行示例应用的 ESP32），并且启动失败，您可能需要在 Google 开发者控制台采取一些操作，请查阅您测试设备的任何说明。
    • 一旦过程完成，选择 完成。
  5. 要查看设备详细信息，请转到 设置 > 设备和服务 并选择 Matter 集成。
  6. 默认情况下，设备会获得一个工厂指定的名称。要重命名，首先在设备页面上选择铅笔 进行编辑并重命名设备。 image
  7. 您的设备现在可以使用。

演示如何将新 Matter 设备添加到 Home Assistant 的屏幕录像。 演示如何将新 Matter 设备添加到 Home Assistant 的屏幕录像。

故障排除安装

如果您在尝试使用 Android 手机的 Home Assistant Companion 应用添加 Matter 设备时遇到问题，请检查这些步骤。

症状

尝试添加 Matter 设备时，出现错误提示 Matter 目前不可用。

解决办法

这可能意味着 Home Assistant Companion 应用需要的所有必要 Matter 模块尚未下载。请尝试以下步骤：

  1. 等待最多 24 小时，以便 Google Play 服务下载必要的 Matter 模块。
  2. 确保满足 前提条件 中列出的要求。这包括满足最低系统要求：
    • Android：
      • 最低版本为 8.1。推荐版本为 12 或更高。
        • 在使用旧版 Android 的人中，报告了更多问题。
      • 使用常规 Google 账号的 Android 设置。无替代的 Android 版本。
      • 确保 Google Play 服务全部是最新的。
    • iPhone：
      • iOS 版本需为 16 或更高。
  3. Home Assistant Companion 应用：
    • 确保您安装的是（完整）版本，并从 Play 商店下载。
    • 确保它是最新版本。
    • 如果您刚刚安装或更新了 Home Assistant Companion 应用：
      • 等待。
      • 可能需要一段时间才能在后台安装所需的组件。
      • 在 1 小时后重试，确保安装完成。
  4. 验证您的设备是否满足支持 Matter 的所有要求：
    • 在您的 Android 设备上，转到 设置 > Google > 设备和共享。
      • 这里应该有一个 Matter 设备 的条目。
  5. 重新安装 Home Assistant Companion 应用。
  6. 尝试（重新）安装 Google Home 应用。从技术上讲，这不是必需的，但可能会触发 Matter 模块的另一个安装尝试。
  7. 请参考 Google 的 故障排除指南。

从其他平台与 Home Assistant 共享设备

如果您的 Matter 设备已添加到 Apple Home 或 Google Home，并且您希望同时从 Apple 或 Google Home 和 Home Assistant 控制它，请使用以下方法。

前提条件

  • 安装最新版本的 Home Assistant Companion 应用。
  • 分别将 Matter 设备与 Apple Home 或 Google Home 集成。
  • 在 Home Assistant 中，确保安装了 Matter 集成。
    • 转到 设置 > 设备和服务。
    • 添加 Matter 集成。
    • 当提示选择连接方法时：
      • 如果您在常规设置中运行 Home Assistant OS：选择 提交。
        • 这将安装官方 Matter 服务器附加组件。
      • 如果您在自定义容器中运行 Matter 服务器（不推荐）：
        • 取消选中复选框，然后选择 提交。
        • 在下一步中，提供您 Matter 服务器的 URL。

从其他 Matter 控制器（如 Apple 或 Google Home）共享设备

要允许 Home Assistant 控制已添加到其他 Matter 控制器（如 Google Home）的 Matter 设备，请按照以下步骤操作：

  1. 打开手机上的 Home Assistant 应用。
  2. 转到 设置 > 设备和服务。
  3. 在 设备 选项卡上，选择 添加设备 按钮，然后选择 添加 Matter 设备。
  4. 在对话框中选择 是的，它已经在使用中，然后选择它已经连接到哪个控制器，例如 Google Home。
  5. 按照对话框中的指示操作。
    • 故障排除：如果 Home Assistant 无法添加设备，请检查是否安装了 Matter 集成以及 Companion 应用的最新版本。
  6. 一旦设备已添加到 Home Assistant，您将看到通知 您的设备已添加。
    • 处理完成后，您将被重定向到 Home Assistant 中的设备页面。
    • 现在，您可以在 Home Assistant 内部以及在 Google Home 中控制设备。

演示如何从 Apple Home 共享 Matter 设备的屏幕录像。 演示如何从 Apple Home 共享 Matter 设备的屏幕录像。

使用 Matter 桥

对于某些生态系统，您可以通过 Matter 桥 将一些非 Matter 设备添加到 Home Assistant。Matter 桥的示例包括 SwitchBot Hub 2、Aqara Hub M2、Ikea Dirigera 或 Philips Hue Bridge。使用桥可以让您继续通过其原生应用控制这些设备，同时在 Home Assistant 中也可用。例如，Aquara Hub 使用基于云的集成。通过 Matter 桥接到 Home Assistant（而不是使用其基于云的集成），您可以让其使用本地通信。

作为 Matter 控制器，Home Assistant 仅支持对 Matter 设备的 控制。Home Assistant 本身不是桥，并且无法将 Home Assistant 中的现有设备转变为 Matter 兼容设备。

如何将 Matter 桥添加到 Home Assistant

将桥添加到 Home Assistant 的方式取决于设备。请查看该设备的文档以获取具体步骤。例如，就SwitchBot Hub 2而言，您需要在应用内启用 Matter 配对模式。然后会给您一个配对代码，并告诉您将实际设备设置为配对模式。然后，您可以将该桥接设备作为 Matter 设备添加到 Home Assistant。不能保证该生态系统中的所有设备都可以在 Home Assistant 中使用。例如，SwitchBot Hub 2 V1.5 允许您通过 Matter 使用窗帘、锁和百叶窗，但不支持灯光。

在何时不使用桥

在某些情况下，通过 Matter 将设备桥接到 Home Assistant 可能不会给您带来好处。例如，Philips Hue 桥支持 Matter。但 Matter 只支持有限的功能集。Philips Hue 的原生 Home Assistant 集成提供了各种各样的功能，也是在本地运行的。通过 Matter 桥接将 Philips Hue 设备添加到 Home Assistant 并没有任何好处，相反，您将失去一些功能。

在平台之间共享设备

如果您已将 Matter 设备添加到 Home Assistant，并希望在其他平台（例如 Google Home 或 Apple Home）中将其可用，请按照以下步骤操作。

  1. 转到 设置 > 设备和服务，在 Matter 集成卡片上选择 设备。
  2. 从设备列表中选择要共享的设备。
  3. 选择 共享设备，然后在对话框中再次选择 共享设备。
    • 不需要按设备上的硬件按钮以将其设置为配对模式。
  4. 要将设备加入到其他平台，在他们的应用中，扫描二维码或输入共享代码。
  5. 按照他们的应用中的指示进行操作。一旦过程完成，您可以在 Home Assistant 中看到设备被共享：
    • 在 共享设备 按钮旁边，选择三点 菜单，然后选择 管理 fabrics。
    • 在那里列出的新平台应为您所共享的平台。
    • 例如，如果您与 Google Home 共享，将列出 Google LLC。 image

从 Matter 控制器中移除设备

如果您想从特定 Matter 控制器中移除设备，请按照以下步骤操作。

  1. 转到 设置 > 设备和服务，在 Matter 集成卡片上选择 设备。
  2. 从设备列表中选择要从控制器中移除的设备。
  3. 在 设备信息 部分，在 共享设备 旁边选择三点菜单。然后，选择 管理 fabrics。
  4. 从列表中移除感兴趣的控制器。
    • 如果您想要移除 Apple Home，请同时移除 Apple 密钥链条目。 image
  5. 如果您想从 Home Assistant 本身移除设备，请选择三点菜单然后选择 删除。

关于 Matter 设备信息

设备信息部分提供设备的一些诊断信息。

  1. 要查看设备详细信息，请转到 设置 > 设备和服务 并在 Matter 集成卡片上选择 设备。
  2. 从设备列表中选择要查看的设备。

Matter 设备信息

此部分提供有关某些类别的更多信息：

网络类型：显示设备所属的网络类型。例如，线程或 Wi-Fi。

设备类型：有 4 种设备类型：

  • 最终设备：始终保持其无线电开启的最终设备。通常这些设备不是电池供电的。
  • 睡眠最终设备：非路由最终设备。通常处于休眠状态，偶尔唤醒以检查消息。通常是电池供电的。
  • 路由最终设备：始终保持其无线电开启并可以为其他路由和非路由最终设备路由流量的最终设备。
  • 桥接

网络名称：设备启动时加入的网络名称。

IP 地址：通常显示一个以上的 IPv6 地址：链路本地、唯一本地和全局单播。在某些情况下，设备也支持 IPv4。在这种情况下，这里也会列出一个 IPv4 地址。

Matter OTA 设备更新

Matter 协议支持 OTA（无线）软件更新。但是，OTA 软件更新是 Matter 设备的可选功能，因此并非所有 Matter 设备都实现此功能。Home Assistant 为每个支持 Matter 更新的 Matter 设备创建一个更新实体。

CSA 运营一个分布式合规账本（DCL），提供固件更新的元数据。默认情况下，Matter 更新实体每 12 小时检查一次 DCL 是否有更新。如果您想强制检查更新，请使用 homeassistant.update_entity 操作，将更新实体作为目标。目前，Eve 和 Nanoleaf 正在使用 DCL 提供更新。预计未来将有越来越多的固件更新通过 DCL 提供。

Matter 设备 OTA 更新消息 Matter 设备的 OTA 更新通知

Note

Home Assistant 的 Matter 更新目前不适用于在带有（任何）Apple 边界路由器的线程网络上的线程设备。通常您会看到 “目标节点未处理更新文件” 的错误。Apple 边界路由器不转发必要的 mDNS 数据包，这使 Home Assistant 端无法发现更新提供程序。Apple Home 生态系统可能会提供来自他们的更新作为替代（例如，针对 Eve 设备）。

在按钮按下时自动化

您有一个将按钮按压作为输入的设备（例如 Tuo 智能按钮、Inovelli 的 VTM31SN 调光器或 Innovation Matters 的 Matter 按钮模块），现在希望基于该按钮按下触发自动化。要了解如何创建由按钮按下触发的自动化，请参考此 教程。

使用 ESP32 开发板尝试 Matter

您尚未拥有任何支持 Matter 的硬件，但您希望试一下，或许创建自己的 DIY Matter 设备？我们为您 准备了一页，您可以轻松地向受支持的 ESP32 开发板刷入 Matter 固件。我们推荐使用运行 Lighting 应用的 M5 Stamp C3 设备。

注意：对于 Android 用户：您需要按照页面底部的说明将测试设备添加到 Google 开发者控制台，否则 commissioning在 Matter 设备的上下文中，调试是将设备添加到 Matter 控制器的过程。它相当于在 Zigbee 或 Z-Wave 中配对设备。 [Learn more] 将失败。iOS 用户不会遇到此问题，但在 commissioning在 Matter 设备的上下文中，调试是将设备添加到 Matter 控制器的过程。它相当于在 Zigbee 或 Z-Wave 中配对设备。 [Learn more] 期间会收到提示询问是否信任开发设备。

  1. 确保您使用 Google Chrome 或 Microsoft Edge 浏览器。
  2. 打开 https://nabucasa.github.io/matter-example-apps/
  3. 使用 USB 电缆连接 ESP32 设备。
  4. 选择您想要设置的示例旁边的单选按钮，以 M5 Stamp 为例，点击 M5STAMP C3 的 Lighting 应用。
  5. 选择 连接。
  6. 在弹出对话框中，选择正确的串行设备。这通常将是类似 “cu-usbserial” 的东西。
  7. 点击 安装 Matter Lighting 应用示例，并让其安装固件在设备上。这将耗时几分钟。
  8. 一旦设备刷入了 Matter 固件，请再次连接到设备，但这次选择 日志和控制台。
  9. 您将看到一个控制台界面，其中实时记录事件。这是一个交互式 shell，您可以在其中输入命令。要查看所有命令的列表，请输入 matter help 并按 Enter。
  10. 要添加设备，我们需要二维码。在控制台中，输入 matter onboardingcodes ble 并将 URL 复制/粘贴到浏览器中。
  11. 使用二维码，利用上面的建议在手机上添加设备，例如使用 Home Assistant Companion 应用。

故障排除

一般建议

  • 在 Home Assistant 中使用基于线程的 Matter 设备需要 Home Assistant OS 版本 10 及以上。如果不使用 Home Assistant OS，则风险自负。我们确实提供了一些关于如何将 Matter 服务器作为 Docker 容器运行的 文档。文档包括主机和网络要求的描述。

  • 要使用 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 设备，您需要一个 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 网络，其中至少有一个线程边界路由器在您的 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 设备附近。苹果用户需要 Apple TV 4K 或 HomePod Mini，而 Google 用户需要 Nest Hub（第二代）。使用 Home Assistant 中的线程集成来诊断您的 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 网络。

  • 从简单开始，从那里开始，保持您的网络简单，例如添加 ESP32 测试设备。一旦它工作，就继续下一个步骤或更多设备。

  • 意识到您是早期采用者，无论是在硬件还是在软件（控制器）方面，因此您可能会遇到兼容性问题或仍然缺失的功能。如发现任何问题，请报告并帮助他人，若您发现了替代方案或测试了设备。

  • 确保 IPv6（多播）流量可以自由传输到您的 Home Assistant 主机。没有要求拥有启用 IPv6 的互联网连接或 DHCPv6 服务器。然而，必须在 Home Assistant 上启用 IPv6。转到 设置 > 系统 > 网络，确保 IPv6 设置为 自动 或 静态，具体取决于您的网络设置。如果不确定，请使用 自动。

  • 有关网络配置的详细信息，请参阅 Matter 服务器库的 README。

我看不到按钮 通过 Companion 应用进行配对

通过 Companion 应用进行配对 按钮仅存在于 Home Assistant Companion 应用中。在浏览器中不可用。

解决办法

如果您在 Companion 应用中看不到该按钮：

  1. 确保满足 前提条件 中列出的要求。

  2. 这包括满足最低系统要求：

    • Android：
      • 最低版本为 8.1。推荐版本为 12 或更高。
        • 在使用旧版 Android 的人中，报告了更多问题。
        • 使用常规 Google 账号的 Android 设置。无替代 Android 版本。
        • 确保 Google Play 服务全部是最新的。
    • iPhone：
      • iOS 版本需为 16 或更高。

尝试通过 Android 进行配对时，出现错误 “Matter 不可用”

请参考 故障排除安装 下的步骤。

安卓：停留在 “检查网络连接”

症状

您正在尝试使用 Android 手机 commission在 Matter 设备的上下文中，调试是将设备添加到 Matter 控制器的过程。它相当于在 Zigbee 或 Z-Wave 中配对设备。 [Learn more] Matter 设备。在该过程中，您看到 “检查网络连接” 消息并且永远没有进展。

解决办法

  1. 确保满足 前提条件 中列出的要求。

  2. 这包括满足 Android 的最低系统要求：

    • 最低版本为 8.1。推荐版本为 12 或更高。
      • 在使用旧版 Android 的人中，报告了更多问题。
      • 使用常规 Google 账号的 Android 设置。无替代 Android 版本。
      • 确保 Google Play 服务全部是最新的。

  3. 如果您正在添加一个基于 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 的 Matter 设备，请确保手机在边界路由器和您的设备的近距离内。

  4. 如果您正在添加一个基于 Wi-Fi 的 Matter 设备：

    • Matter 设备通常在 Wi-Fi 上使用 2.4 GHz 频率。
    • 确保您的手机在您希望操作设备的相同 2.4 GHz 网络中。

错误 “该设备需要边界路由器”

症状

在尝试通过 Home Assistant Companion 应用添加 Matter 设备时，您出现错误 “该设备需要边界路由器”。

原因

要添加基于 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 无线协议的 Matter 设备，您需要在设备附近有一个 Thread border routerThread 边界路由器在本地网络和 Thread 网络之间转发数据包。这使得 Thread 网络中的智能家居设备能够与本地网络中的 IPv6 设备通信。Thread 边界路由器通过 Wi-Fi 或以太网连接到您的网络，并使用其射频（RF）无线电与 Thread 网状网络通信。在 Matter 的情况下，转发的数据是加密的。Thread 边界路由器的示例包括 Nest Hub（第 2 代）、HomePod mini 和 Home Assistant Connect ZBT-1 以及 OpenThread Border Router 插件。 [Learn more]，并且您的手机需要知道您（新建的）线程网络的凭据。

解决办法

设置一个 Thread border routerThread 边界路由器在本地网络和 Thread 网络之间转发数据包。这使得 Thread 网络中的智能家居设备能够与本地网络中的 IPv6 设备通信。Thread 边界路由器通过 Wi-Fi 或以太网连接到您的网络，并使用其射频（RF）无线电与 Thread 网状网络通信。在 Matter 的情况下，转发的数据是加密的。Thread 边界路由器的示例包括 Nest Hub（第 2 代）、HomePod mini 和 Home Assistant Connect ZBT-1 以及 OpenThread Border Router 插件。 [Learn more]，并将凭据从 Home Assistant 同步到您的 Android 设备：

  1. 按照 将 Home Assistant 变成线程边界路由器 的步骤操作。
  2. 确保按照步骤 3 中所述同步线程凭据。

错误 “目标节点未处理更新文件”

症状

您尝试通过 Home Assistant 更新一个 Matter over Thread 设备，并看到错误 “目标节点未处理更新文件”。

原因

通过 Home Assistant 对 Matter 设备的 OTA 更新不支持 Apple Thread border routerThread 边界路由器在本地网络和 Thread 网络之间转发数据包。这使得 Thread 网络中的智能家居设备能够与本地网络中的 IPv6 设备通信。Thread 边界路由器通过 Wi-Fi 或以太网连接到您的网络，并使用其射频（RF）无线电与 Thread 网状网络通信。在 Matter 的情况下，转发的数据是加密的。Thread 边界路由器的示例包括 Nest Hub（第 2 代）、HomePod mini 和 Home Assistant Connect ZBT-1 以及 OpenThread Border Router 插件。 [Learn more]。

解决办法

  • 如果您只有 Apple 的 Thread border routerThread 边界路由器在本地网络和 Thread 网络之间转发数据包。这使得 Thread 网络中的智能家居设备能够与本地网络中的 IPv6 设备通信。Thread 边界路由器通过 Wi-Fi 或以太网连接到您的网络，并使用其射频（RF）无线电与 Thread 网状网络通信。在 Matter 的情况下，转发的数据是加密的。Thread 边界路由器的示例包括 Nest Hub（第 2 代）、HomePod mini 和 Home Assistant Connect ZBT-1 以及 OpenThread Border Router 插件。 [Learn more]，则无法通过 Home Assistant 更新设备。

  • 如果您有 Apple 和其他 Thread border routersThread 边界路由器在本地网络和 Thread 网络之间转发数据包。这使得 Thread 网络中的智能家居设备能够与本地网络中的 IPv6 设备通信。Thread 边界路由器通过 Wi-Fi 或以太网连接到您的网络，并使用其射频（RF）无线电与 Thread 网状网络通信。在 Matter 的情况下，转发的数据是加密的。Thread 边界路由器的示例包括 Nest Hub（第 2 代）、HomePod mini 和 Home Assistant Connect ZBT-1 以及 OpenThread Border Router 插件。 [Learn more] 的组合，例如 Home Assistant OpenThread 边界路由器，请按照以下步骤操作：

    1. 关闭所有 Apple 的 Thread border routersThread 边界路由器在本地网络和 Thread 网络之间转发数据包。这使得 Thread 网络中的智能家居设备能够与本地网络中的 IPv6 设备通信。Thread 边界路由器通过 Wi-Fi 或以太网连接到您的网络，并使用其射频（RF）无线电与 Thread 网状网络通信。在 Matter 的情况下，转发的数据是加密的。Thread 边界路由器的示例包括 Nest Hub（第 2 代）、HomePod mini 和 Home Assistant Connect ZBT-1 以及 OpenThread Border Router 插件。 [Learn more]。
    2. 等待至少 30 分钟。
    3. 再次尝试通过 Home Assistant 更新设备。

无法配对设备，持续出现错误或随机停止工作

症状

初始 commissioning在 Matter 设备的上下文中，调试是将设备添加到 Matter 控制器的过程。它相当于在 Zigbee 或 Z-Wave 中配对设备。 [Learn more] 不断失败，您遇到发现设备的问题，或者设备随机变为不可用。

原因

  • Matter 协议依赖于（本地）IPv6 和 mDNS（多播流量）在您的网络中自由传输。
  • Matter 旨在常规住宅网络设置中运行，可能无法很好地与例如 VLAN、多播过滤和（故障的）IGMP 侦听等企业网络解决方案集成。

解决办法

  1. 确保使用 Wi-Fi 的 Matter 设备（包括 Thread border routerThread 边界路由器在本地网络和 Thread 网络之间转发数据包。这使得 Thread 网络中的智能家居设备能够与本地网络中的 IPv6 设备通信。Thread 边界路由器通过 Wi-Fi 或以太网连接到您的网络，并使用其射频（RF）无线电与 Thread 网状网络通信。在 Matter 的情况下，转发的数据是加密的。Thread 边界路由器的示例包括 Nest Hub（第 2 代）、HomePod mini 和 Home Assistant Connect ZBT-1 以及 OpenThread Border Router 插件。 [Learn more]）在与 Home Assistant 相同的 VLANs/VLAN 中。
  2. 确保仅使用 ThreadThread 是一种专为智能家居应用设计的低功耗网状网络标准。它是定义设备如何通信的协议。 [Learn more] 的 Matter 设备连接到至少有一个 Thread border routerThread 边界路由器在本地网络和 Thread 网络之间转发数据包。这使得 Thread 网络中的智能家居设备能够与本地网络中的 IPv6 设备通信。Thread 边界路由器通过 Wi-Fi 或以太网连接到您的网络，并使用其射频（RF）无线电与 Thread 网状网络通信。在 Matter 的情况下，转发的数据是加密的。Thread 边界路由器的示例包括 Nest Hub（第 2 代）、HomePod mini 和 Home Assistant Connect ZBT-1 以及 OpenThread Border Router 插件。 [Learn more] 连接到 Home Assistant LAN 的线程网络。
  3. 调查您的网络拓扑。
    • 例如，路由器或 Wi-Fi 接入点上的某个设置以 “优化” 多播流量可能会损害来自 Matter 设备的（发现）流量。当您在添加或控制 Matter 设备时遇到问题时，请记住这一点。
    • 为避免问题，尽量将网络拓扑保持尽可能简单和扁平。

相关主题