connectedhomeip 模拟设备指南（Linux）：构建、运行 chip-app1 并编写 YAML 测试-港品优选

connectedhomeip 模拟设备指南（Linux）：构建、运行 chip-app1 并编写 YAML 测试

【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip

本文基于 docs/guides/simulated_device_linux.md 展开，讲解如何在 Linux 上构建并运行 Matter（Project CHIP）模拟设备（Simulated Device），如何用 chip-tool 与模拟设备配网、下发簇命令，以及如何通过 YAML 文件为模拟设备补充认证测试用例。读完本文，你能够独立完成模拟设备的构建、启动、配网与集群命令交互，并掌握 YAML 测试的命名规范与可用属性，为验证 commissioner/controller 行为建立一条可复用的测试链路。

模拟设备是什么

原文档将 Simulated Device 定义为：一种"应用仿真"，其形态由 ZAP 配置文件定义，并且可以附加 YAML 测试文件，用于验证 commissioner/controller 的行为是否符合预期。原文档给出的典型用例路径是：

虚拟配件统一放在examples/placeholder/linux/apps目录下，每个配件对应一个子文件夹，文件夹名即应用名——例如app1会生成名为chip-app1的二进制；
如果需要覆盖默认编译参数，可以在应用文件夹下放置include/CHIPProjectConfig.h（例如examples/placeholder/linux/apps/app1/include/CHIPProjectConfig.h）。

需要说明的是：在当前仓库快照中，examples/placeholder目录已不存在（examples 目录下不再包含 placeholder 子树），文档中引用的示例 ZAP 配置与部分示例文件属于该文档所对应的历史版本；下文所有命令以原文档为准照录，而涉及具体文件与测试框架的佐证则引用当前快照中确实存在的文件。

模拟设备的底层入口是 Linux 平台的通用应用框架。从 examples/platform/linux/BUILD.gn 可以看到，app-mainsource_set 以 AppMain.cpp 为核心，聚合了配网初始化（CommissionableInit.cpp）、命令行选项解析（Options.cpp）、命名管道命令（NamedPipeCommands.cpp）以及各类测试事件触发器，这正是chip-app1这类二进制能够完成配网、日志输出 SetupQRCode 并响应测试事件的底层支撑。

构建前置条件

按照原文档，构建模拟设备之前需要满足以下前置条件（链接已转换为仓库根目录相对路径）：

构建前置依赖（Prerequisites）：docs/guides/BUILDING.md#prerequisites
构建准备（Prepare For Building）：docs/guides/BUILDING.md#prepare-for-building
代码生成流程：docs/zap_and_codegen/code_generation.md
已安装 ZAP 并配置环境变量：docs/zap_and_codegen/code_generation.md#installing-zap-and-environment-variables

这些步骤的核心是：先让环境具备编译器、Python 虚拟环境与 ZAP 代码生成能力，再通过 ZAP 生成器把 ZAP 配置转换成应用代码，最终由 GN/Ninja 完成编译。

方式一：使用脚本构建默认模拟应用

原文档给出的推荐路径是借助scripts/examples/gn_build_example.sh脚本。构建chip-app1二进制的完整命令如下：

./scripts/examples/gn_build_example.sh examples/placeholder/linux out/debug/simulated/ chip_tests_zap_config="app1"

命令中各部分的含义：

examples/placeholder/linux：目标示例目录，脚本会以其作为 GN 构建根；
out/debug/simulated/：输出目录，构建产物（包括chip-app1）会落在该目录下；
chip_tests_zap_config="app1"：GN 参数，指定使用app1对应的 ZAP 配置生成该虚拟配件的应用代码，最终产物命名规则为chip-<应用名>。

注意：chip_tests_zap_config是原文档中由 placeholder 示例声明的 GN 参数。在当前仓库快照中，全仓库检索不到该参数名，可以推断该参数随examples/placeholder示例一起从主线移除或改名；如果你在当前版本执行上述脚本报错，应先查看 scripts/examples/gn_build_example.sh 的用法说明，确认当前版本支持的参数与示例目录。

