Matter 虚拟设备

Matter ; Home API

Matter 虚拟设备对于开发和测试 Matter 解决方案非常有用，可以使用 Google Home app (GHA) 进行调试，并使用 GHA 和 Google Assistant 进行控制，就像实体 Matter 设备一样。

对于需要测试或模拟虚拟 Matter 设备，但缺乏资源来构建自己的实体或虚拟 Matter 设备的应用开发者和其他人员，Google 提供了 Matter Virtual Device (MVD)。MVD 是一款轻量级独立 Linux 或 macOS 桌面工具，可模拟不同类型的虚拟 Matter 设备，并提供图形界面来控制和显示虚拟 Matter 设备的状态。

与实体 Matter 设备不同，MVD 不依赖于蓝牙®低功耗 (BLE) 或 Thread® 即可加入 Matter 结构。而是使用主机 Linux 或 macOS 机器的现有 Wi-Fi 网络连接进行调试。

与其他工具相比

MVD 与 Virtual Device Controller (VDC) 的不同之处在于，它是一个独立的解决方案，将虚拟设备与用于控制该设备的界面相结合。相比之下，VDC 用于控制单独的虚拟 Matter 设备。

MVD 包含多个不同的预构建虚拟设备，并包含一个用于运行和控制这些设备的集成界面。

支持的设备

MVD 支持以下 Matter 设备类型：

表：MVD 支持的 Matter 设备类型
Matter 设备类型 应用集群 Home 生态系统类型
空气净化器 0x0202
0x0006
0x0071
0x0072
 空气净化器
空气质量传感器 0x005b
0x0402
0x0405
0x040c
0x040d
0x042a
0x042b
0x042c
0x042d
0x042e
0x042f
0x0413
0x0415
 传感器
基本视频播放器 0x0006
0x0506
0x0509
 电视
色温灯 0x0300
0x0008
0x0006
 浅色
接触式传感器 0x0045
 传感器
可调光灯 0x0008
0x0006
 浅色
可调光插入式装置 0x0006
0x0008
 插座
洗碗机 0x0006
0x0059
0x0056
0x0060
 洗碗机
门锁 0x0101
 锁定
扩展彩色灯 0x0300
0x0008
0x0006
 浅色
风扇 0x0202
0x0006
 风扇
流量传感器 0x0404
 传感器
通用开关 0x003b
 Switch
湿度传感器 0x0405
 传感器
洗衣机 0x0006
0x0051
0x0053
0x0056
0x0060
 洗衣机
光传感器 0x0400
 传感器
在家/外出传感器 0x0406
 传感器
开/关灯 0x0008
0x0006
 浅色
电灯开关 0x0006
 Switch
开关插接单元 0x0008
0x0006
 插座
压力传感器 0x0403
 传感器
泵 0x0006
0x0200
0x0402
0x0403
0x0404
 泵
扫地机器人 0x0054
0x0055
0x0061
 吸尘器
房间空调 0x0006
0x0201
0x0202
 空调
烟雾/一氧化碳警报器 0x005C
 一氧化碳检测器
烟雾检测器
温度传感器 0x0402
 传感器
温控器 0x0201
 温控器
窗饰 0x0102
 卷帘

安装 MVD

MVD 可在运行 Debian（13 Trixie 或更高版本）、Ubuntu（20.04 Noble Numbat 或更高版本）或 macOS 的 64 位 x86 处理器机器上运行。

Linux

下载 MVD Debian (.deb) 软件包

下载 armored-ASCII 签名 (.asc) 文件

然后运行 dpkg 以安装 MVD Debian (.deb) 软件包：

sudo dpkg -i mvd_1.7.0_amd64.deb

macOS

下载 MVD (macOS x86) dmg 文件

下载 MVD (ARM64 M1) dmg 文件

然后双击 dmg 文件以打开安装窗口。

如需完成安装，请选择 mvd 图标并将其拖动到 Applications 文件夹：

macOS 安装

检查端口使用情况

MVD 中的控制器模块使用 TCP 端口 33000 向虚拟设备发出 RPC 调用，因此，如果此端口已被计算机上的其他进程使用，请务必将其释放。

如需查看是否有任何进程正在使用端口 33000，请运行以下命令：

Linux

sudo fuser -v 33000/tcp

macOS

lsof -i:33000

您可以使用一条命令终止使用 TCP 端口 33000 的任何进程：

Linux

sudo fuser -k 33000/tcp

macOS

lsof -ti:33000 | xargs kill

运行 MVD

Linux

在 Linux 上，从应用文件夹或终端运行 MVD：

mvd

macOS

在 macOS 上，使用启动台打开 MVD，或从终端运行 MVD：

cd /Applications
open mvd.app

配置设备

启动后，系统会显示主屏幕，您可以在其中配置虚拟设备：

  • Device Type：选择设备类型（例如 Light、Switch、Sensor 等）。
  • 设备名称：为设备指定一个简单易懂的名称。
  • 鉴别器：一个 12 位数字，用于区分多个可调试设备通告。（默认值：3840）。
  • Matter 端口：用于通过 IP 网络进行 Matter 调试和通信的端口。Matter 默认使用 TCP/UDP 端口 5540，但您可以将虚拟设备配置为使用其他端口，只要没有其他服务在使用该端口即可。
  • 供应商 ID：仅支持测试供应商 ID 0xFFF1。
  • 产品 ID：仅支持测试产品 ID 0x8000 到 0x801F。

