Matter PSoC6 All Clusters 示例应用实战:在 Infineon CY8CKIT-062S2-43012 上构建、烧录与 BLE 配网指南
Matter PSoC6 All Clusters 示例应用实战:在 Infineon CY8CKIT-062S2-43012 上构建、烧录与 BLE 配网指南
本篇技术指南围绕 Matter(原 Project CHIP)官方示例 all-clusters-app 在 Infineon PSoC6 平台上的移植实现展开,完整覆盖从环境准备、GN 构建、KitProg3 烧录,到基于 chip-tool 的 BLE 配网(Commissioning)、Wi-Fi 入网、集群控制、出厂重置以及 OTA 软件更新的全流程。读完本文,你将能够在 CY8CKIT-062S2-43012 开发板上跑通一套可被 Matter 控制器远程操控的 All Clusters 集群控制设备,并理解其底层的 FreeRTOS 任务结构、PASE/SASE 配网参数与双分区 OTA 机制。
示例应用定位与整体架构
示例位于仓库的 examples/all-clusters-app/infineon/psoc6 目录,其目标是提供一个基于 Matter 与 Infineon ModusToolbox SDK 构建的集群控制设备(Cluster control device)基线演示:设备通过 Wi-Fi 网络接入局域网,可被任意 Matter 控制器(如 chip-tool)控制;在初始阶段则通过 Bluetooth Low Energy(BLE)完成配网。
配网采用 Matter 标准的 Rendezvous 流程:
- PSoC6 设备通过 BLE 广播并暴露 Matter 服务(CHIPoBLE),BLE 设备名为
PSOC6_CLUSTERS(见 src/main.cpp)。 - Matter 控制器与设备通过 BLE 建立 PASE(Password-Authenticated Session Establishment)会话,交换安全信息。
- 控制器通过该安全通道将 Wi-Fi 网络凭据下发到设备。
- PSoC6 设备凭据入网后切换至 Wi-Fi/IP 通信,通过 CASE(Certificate-Authenticated Session Establishment)会话与控制器完成后续集群交互。
这一"BLE 配网 + Wi-Fi 业务"的双模模式是当前 Matter 生态中 Wi-Fi 设备最典型的落地路径,也是本文后续所有命令的核心前提。
应用源码结构与启动流程
从 BUILD.gn 可以看出,该示例是一个运行在 FreeRTOS 之上的 GN 工程(assert(current_os == "freertos")),产物名为 chip-psoc6-clusters-example.out。其可执行目标 clusters_app 的源码由三部分组成:
- 平台公共部分:复用
examples/all-clusters-app/all-clusters-common/src/下的大量集群实例与模式管理器(如 air-quality、fan、rvc-modes、thermostat-mode、oven-modes 等 stubs 与 delegate 实现),这些代码支撑了 All Clusters 应用对数十个 Matter 集群的声明与响应能力; - PSoC6 平台层:
examples/platform/infineon/psoc6下的LEDWidget.cpp、init_psoc6Platform.cpp负责 LED 与板级外设初始化; - 应用层:
src/AppTask.cpp、src/ButtonHandler.cpp、src/ClusterManager.cpp、src/ZclCallbacks.cpp与src/main.cpp构成应用的任务编排与事件处理逻辑。
启动链路
入口 src/main.cpp 的启动顺序清晰地展示了嵌入式 Matter 应用的初始化骨架:
int main(void)
{
init_psoc6Platform(); // 板级平台初始化
...
vTaskStartScheduler(); // 启动 FreeRTOS 调度器
}
调度器启动后,vApplicationDaemonTaskStartupHook 中会先完成 chip::Platform::MemoryInit()(CHIP 内存管理初始化),随后创建主任务 main_task(栈 4096 字节、优先级 2)。主任务内依次执行:
KeyValueStoreMgrImpl().Init()—— 初始化持久化 KV 存储(用于保存配网凭据与 Matter 配置);PlatformMgr().InitChipStack()—— 初始化 CHIP 平台栈;ConnectivityMgr().SetBLEDeviceName("PSOC6_CLUSTERS")—— 设置 BLE 广播名;PlatformMgr().StartEventLoopTask()—— 启动平台事件循环;GetAppTask().StartAppTask()—— 启动应用任务。
应用任务侧(src/AppTask.cpp)的 AppTask::Init() 会完成:注册 MDNS 服务启动回调(IPv4/IPv6 连通后启动 DnssdServer)、通过 ScheduleWork 初始化 Matter Server(含示例 DAC 设备认证凭据提供者)、初始化按钮、创建功能定时器、初始化 Wi-Fi 网络配网实例(sWiFiNetworkCommissioningInstance,挂在 Endpoint 0),最后打印设备配网信息(含 BLE 的 onboarding QR 码)。所有关键步骤失败都会进入 appError() 死循环并打印 App Critical Error,便于串口定位。
构建环境准备
硬件
官方支持的评估板为 CY8CKIT-062S2-43012(PSoC 6 MCU + CYW43012 Wi-Fi/BLE Combo 芯片),芯片内置 Wi-Fi 与 BLE 双模能力,正是上文"BLE 配网 + Wi-Fi 业务"架构的硬件基础。
软件依赖
- ModusToolbox Software v3.2:从 Infineon 官网下载安装。仓库提供了两种参考方式:
- 官方 CI Docker 镜像 integrations/docker/images/stage-2/chip-build-infineon/Dockerfile:该镜像基于
chip-build基础镜像,通过curl下载ModusToolbox_3.2.0.16028-linux-install.deb并安装,随后由/etc/profile.d/modustoolbox_3.2.sh初始化CY_TOOLS_PATHS环境变量; - 构建脚本 scripts/examples/gn_psoc6_example.sh:脚本开头会检查
CY_TOOLS_PATHS是否已设置,未设置时提示安装 ModusToolbox v3.2。
- 官方 CI Docker 镜像 integrations/docker/images/stage-2/chip-build-infineon/Dockerfile:该镜像基于
- Linux 构建工具链(Matter 开发者通常已具备):
sudo apt install gcc g++ clang ninja-build python \
python3-venv libssl-dev libavahi-client-dev libglib2.0-dev git cmake \
python3-pip
其中 libavahi-client-dev 与 libglib2.0-dev 是编译 host 侧工具(如 chip-tool)所需的 D-Bus/Avahi mDNS 依赖。
构建示例应用
在仓库根目录激活 Matter 构建环境并执行官方构建入口:
$ source scripts/activate.sh
$ scripts/build/build_examples.py --no-log-timestamps --target 'infineon-psoc6-all-clusters' build
构建产物默认输出到 out/infineon-psoc6-all-clusters/ 目录。若要清理所有生成物(可执行文件、库、目标文件),执行:
$ cd ~/connectedhomeip
$ rm -rf out/
构建系统底层逻辑
build_examples.py 实际会透传到 scripts/examples/gn_psoc6_example.sh 完成 GN + Ninja 两段式构建:
gn gen --check --fail-on-unused-args "$OUTPUT_DIR" --root="$EXAMPLE_DIR" --args="psoc6_board=\"$PSOC6_BOARD\" ${GN_ARGS[*]}"
ninja -C "$OUTPUT_DIR" "${NINJA_ARGS[@]}"
arm-none-eabi-size -A "$OUTPUT_DIR"/*.out # 打印各 section 大小
该脚本固定使用 psoc6_board="CY8CKIT-062S2-43012" 作为目标板,并支持通过 key=value 参数透传额外的 GN args。例如:
# 启用 OTA Requestor(见下文 OTA 章节)
scripts/build/build_examples.py --target 'infineon-psoc6-all-clusters' build -- -Dchip_enable_ota_requestor=true
在 BUILD.gn 中声明了几个对本示例非常有用的 GN 参数:
| GN 参数 | 默认值 | 作用 |
|---|---|---|
chip_print_memory_usage |
false |
链接时通过 -Wl,--print-memory-usage -fstack-usage 输出内存占用 |
setup_pin_code |
20202021 |
用于 PASE 会话建立的 Setup PIN Code |
enable_heap_monitoring |
false |
启用运行时堆监控(编译进 MemMonitoring.cpp,定义 HEAP_MONITORING) |
build_update_image |
false |
构建 OTA 更新镜像时置为 true(会令软件版本号提升为 2) |
其中 setup_pin_code 通过 CHIP_DEVICE_CONFIG_USE_TEST_SETUP_PIN_CODE 注入到编译定义中,与 include/CHIPProjectConfig.h 中默认的 PIN Code 20202021、Discriminator 0xF00(即十进制 3840)保持一致——这正是后续 chip-tool 配网命令参数 20202021 3840 的来源。
烧录应用程序
-
将 CY8CKIT-062S2-43012 开发板切换到 KitProg3 CMSIS-DAP 模式:按住
MODE SELECT按钮。当KITPROG3 STATUSLED 点亮即表示已处于正确模式(此操作需要已安装 ModusToolbox Software)。 -
在命令行中执行烧录脚本:
$ cd ~/connectedhomeip
$ export CY_TOOLS_PATHS=<ModusToolbox install location>/tools_3.2
$ python3 out/infineon-psoc6-all-clusters/chip-psoc6-clusters-example.flash.py
CY_TOOLS_PATHS 必须指向 ModusToolbox 安装目录下的 tools_3.2,烧录脚本依赖其中的 OpenOCD/工具链对 KitProg3 编程器进行操作。
配网与集群控制
设备上电运行后,使用 BLE 方式完成配网。
第一步:搭建 chip-tool 控制器
在 Raspberry Pi 4(或其他 Linux 主机)上构建 chip-tool:
$ cd {path-to-connectedhomeip}
$ ./scripts/examples/gn_build_example.sh examples/chip-tool out/debug
启动控制器(进入交互式命令行):
$ ./out/debug/chip-tool
第二步:通过 BLE 配网(Commissioning over BLE)
执行配网命令时,需要传入远端设备的 Discriminator、配对码(Setup PIN Code),以及目标 Wi-Fi 网络的凭据:
$ ./out/debug/chip-tool pairing ble-wifi 1234 ${SSID} ${PASSWORD} 20202021 3840
各参数含义如下:
| 序号 | 参数 | 值 | 说明 |
|---|---|---|---|
| 1 | Discriminator | 3840 |
设备在 BLE 广播中携带的标识(对应源码中的 0xF00) |
| 2 | Setup PIN Code | 20202021 |
PASE 会话配对码(对应 CHIPProjectConfig.h 中的 CHIP_DEVICE_CONFIG_USE_TEST_SETUP_PIN_CODE) |
| 3 | Node ID | 1234 |
分配给设备的 Fabric 内节点 ID(可任意指定) |
| 4 | SSID | 用户自定 | Wi-Fi SSID |
| 5 | PASSWORD | 用户自定 | Wi-Fi 密码 |
配网成功后,设备即完成 Wi-Fi 入网并可通过 chip-tool 的集群命令进行控制(如 onoff、levelcontrol 等 All Clusters 应用声明的集群)。设备端的启动日志中会打印 Onboarding 二维码与手动配对码(AppTask.cpp 中的 PrintOnboardingCodes),也可使用官方 Matter 手机 App 扫码配网。
针对 Raspberry Pi 4 的 BLE 注意事项
Raspberry Pi 4 的 BLE 连接偶发不稳定,可先执行以下命令对蓝牙硬件进行电源循环,并关闭 BR/EDR 模式(仅保留 BLE):
$ sudo btmgmt -i hci0 power off
$ sudo btmgmt -i hci0 bredr off
$ sudo btmgmt -i hci0 power on
出厂重置(Factory Reset)
- 短按开发板上的
USER_BTN2按钮即可清除已配网的 Wi-Fi 凭据。设备在初始配网期间配置的所有数据(含 Fabric 信息、网络凭据、集群配置)都会被删除,设备恢复为可重新配网状态。 - 在按下后的 5 秒内再次按下
USER_BTN2,可取消本次出厂重置。
该"5 秒取消窗口"与源码中的 FACTORY_RESET_CANCEL_WINDOW_TIMEOUT 5000(单位 ms)完全对应,见 AppTask.cpp。在 AppConfig.h 中,APP_FUNCTION_BUTTON 被映射为 CYBSP_USER_BTN2,APP_LIGHT_BUTTON 映射为 CYBSP_USER_BTN1;按钮事件由 ButtonHandler.cpp 通过 FreeRTOS 软件定时器做 30ms 去抖(APP_BUTTON_MIN_ASSERT_TIME_MS)后上报给 AppTask 分发处理。
OTA 软件更新
PSoC6 示例应用支持 Matter 标准的 OTA 软件更新(OTA Requestor 角色)。详细的端到端流程(Provider 构建、bootloader 烧录、双镜像刷写、announce-otaprovider 触发下载)请参阅 Infineon PSoC6 OTA Software Update,这里提炼其核心要点:
-
开启方式:为任意 Infineon PSoC6 示例应用传递
chip_enable_ota_requestor=trueGN 参数即可启用 OTA Requestor 功能。 -
双分区固件布局:启用 OTA 后,BUILD.gn 中的
psoc6_ota_config会切换到双 OTA 链接脚本cy8c6xxa_cm4_dual_ota_int.ld,并注入一组 MCUBoot 分区宏:主镜像区(FLASH_AREA_IMG_1_PRIMARY,内部 Flash,起始0x028000、大小0x1c0000)、次镜像区(FLASH_AREA_IMG_1_SECONDARY,外部 Flash,起始0x000200)、交换状态区与 scratch 区等,同时定义COMPONENT_MCUBOOT、CY_BOOTLOADER=MCUBOOT、OTA_USE_EXTERNAL_FLASH=1等编译宏。 -
版本管理:设备侧软件版本由
CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION决定(默认为 1,见 CHIPProjectConfig.h);构建更新镜像时(build_update_image=true)版本号提升为 2。OTA Provider 配置中的softwareVersion必须大于设备当前版本号,否则更新不会下发。 -
bootloader 前置:刷入应用前需先用 Cypress Programmer 将预编译的 MCUBoot bootloader(
third_party/infineon/psoc6/psoc6_sdk/ota/matter-psoc6-mcuboot-bootloader.hex)烧录到板子。启动时应用会调用flash_area_boot_set_confirmed()确认当前镜像有效(AppTask.cpp),并在main.cpp中清理 bootloader 启动的看门狗,避免下载新镜像前被意外复位。 -
触发流程:Provider 端启动
chip-ota-provider-app -f xxx.ota并提供更新文件后,通过 chip-tool 执行otasoftwareupdaterequestor announce-otaprovider通知设备;设备作为 OTA Requestor 通过 BDX 协议下载镜像、写入外部 Flash 次分区,完成后自动重启进入新镜像。
OTA Requestor 的运行时对象(DefaultOTARequestor、BDXDownloader、OTAImageProcessorImpl 等)在 AppTask.cpp 中实例化,并通过 InitOTARequestor() 完成初始化。
关键配置项速查
对开发 PSoC6 Matter 设备有价值的配置集中在 include/CHIPProjectConfig.h:
| 配置宏 | 默认值 | 说明 |
|---|---|---|
CHIP_DEVICE_CONFIG_USE_TEST_SETUP_PIN_CODE |
20202021 |
测试配对码,配网命令需与此一致 |
CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR |
0xF00 (3840) |
BLE 广播 Discriminator |
CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID |
0x8003 |
Basic 集群的 ProductID 属性 |
CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_NAME |
PSOC6-CYW43012 All Clusters |
Basic 集群的 ProductName |
CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION |
1 |
软件版本号(OTA 依据) |
CHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE |
1 |
启用 CHIPoBLE(BLE 配网必需) |
CHIP_CONFIG_MAX_GROUP_ENDPOINTS_PER_FABRIC |
3 |
All Clusters 应用含 3 个组播 Endpoint,须在此预定义 |
CHIP_CONFIG_ENABLE_ACL_EXTENSIONS |
1 |
启用 ACL Cluster 的 Extension 属性 |
注意:
CHIP_CONFIG_SECURITY_TEST_MODE默认保持0(关闭)。该选项会绕过包括消息加密在内的 Matter 安全机制,严禁在生产构建中启用。
总结
通过本文你可以完整跑通 Matter All Clusters 示例在 Infineon PSoC6 上的"构建 — 烧录 — BLE 配网 — Wi-Fi 控制 — 出厂重置 — OTA 升级"全链路。该示例不仅是评估 CY8CKIT-062S2-43012 开发板的快速起点,其 BUILD.gn 中的 GN 参数体系(PIN Code、OTA 分区、堆监控)与 src/AppTask.cpp 中的任务编排模式,也为将自有产品移植到 PSoC6 平台提供了可直接复用的工程范式。