方式二：直接使用 gn 与 ninja 构建（替代方案）

如果不经过脚本封装，可以直接用 gn + ninja 完成同样的构建。原文档给出的步骤为：

source scripts/activate.sh gn gen --check --root=examples/placeholder/linux out/simulated --args="chip_tests_zap_config=\"app1\"" ninja -C out/simulated

source scripts/activate.sh：激活仓库 Python 虚拟环境（scripts/activate.sh），使gn、ninja等工具链路径生效；
gn gen --check --root=examples/placeholder/linux out/simulated --args=...：在out/simulated下生成构建文件并做参数检查，--args传入与脚本方式相同的chip_tests_zap_config="app1"；
ninja -C out/simulated：进入输出目录执行编译，生成chip-app1。

两种方式的区别仅在于是否由脚本代劳 gn 配置与 ninja 调度的细节；产物与输出目录结构保持一致（out/debug/simulated或out/simulated，取决于你指定的输出目录）。

运行模拟设备应用

构建完成后，可以直接在 Linux 上执行二进制：

./out/debug/simulated/chip-app1

启动后，应用会在日志中打印配网信息，其中SetupQRCode:一行输出的配对码（setup code 对应的二维码字符串）是后续用 chip-tool 配网的关键输入。

使用测试参数运行（YAML 测试入口）

模拟设备同样支持以测试模式运行。原文档给出的命令为：

./scripts/tests/chipyaml/runner.py [TEST NAME] app1

其中：

[TEST NAME]：要执行的 YAML 测试名称；
app1：目标模拟设备应用名，runner 会将该测试下发到指定设备上执行。