“Virtual Device configuration” （虚拟设备配置）界面

配置防火墙

Linux

如果您的计算机上运行了防火墙，请将其关闭，或允许 Matter 端口上的传入 TCP/UDP 连接。

如需查看当前有效的 netfilter 防火墙规则，请运行以下命令：

sudo iptables -L -n

如果您使用的是 `ufw`，则可以使用以下命令将其停用：

sudo ufw disable

您可以使用以下命令重新启用该功能：

sudo ufw enable

macOS

如需在 macOS 上配置或停用防火墙，请执行以下操作：

  1. 前往  Apple 菜单，然后选择系统设置。
  2. 点击边栏列表中的网络。
  3. 点击防火墙。
  4. 将防火墙开关切换到关闭位置。

运行设备

配置设备后，点击创建设备。创建设备后，系统会显示 Controller 屏幕。根据您选择的设备类型，您可能会看到以下一个或多个控件：

  • 开/关：大多数设备都支持。
  • Level：例如，灯可以有一个用于调节亮度的级别滑块。
  • 颜色：例如，彩色灯可以具有此控件。
  • 在家/外出：在家/外出传感器提供此控件，用于模拟有人或无人的状态。

所有虚拟设备都具有以下控件：

  • QRCode：显示用于调试的二维码。
  • Reboot：重启虚拟设备。设备会短暂断开与网络的连接。
  • 重置：将当前设备恢复出厂设置，并清除所有状态，包括调试、当前控件状态等
  • 删除：销毁设备并返回创建设备界面。

虚拟设备控制界面

特定于制造商的特征

适用于 Android 的 Home API 支持制造商专用 (MS) 特性，这些特性提供了 Matter 中的标准特性之外的其他功能。如需测试具有 MS 特性的设备，MVD 允许您与名为自定义集群的部分中的特性进行交互（请参阅上图）。

调试设备

设备一经创建即可进行调试。

调试设备需要满足以下几个前提条件：

  • 您必须在 Google Home Developer Console 中有一个项目。此项目必须包含一个 Matter 集成，该集成具有与您在设置虚拟设备时使用的 VID/PID 组合相同的 VID/PID 组合。如需了解详情，请参阅项目创建指南。

  • 您必须拥有支持 Matter 的 Google Nest Hub

  • 您必须拥有搭载 Android 8.1 或更高版本且安装了 GHA 的 Android 手机。

  • Android 手机必须与 hub 连接到同一 Wi-Fi 网络。

  • 主机必须连接到 Wi-Fi 网络。

如需使用 GHA 调试设备，请点击 QRCode 以显示设备的二维码，然后按照配对 Matter 设备中的说明操作，其中介绍了如何使用 GHA 注册 Matter 设备。您也可以使用 Google Home Sample App for Matter 调试设备。

请参阅我们的 Matter 入门指南，了解 Matter 调试的工作原理。

控制设备

调试虚拟设备后，您可以使用 Google Home 应用或 Google 助理通过语音控制设备。您可以执行以下任一项操作：

  • 通过 GHA 或 Assistant 控制设备，同时监控虚拟设备上的状态变化，或者
  • 使用 Sample App for Matter 控制设备，同时监控虚拟设备上的状态变化，或者
  • 通过 MVD 本身控制设备状态，同时监控 GHA 或 Assistant 中的状态变化。

使用设备进行测试

如需使用 Assistant 进行测试，我们建议您使用话语模拟器，例如 Google Home Extension for VS Code 或 Google Home Plugin for Android Studio。

查看设备详细信息

设备详情界面会显示详细的设备信息：

  • 名称：为设备指定的易记名称。
  • 设备类型：所选的设备类型。
  • Discriminator：当前设备判别器。
  • 供应商 ID：当前设备供应商 ID。
  • 产品 ID：当前设备的产品 ID。
  • RPC 端口：设备与控制器 (GUI) 通信时使用的 RPC 端口。
  • Matter 端口：当前设备用于通过 IP 网络进行通信的端口。
  • Pass Code：用于通过网络调试设备的 PIN 码。
  • 配置文件夹：虚拟设备存储配置的文件夹。
  • 调试信息：显示设备加入的结构以及设备在结构中的节点 ID。

查看设备日志

如果您从终端启动了 MVD，日志输出会显示在 stdout 上。您还可以在设备日志标签页中查看设备日志。

停止设备

如需停止并销毁设备，请点击删除。

终止应用

关闭控制窗口会销毁设备并终止 MVD 应用。如果您是从终端启动的应用，也可以在终端中输入 Ctrl-C 来终止应用。

获取帮助

如需获取有关 MVD 的帮助、报告 bug 或请求新功能，请与您的 Google 支持联系人联系。

点击窗口右上角的帮助 按钮可转到此页面。

提交 bug

如果您认为自己在 MVD 中发现了缺陷，可以点击窗口右上角的“问题” 按钮来提交 bug。

发送反馈

如需提交您对 MVD 的看法或您认为我们如何改进该工具的使用体验，请填写我们的反馈表单。

您可以通过点击窗口右上角的反馈 按钮或点击下方按钮来启动表单。

向我们发送反馈

您也可以通过使用 MVD 时底部弹出的调查问卷提供反馈。