Matter SDK 示例应用深度解析Qorvo QPG6200 Persistent Storage 应用与 Key-Value 存储 API 验证【免费下载链接】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本篇文章以 Matter原 Project CHIP开源仓库中的 examples/persistent-storage/qpg/APPLICATION.md 为主线全面讲解运行在 Qorvo QPG6200 平台上的持久化存储示例应用Persistent Storage Application它如何借助 Matter 的 Key-Value 存储KVS接口验证不同平台的持久化存储实现如何通过一组标准测试用例检验 API 的正确性以及启动日志中每一行输出背后的代码逻辑。读完本文你将掌握KeyValueStoreManager的Put/Get/Delete用法、QPG 平台的 KVS 适配方式并能独立读懂或移植这套 KVS 验证框架。一、应用定位既是测试台也是 API 使用范例QPG6200 Persistent Storage Application 是 Matter SDK 中一个小而专的示例工程其目标非常明确演示并验证 Key-Value 存储 API 在 Qorvo QPG6200 上的实现。原文档明确指出APPLICATION.mdAn example application showing the use of key value storage API on the Qorvo QPG6200.它承担着双重角色KVS 实现的 Bring-up 验证当 KVS 后端被移植到新平台时这套示例可以立即运行通过一组预置测试用例检验底层存储实现是否正确API 使用参考它以最直接的方式展示了应用层如何调用持久化存储接口是开发者学习PersistedStorage::KeyValueStoreMgr()用法的入门范例。原文档还提到未来当各平台都具备条件后这套测试逻辑可能会迁移为单元测试unit test。这也解释了为什么示例与测试逻辑是分离的——测试代码被抽离在共享文件中由不同平台的工程复用。需要说明的是原文档末尾的SDK Documentation链接指向 examples/platform/qpg/README.md该文件目前仅保留了 Qorvo SDK 的外部信息占位文档头标注orphan: true实际内容为 Qorvo 产品线与支持联系方式。因此本文的深入解读将以仓库内的真实源码示例入口、共享测试代码、KVS 抽象层与 QPG 平台实现为依据展开。二、应用结构一个任务、一轮测试、循环执行QPG6200 示例的入口代码位于 examples/persistent-storage/qpg/main.cpp整体结构非常精简只有三个函数2.1main()启动 Qorvo 栈与 FreeRTOS 调度器int main(void) { int result; /* Initialize Qorvo stack */ result qvCHIP_init(Application_Init); if (result 0) { goto exit; } qvCHIP_Printf(LOG_MODULE_ID, Starting FreeRTOS scheduler); vTaskStartScheduler(); // Should never get here. qvCHIP_Printf(LOG_MODULE_ID, vTaskStartScheduler() failed); exit: return 0; }关键点qvCHIP_init(Application_Init)是 Qorvo SDK 提供的初始化接口注册应用回调Application_Init并完成底层协议栈初始化返回负数表示失败vTaskStartScheduler()启动 FreeRTOS 调度器正常情况下不会返回任务栈通过静态方式分配appStack[APP_TASK_STACK_SIZE / sizeof(StackType_t)]与appTaskStruct配合xTaskCreateStatic使用避免在嵌入式环境中动态分配内存的不确定性。APP_TASK_STACK_SIZE定义为3 * 1024字节main.cpp。2.2Application_Init()打印启动横幅并创建测试任务void Application_Init(void) { /* Launch application task */ qvCHIP_Printf(LOG_MODULE_ID, ); qvCHIP_Printf(LOG_MODULE_ID, Qorvo APP_NAME Launching); qvCHIP_Printf(LOG_MODULE_ID, ); // Run tests xTaskCreateStatic(TestTask, APP_NAME, 2048, NULL, 1, appStack, appTaskStruct); }这里APP_NAME宏定义为KVS-Test因此启动横幅打印出的正是Qorvo KVS-Test Launching。随后创建名为KVS-Test的 FreeRTOS 静态任务优先级为 1。2.3TestTask()每 60 秒运行一轮 KVS 测试void TestTask(void * pvParameter) { while (true) { qvCHIP_Printf(LOG_MODULE_ID, Running Tests:); chip::RunKvsTest(); vTaskDelay(60000); // Run every minute } }任务进入死循环每次调用共享的chip::RunKvsTest()后延时 60 秒再跑一轮。这意味着应用会周期性地、反复地执行全部 KVS 测试用例从而在设备长期运行过程中持续检验存储后端的稳定性与数据一致性——这对于排查 KVS 的写磨损、掉电一致性等问题非常有价值。三、按键与 LED本应用刻意保持无交互原文档在 Persistent-storage-app button control 与 LED output 两节中明确声明本应用不使用任何按键This application does not use any buttons本应用没有任何 LED 输出This application does not have any LED output。这是有意的设计取舍该示例的唯一职责是验证 KVS API刻意剥离了其他示例应用中常见的按键触发、LED 状态指示等外设交互逻辑使测试结果完全由串口日志呈现。对比仓库中其他示例如 lighting-app、lock-app 均包含按键与 LED 处理可以看出本示例是 KVS 验证场景下的最小化形态。因此评估该应用是否正常运行唯一可信的依据就是日志输出。四、核心 APIKeyValueStoreManager的 Put / Get / Delete示例应用使用的接口来自 Matter 平台抽象层chip::DeviceLayer::PersistedStorage::KeyValueStoreManager其完整声明位于 src/include/platform/KeyValueStoreManager.h。应用层通过全局单例访问函数KeyValueStoreMgr()获取接口实例。4.1Put写入或更新键值对CHIP_ERROR Put(const char * key, const void * value, size_t value_size);如果 key 已存在则覆盖旧值该接口还提供了模板重载Put(const char * key, const T value)自动推断类型大小要求T为平凡可复制类型trivially copyable且非指针源码中以static_assert强制约束见 KeyValueStoreManager.h。4.2Get读取键值CHIP_ERROR Get(const char * key, void * buffer, size_t buffer_size, size_t * read_bytes_size nullptr, size_t offset_bytes 0);支持从任意字节偏移offset_bytes开始读取若缓冲区过小返回CHIP_ERROR_BUFFER_TOO_SMALL并在read_bytes_size中返回已读字节数通常等于缓冲区大小同样提供模板重载Get(const char * key, T * value)按类型大小读取。4.3Delete删除键值对CHIP_ERROR Delete(const char * key);key 不存在时返回CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND。4.4 返回值错误码语义头文件注释明确了各接口的返回码含义这里汇总为表格便于对照测试代码理解返回码含义常见触发场景CHIP_NO_ERROR操作成功正常读写删CHIP_ERROR_PERSISTED_STORAGE_VALUE_NOT_FOUND键不存在Get/Delete访问未写入的 keyCHIP_ERROR_INTEGRITY_CHECK_FAILED数据校验失败数据损坏读到被破坏的条目或写入后校验失败CHIP_ERROR_BUFFER_TOO_SMALL缓冲区放不下整个值读取时缓冲区过小已写入尽可能多的字节CHIP_ERROR_UNINITIALIZEDKVS 尚未初始化底层存储未就绪时调用CHIP_ERROR_INVALID_ARGUMENT参数非法key 为空或过长、value 过大CHIP_ERROR_PERSISTED_STORAGE_FAILED底层写入/擦除失败存储介质写入错误4.5 QPG6200 平台实现平台侧实现位于 src/platform/qpg/KeyValueStoreManagerImpl.hclass KeyValueStoreManagerImpl final : public KeyValueStoreManager继承抽象接口实现_Get、_Put、_Delete三个私有方法并通过friend class KeyValueStoreManager让基类委托调用头文件注释特别说明当前该平台不支持部分读取与偏移读取partial and offset reads此类调用会返回CHIP_ERROR_NOT_IMPLEMENTED单例通过KeyValueStoreMgr()/KeyValueStoreMgrImpl()两个内联函数暴露KeyValueStoreManagerImpl.h底层实现直接调用 Qorvo SDK 的qvCHIP.h接口。这一平台差异是理解测试日志的重要背景TestMultiRead的偏移读取行为在不同平台上的表现可能不同为此共享测试框架专门提供了配置开关见下文。五、共享测试框架8 组用例逐行解读测试逻辑不放在平台目录内而是抽离到 examples/persistent-storage/KeyValueStorageTest.cpp 与 examples/persistent-storage/KeyValueStorageTest.h由各平台qpg、esp32、linux、infineon/psoc6 等共同复用。这也印证了原文档本示例用于在不同平台上验证 KVS 实现的定位。每个用例的返回值通过RUN_TEST宏统一处理成功打印PASSED失败打印FAILED [错误码]。测试入口为RunKvsTest(TestConfigurations test_config RUN_ALL_TESTS)枚举提供了RUN_ALL_TESTS与SKIP_MULTI_READ_TEST两个选项KeyValueStorageTest.h供不支持偏移读取的平台跳过TestMultiRead。用例函数源码位置验证要点TestEmptyString()KeyValueStorageTest.cpp#L50-L62空字符串值的写入、读取、删除闭环TestKeyExistence()KeyValueStorageTest.cpp#L64-L74用nullptr缓冲 0 长度探测 key 是否存在允许CHIP_NO_ERROR或CHIP_ERROR_BUFFER_TOO_SMALLTestString()KeyValueStorageTest.cpp#L76-L88普通字符串test_value的存取与内容比对TestUint32()KeyValueStorageTest.cpp#L90-L100uint32_t标量值为 5通过模板重载存取TestArray()KeyValueStorageTest.cpp#L102-L1125 元素uint32_t数组的memcmp全量比对TestStruct()KeyValueStorageTest.cpp#L114-L130自定义结构体uint8_t value1uint32_t value2逐字段比对TestUpdateValue()KeyValueStorageTest.cpp#L132-L144对同一 key 连续写入 0~9 并逐一读回验证覆盖更新语义TestMultiRead()KeyValueStorageTest.cpp#L146-L163按i * sizeof(uint32_t)偏移分段读取前 4 次应返回CHIP_ERROR_BUFFER_TOO_SMALL最后一次成功几个值得深入的技术细节偏移读取的语义验证TestMultiRead它把 5 个uint32_t的数组当作可分段读取的值每次只读取 4 字节。按 API 契约除最后一次外都应返回CHIP_ERROR_BUFFER_TOO_SMALL且read_size sizeof(read_value)同时读出的数值还必须与原始数组对应元素一致。这是对 KVS 偏移读取实现最严格的功能检验。存在性探测TestKeyExistence用Get(key, nullptr, 0)的方式只探测 key 是否存在而不读取数据验证实现能区分值恰好为空与键不存在两种情形。覆盖更新TestUpdateValue连续 10 次Put同一 key每次读回并断言相等用于暴露写入未真正落盘或读缓存未失效等实现缺陷。六、启动日志逐行解读原文档给出了应用启动后的完整日志。结合上文源码逐行解读如下qvCHIP v0.0.0.0 (CL:170621) r:3 Qorvo KVS-Test Launching Starting FreeRTOS scheduler Consistency fail - tag:20ef Consistency failed Running Tests: [P][-] TestEmptyString(): PASSED [P][-] TestString(): PASSED [P][-] TestUint32(): PASSED [P][-] TestArray(): PASSED [P][-] TestStruct(): PASSED [P][-] TestUpdateValue(): PASSED [P][-] TestMultiRead(): PASSED日志行来源与含义qvCHIP v0.0.0.0 (CL:170621) r:3Qorvo 协议栈qvCHIP的版本横幅由 SDK 内部在qvCHIP_init阶段打印/Qorvo KVS-Test Launching/应用启动横幅来自Application_Init()中的qvCHIP_PrintfAPP_NAME为KVS-TestStarting FreeRTOS schedulermain()调用vTaskStartScheduler()前打印Consistency fail - tag:20ef/Consistency failedQorvo KVS 后端在首次启动/空存储时的一致性检查输出属于该平台 KVS 初始化阶段的预期日志提示存储区域尚未包含有效数据或校验不一致例如全新 FlashRunning Tests:TestTask()每次循环开始时打印[P][-] TestXxx(): PASSEDRUN_TEST宏对每个用例的输出[P]表示进度Progress日志级别[-]为测试序号占位全部用例PASSED说明 KVS 后端通过了完整验证需要指出的是文档中记录的这段日志来自较早的构建当前共享测试代码 KeyValueStorageTest.cpp 的RunKvsTest()在TestEmptyString与TestString之间还包含TestKeyExistence()因此在新版本固件上运行时会额外看到[P][-] TestKeyExistence(): PASSED一行。若你的日志中缺少该行很可能是固件版本与当前源码不同步而非测试失败。此外QPG 平台实现不支持偏移读取返回CHIP_ERROR_NOT_IMPLEMENTED见 KeyValueStoreManagerImpl.h因此日志中出现TestMultiRead(): PASSED说明该平台版本已具备或已跳过该测试的支持路径——这正是TestConfigurations枚举中提供SKIP_MULTI_READ_TEST的原因各平台可根据后端能力选择是否执行。七、构建配置速览7.1 GN 构建目标BUILD.gn目标名persistent_storage_app输出名为chip-${qpg_target_ic}-persistent_storage-example.out源文件仅两个../KeyValueStorageTest.cpp共享测试代码与main.cpp通过qpg_sdk(sdk)引入src/platform/qpg与工程自身include目录include_dirs追加${qpg_project_dir}/..以便包含KeyValueStorageTest.h链接脚本使用 Qorvo SDK 的base_${qpg_target_ic}_development.ld即开发板基础链接脚本assert(current_os freertos)表明该工程仅面向 FreeRTOS 环境构建。7.2 GN 参数args.gnichip_enable_thread false、chip_openthread_ftd false本示例不启用 Threadchip_with_lwip false不依赖 lwIP 网络栈chip_system_config_use_openthread_inet_endpoints true系统层使用 OpenThread 的 inet 端点chip_stack_lock_tracking none由于该 FreeRTOS 配置未开启INCLUDE_xSemaphoreGetMutexHolder因此关闭栈锁跟踪避免编译/运行问题。7.3 工程配置include/CHIPProjectConfig.h测试 Setup PIN 码20202021、测试 Discriminator0xF00厂商 ID0xFFF1测试厂商、产品 ID0x8009persistent-storage 示例专用、硬件版本 1、软件版本字符串0.1ALPHA启用 CHIPoBLECHIP_DEVICE_CONFIG_ENABLE_CHIPOBLE 1与测试序列号TEST_SN安全测试模式保持关闭CHIP_CONFIG_SECURITY_TEST_MODE 0头文件注释明确警告该选项禁止在生产构建中启用。由于本示例不参与实际网络交互这些设备参数更多是保持与其他 Matter 示例的配置一致性真正核心的运行时行为仍集中在 KVS 测试任务上。八、总结与二次开发指引QPG6200 Persistent Storage Application 是一个以日志为唯一界面的 KVS 验证工程它通过TestTask每 60 秒循环执行 KeyValueStorageTest.cpp 中的 8 组用例覆盖空值、字符串、标量、数组、结构体、覆盖更新与偏移读取等关键场景任何一组返回失败都会以FAILED [错误码]形式呈现在串口日志中。如果你希望基于它做二次开发或验证可以按以下思路进行移植新平台实现src/platform/平台/KeyValueStorageManagerImpl.h中的_Put/_Get/_Delete复用本示例的main.cppKeyValueStorageTest.cpp组合即可获得开箱即用的验证环境适配偏移读取若后端支持偏移读取保持RUN_ALL_TESTS若不支持可在调用RunKvsTest()时传入SKIP_MULTI_READ_TEST参考 KeyValueStorageTest.h 的枚举定义排查失败用例结合上文错误码表格与各用例源码定位问题域——例如TestUpdateValue失败多与写入覆盖语义有关TestMultiRead失败多与偏移/长度处理有关理解底层实现QPG 平台的 KVS 直接构建于 Qorvo SDKqvCHIP.h之上更底层的 Flash 管理与一致性校验由 SDK 提供这正是启动日志中Consistency fail - tag:20ef的来源。作为 Matter 生态中验证基础设施性质的代表性示例它规模虽小却完整示范了平台抽象层接口 跨平台共享测试 平台特定实现这一 Matter 设备端代码组织的典型模式。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考