该 runner 的真实入口是 scripts/tests/chipyaml/runner.py。从源码看，它基于click组织命令行选项，默认从src/app/zap-templates/zcl/data-model/chip/*.xml加载数据模型规范，并默认读取src/app/tests/suites/certification/ci-pics-values作为 PICS 文件；同时支持通过--additional-pseudo-clusters-directory加载自定义伪簇。也就是说，测试名能否被识别、测试步骤如何解析，都取决于这套 YAML 测试解析与数据模型规范。

用 chip-tool 与模拟应用交互

应用启动并完成配网后，就可以使用 chip-tool 与之交互。原文档的交互流程为：

按照 docs/examples/chip_tool.md 等文档说明构建 chip-tool（原文档指向examples/chip-tool/README.md，该目录在当前快照中不存在，可参考 docs 下的 chip-tool 文档）；
使用日志SetupQRCode:行中的配对码执行配网命令：
```
./out/debug/standalone/chip-tool pairing code 0x654321 MT:-24J0AFN00KA0648G00
```
其中0x654321是控制器侧的 commissioning node ID（示例值），MT:-24J0AFN00KA0648G00是 Setup QR Code 字符串，需替换为实际日志中输出的内容；
配网完成后，大多数测试会开始运行。此时可以像对待真实 Matter 设备一样发送簇命令，例如：
```
./out/debug/standalone/chip-tool onoff on 0x654321 1 ./out/debug/standalone/chip-tool onoff read on-off 0x654321 1 ./out/debug/standalone/chip-tool onoff write on-time 1 0x654321 1
```
三条命令分别演示了：向端点 1 下发on命令、读取OnOff属性、写入OnTime属性。更多可用命令请参考 chip-tool 相关文档。

这里体现的正是模拟设备的价值：它没有硬件，却完整实现了"设备侧"的数据模型行为（属性读写、命令处理、配网流程），因此可以用标准 chip-tool 工作流验证控制器到设备侧的整条链路。

通过 YAML 为模拟设备添加测试

为验证 commissioner/controller 行为，需要向模拟设备测试框架添加测试，方式是创建 YAML 测试文件。原文档给出的规范如下：

文件位置：YAML 测试文件统一放在 src/app/tests/suites/certification/ 目录下；
命名格式（CI 依赖此规则识别测试）：
```
Test_TC_[CATEGORY ABBREVIATION]_[SECTION NUMBER]_[SUBSECTION NUMBER]_Simulated.yaml
```
重要：测试名必须以大写开头的Simulated结尾；
可用属性：完整属性清单见 src/app/tests/suites/README.md；
模拟设备特有属性：
名称说明
wait 期望从 controller 端接收到、由 app 等待执行的命令
wait是模拟设备方向的关键属性：普通 YAML 测试通常是"controller 发命令、校验响应"，而模拟设备作为被仿真的一侧，需要用wait声明它期望 controller 发出的命令，从而测试控制器的行为；
示例：原文档以Test_TC_DM_1_3_Simulated.yaml作为示例。该文件在当前仓库快照中已不存在，但同目录下仍存在一批按同一命名规范编写的模拟设备测试，例如 Test_TC_CC_3_4_Simulated.yaml、Test_TC_CC_4_5_Simulated.yaml、Test_TC_OO_3_2_Simulated.yaml、Test_TC_TBRM_3_1_Simulated.yaml 等，可直接作为编写新测试的模板参考。

名称	说明
wait	期望从 controller 端接收到、由 app 等待执行的命令

YAML 测试文件的核心结构速览

结合 src/app/tests/suites/README.md，一个 YAML 测试文件由三层构成，编写时可对照使用：

测试集（Test Set）层属性：

属性	说明	必填
name	人类可读的测试集名称	是
config	测试集中每个测试继承的默认配置	是
tests	测试集合，支持用`{{chip_test_items}}`迭代	是

默认配置层属性：

属性	说明	必填
cluster	簇名（取自数据模型簇名索引）	否
endpoint	测试默认目标端点标识	否
identity	执行测试的控制器名（支持 alpha、beta、gamma）	否
{variable_name}	测试内使用的变量名	否

单个测试（Test）层属性（摘录）：

属性	说明
label	测试名称
disabled	停用该测试
command	要执行的命令，可以是簇命令或特殊命令
attribute	特殊属性命令的目标属性名
optional	标记为可选测试：设备不支持该命令即视为通过
cluster / endpoint	未指定时继承默认配置
arguments	传给命令的参数列表，支持`{{chip_test_item_parameters}}`迭代
response	期望的响应结果或约束，支持`{{chip_test_item_response_parameters}}`迭代
PICS	协议实现一致性声明条件，决定该测试步骤是否执行
timedInteractionTimeoutMs	写属性与发命令的超时设置

其中response可进一步使用values（期望值列表）、value、error（期望错误码）、saveAs（把响应值存入变量供后续步骤使用）等子属性；arguments的values子项由name（可选）与value（必填）组成。

编写新测试时的推荐步骤：

在 src/app/tests/suites/certification/ 下按Test_TC_<类别缩写>_<节号>_<小节号>_Simulated.yaml命名新建文件；
从上述任一现存*_Simulated.yaml复制骨架，声明name、config、tests；
用command+arguments描述 controller 侧行为，用wait描述设备侧（模拟应用）期望收到的命令，用response约束校验点；
用./scripts/tests/chipyaml/runner.py [TEST NAME] app1在本地跑通，再交给 CI 识别执行。

小结

模拟设备把"设备侧实现"压缩成一个可在 Linux 上直接运行的二进制：由 ZAP 配置定义其数据模型，通过chip-app1形式启动后用 chip-tool 完成配网与簇命令交互，再借助Test_TC_*_Simulated.yaml测试文件持续验证 controller 行为。构建（脚本或 gn/ninja 两条路径）、运行（普通模式与 runner.py 测试模式）、交互（pairing code 配网 + onoff 命令）与测试编写（命名规范 +wait属性 + YAML 属性表）四个环节环环相扣，构成一条完整的、无硬件依赖的 Matter 行为验证链路。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析