Matter PSoC6 All Clusters 示例应用实战:在 Infineon CY8CKIT-062S2-43012 上构建、烧录与 BLE 配网指南

原创2026-09-18 22:26:181,670 阅读
文章标签:物联网智能家居嵌入式IoT协议通信网络蓝牙密码学认证鉴权

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 流程:

  1. PSoC6 设备通过 BLE 广播并暴露 Matter 服务(CHIPoBLE),BLE 设备名为 PSOC6_CLUSTERS(见 src/main.cpp)。
  2. Matter 控制器与设备通过 BLE 建立 PASE(Password-Authenticated Session Establishment)会话,交换安全信息。
  3. 控制器通过该安全通道将 Wi-Fi 网络凭据下发到设备。
  4. 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)。主任务内依次执行:

  1. KeyValueStoreMgrImpl().Init() —— 初始化持久化 KV 存储(用于保存配网凭据与 Matter 配置);
  2. PlatformMgr().InitChipStack() —— 初始化 CHIP 平台栈;
  3. ConnectivityMgr().SetBLEDeviceName("PSOC6_CLUSTERS") —— 设置 BLE 广播名;
  4. PlatformMgr().StartEventLoopTask() —— 启动平台事件循环;
  5. 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 业务"架构的硬件基础。

软件依赖

  1. ModusToolbox Software v3.2:从 Infineon 官网下载安装。仓库提供了两种参考方式:
  2. 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 的来源。

烧录应用程序

  1. 将 CY8CKIT-062S2-43012 开发板切换到 KitProg3 CMSIS-DAP 模式:按住 MODE SELECT 按钮。当 KITPROG3 STATUS LED 点亮即表示已处于正确模式(此操作需要已安装 ModusToolbox Software)。

  2. 在命令行中执行烧录脚本:

$ 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,这里提炼其核心要点:

  1. 开启方式:为任意 Infineon PSoC6 示例应用传递 chip_enable_ota_requestor=true GN 参数即可启用 OTA Requestor 功能。

  2. 双分区固件布局:启用 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 等编译宏。

  3. 版本管理:设备侧软件版本由 CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION 决定(默认为 1,见 CHIPProjectConfig.h);构建更新镜像时(build_update_image=true)版本号提升为 2。OTA Provider 配置中的 softwareVersion 必须大于设备当前版本号,否则更新不会下发。

  4. 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 启动的看门狗,避免下载新镜像前被意外复位。

  5. 触发流程: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 平台提供了可直接复用的工程范式。

登录后查看全文
connectedhomeip