Matter Realtek FreeRTOS 平台适配指南从 PlatformManager 到 BLE 的完整移植解析【免费下载链接】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本指南以 src/platform/realtek/freertos/README.md 为主线系统讲解 Matter SDK 在 Realtek Bee 平台FreeRTOS 环境上的平台适配Platform Adaptation架构。读者将掌握 PlatformManager、ConfigurationManager、ConnectivityManager、ThreadStackManager、BLEManager 等核心接口的具体落地方式理解通用实现基类 平台定制实现的移植范式并能在自己平台的新适配中复用同样的结构。一、适配层的定位与整体结构在 Matter原 Project CHIP中src/platform下的 Device Layer 将上层协议与底层芯片平台解耦。任何新平台都需要实现一组 Manager 接口PlatformManager、ConfigurationManager、ConnectivityManager、ThreadStackManager、BLEManager 等并辅以熵源、日志、时钟等基础能力。Realtek Bee 平台的 FreeRTOS 移植正是这套范式的完整样例正如 README 开头所述Most of this code will have parallels in any new adaptation这段代码的大部分在任何新适配中都能找到对应物。所有实现文件均位于src/platform/realtek/freertos/目录其内部文件组织如下src/platform/realtek/freertos/ ├── PlatformManagerImpl.{h,cpp} # 平台生命周期与事件循环 ├── ConfigurationManagerImpl.{h,cpp} # 持久化配置管理 ├── ConnectivityManagerImpl.{h,cpp} # 连接状态管理 ├── ThreadStackManagerImpl.{h,cpp} # Thread 协议栈管理 ├── BLEManagerImpl.{h,cpp} # BLE 适配 ├── RTKConfig.{h,cpp} # 底层 KVS 读写底层存储引擎 ├── Logging.cpp # 日志适配 ├── FactoryDataProvider/Decoder # 工厂数据 ├── OTAImageProcessorImpl.{h,cpp} # OTA 镜像处理 ├── KeyValueStoreManagerImpl.{h,cpp} # KVS 管理器 ├── DiagnosticDataProviderImpl.{h,cpp} # 诊断数据 └── SystemTimeSupport.{h,cpp} # 系统时间从 BUILD.gn 的static_library(freertos)目标可以看出这些文件被统一编译进平台库当chip_enable_thread开启时还会额外加入GenericNetworkCommissioningThreadDriver、OpenThreadDnssdImpl等 OpenThread 相关源文件并将 Thread 相关平台文件纳入构建。二、PlatformManagerImpl平台初始化与核心事件循环2.1 职责PlatformManagerImpl.h 与 PlatformManagerImpl.cpp 是PlatformManager接口的具体实现负责CHIP 协议栈的初始化_InitChipStack为 chip 任务提供核心事件循环_RunEventLoop应用级启动时间的记录GetStartTime。其实现绝大部分复用Internal::GenericPlatformManagerImpl_FreeRTOSPlatformManagerImpl泛型基类一个面向 FreeRTOS 的通用平台管理器实现平台代码只需补齐少量定制逻辑。2.2 关键源码实现初始化_InitChipStackPlatformManagerImpl.cpp展示了一条典型的平台初始化链路CHIP_ERROR PlatformManagerImpl::_InitChipStack(void) { err System::Clock::InitClock_RealTime(); // 初始化实时时钟 SuccessOrExit(err); #if CHIP_SYSTEM_CONFIG_USE_LWIP tcpip_init(NULL, NULL); // 初始化 LwIP 协议栈 #endif chip::Crypto::add_entropy_source(app_entropy_source, NULL, 1); // 注册熵源 err Internal::GenericPlatformManagerImpl_FreeRTOSPlatformManagerImpl::_InitChipStack(); ... }System::Clock::InitClock_RealTime()建立系统时钟与实时时间基准在启用 LwIP 时调用tcpip_init启动 TCP/IP 协议栈注意 Realtek 平台的lwip_platform external即使用平台外部集成的 LwIP见 args.gni通过chip::Crypto::add_entropy_source(app_entropy_source, NULL, 1)将平台熵源注册进 CHIP 加密层最后调用泛型基类的_InitChipStack完成剩余初始化。事件循环_RunEventLoopPlatformManagerImpl.h展示了 TrustZone 安全上下文的处理inline void PlatformManagerImpl::_RunEventLoop(void) { #if defined(FEATURE_TRUSTZONE_ENABLE) (FEATURE_TRUSTZONE_ENABLE 1) #if CONFIG_USE_CG_SECURE_DAC_VENDOR constexpr size_t kPlatformManagerSecureContextSize 2 * 1024; #else // RTK Encrypt DAC constexpr size_t kPlatformManagerSecureContextSize 8 * 1024; #endif os_alloc_secure_ctx(kPlatformManagerSecureContextSize); #endif Internal::GenericPlatformManagerImpl_FreeRTOSPlatformManagerImpl::_RunEventLoop(); }在启用 TrustZone 的芯片上事件循环启动前会按 DAC 方案分配不同大小的安全上下文使用 CG 安全 DAC Vendor 时为 2 KB使用 RTK 加密 DAC 时为 8 KB。关闭_ShutdownPlatformManagerImpl.cpp在停机前会读取诊断数据中的 uptime将其折算为小时并累加到ConfigurationMgr的累计运行时长TotalOperationalHours随后委托泛型基类完成真正的关闭流程。2.3 单例访问入口头文件末尾提供两个内联访问函数PlatformManagerImpl.hPlatformMgr()返回PlatformManager公共接口单例供所有平台通用调用PlatformMgrImpl()返回平台特有实现单例供应用访问平台专属能力如GetStartTime()。两者都指向静态实例PlatformManagerImpl::sInstance。三、ConfigurationManagerImpl持久化配置管理3.1 职责与分层ConfigurationManagerImpl.cpp 实现ConfigurationManager接口负责设备持久化配置的存储与读取重启次数、累计运行时长、BootReason 等大部分 API 逻辑复用Internal::GenericConfigurationManagerImplRTKConfig泛型类底层读写委托给RTKConfig类README 中提到的 NRF5Config 实为历史遗留笔误当前代码实际引用的是RTKConfig。这一接口 泛型实现 平台存储后端的三层结构是 ConfigurationManager 移植的通用模式上层逻辑在GenericConfigurationManagerImpl中完成平台只需实现RTKConfig的ReadConfigValue/WriteConfigValue系列原语。3.2 初始化与计数器维护Init()ConfigurationManagerImpl.cpp的执行流程调用RTKConfig::InitNamespace()强制初始化 KVS 命名空间若已存在kCounterKey_RebootCount键则读取后自增 1 再写回否则视为出厂后首次启动将重启计数初始化为 1若不存在kCounterKey_TotalOperationalHours初始化为 0若不存在kCounterKey_BootReason初始化为BootReasonType::kUnspecified调用泛型基类的Init()完成其余初始化。3.3 工厂复位流程DoFactoryResetConfigurationManagerImpl.cpp通过PlatformMgr().ScheduleWork(DoFactoryReset)调度执行其动作包括调用RTKConfig::ClearNamespace()擦除chip-config等命名空间内的全部配置在启用 Thread 时调用ThreadStackMgr().ClearAllSrpHostAndServices()清理 SRP 注册并调用ThreadStackMgr().ErasePersistentInfo()擦除 Thread 入网信息最后调用WDG_SystemReset(RESET_ALL, RESET_REASON_FACTORY_RESET)复位系统。四、RTKConfig基于 matter_kvs 的底层存储后端RTKConfigRTKConfig.cpp是持久化配置的真正落地层封装了平台提供的matter_kvs_*键值存储接口接口封装函数说明matter_kvs_init()InitNamespace初始化 KVS 模块matter_kvs_getReadConfigValue/ReadConfigValueStr/ReadConfigValueBin读取 bool/uint32/uint64/字符串/二进制matter_kvs_putWriteConfigValue系列写入各类值matter_kvs_key_deleteClearConfigValue删除单个键matter_kvs_key_findConfigValueExists判断键是否存在matter_kvs_cleanClearNamespace清空全部存储4.1 三个命名空间源码中以改变这些名称/命名空间将破坏既有设备的醒目注释RTKConfig.cpp定义了三个 KVS 命名空间chip-factory存放出厂数据如序列号serial-num、制造商设备 IDdevice-id、设备证书device-cert、中间 CA 证书device-ca-certs、设备私钥device-key、硬件版本hardware-ver、生产日期mfg-date、配对 PIN 码pin-code、配对 Discriminatordiscriminator、SPAKE2 迭代次数/盐/验证器、UniqueId 等chip-config存放运行时配置如服务配置service-config、配对账户 IDaccount-id、操作证书op-device-cert与私钥op-device-key、国家码country-code、监管位置regulatory-location、FailSafe 状态等chip-counters存放计数器如重启计数reboot-count、运行时长up-time、累计运行小时total-hours、启动原因boot-reason。ConfigurationManagerImpl的持久化存储读写ReadPersistedStorageValue/WritePersistedStorageValue也会映射到chip-counters命名空间下的对应键ConfigurationManagerImpl.cpp。五、ConnectivityManagerImpl 与 ThreadStackManagerImpl5.1 ConnectivityManagerImplConnectivityManagerImpl.h 与 ConnectivityManagerImpl.cpp 实现ConnectivityManager接口提供管理设备连接能力的高层 API其主体逻辑复用GenericConnectivityManagerImpl_Thread泛型类。从 BUILD.gn 的依赖可见chip_mdns platform时平台会引入OpenThreadDnssdImplmDNS 也由 Thread 网络栈承载这与 ConnectivityManager 对 Thread 连接状态的集中管理相辅相成。5.2 ThreadStackManagerImplThreadStackManagerImpl.h 与 ThreadStackManagerImpl.cpp 实现ThreadStackManager接口支持 Thread 协议栈初始化与核心事件循环处理复用GenericThreadStackManagerImpl_OpenThread/_FreeRTOS/_LwIP三套泛型基类组合实现大部分 API。头文件中还声明了int GetEntropy(uint8_t * buf, size_t bufSize)函数并设为Internal::GetEntropy的友元用于向 OpenThread 提供熵源。若平台通过 Thread而非 Wi-Fi接入 Matter 网络args.gni 中chip_inet_config_enable_ipv4 false、chip_inet_config_enable_tcp_endpoint false等配置直接约束了网络栈能力范围。六、BLEManagerImplBLE 能力适配BLEManagerImpl.h 与 BLEManagerImpl.cpp 实现BLEManager接口是 Matter 设备配对commissioning阶段的重要通道。其核心职责将 CHIP 的 BLE 接口抽象BleLayer、BlePlatformDelegate、BleApplicationDelegate映射到平台的本地 BLE 服务基于平台 BLE 协议栈实现 CHIP 兼容的 BLE 广播advertising与 GATT 服务。注README 中提到的 Softdevice BLE stack 沿用了参考模板的描述Realtek 平台实际基于自身 BLE 协议栈具体接入实现见上述文件。配对时BLE 广播中携带的发现信息与 RTKConfig.cpp 中chip-factory命名空间的pin-code、discriminator等出厂参数共同决定了设备可被发现与配对的形态。此外BUILD.gn 中的chip_use_cg_secure_dac_vendor参数可切换 DAC Vendor Provider 实现RTK/RTKDACVendorProvider或CG/CGSecureDACVendorProvider后者会定义CONFIG_USE_CG_SECURE_DAC_VENDOR1并影响 PlatformManagerImpl.h 中 TrustZone 安全上下文的分配大小。七、基础支撑熵源、日志与配置头文件7.1 Entropy 熵源README 中提到的Entropy.cpp实现平台熵源接口。在现版本中该能力已并入 PlatformManagerImpl.cpp 的初始化流程通过chip::Crypto::add_entropy_source(app_entropy_source, NULL, 1)注册平台熵源app_entropy_source由平台 SDK 提供供 CHIP 加密层如 SPAKE2、证书签名取用随机数同时 ThreadStackManagerImpl.h 的GetEntropy为 OpenThread 提供同一熵源保证整个系统随机性的单一来源。7.2 Logging 日志适配Logging.cpp 将 CHIP 调试日志ChipLogError/ChipLogProgress等宏适配到平台日志设施。在 BUILD.gn 中它被独立编译为source_set(logging)仅依赖platform_base与日志头文件可被其他模块按需引用。7.3 平台配置头文件freertos目录下的一组*PlatformConfig.h/CHIPPlatformConfig.h头文件如 CHIPPlatformConfig.h、CHIPDevicePlatformConfig.h、InetPlatformConfig.h、SystemPlatformConfig.h、BlePlatformConfig.h分别定义了平台级功能开关、BLE/Thread 能力、内存布局等宏是整个适配层的编译期配置面也是新平台移植时最先需要调整的文件。八、构建与移植要点8.1 平台构建配置args.gni 定义了 Realtek Bee 平台的关键 GN 参数chip_device_platform realtek_bee # 平台标识 chip_mdns platform # mDNS 由平台承载OpenThread lwip_platform external # LwIP 使用平台外部集成版本 lwip_debug false chip_inet_config_enable_ipv4 false # 禁用 IPv4 chip_inet_config_enable_tcp_endpoint false # 禁用 TCP 端点 chip_build_tests false其中chip_device_platform realtek_bee与 BUILD.gn 顶部的assert(chip_device_platform realtek_bee)呼应确保该平台库只在正确的平台配置下被编译。8.2 新平台适配的通用参考结合 README 的指引与上述源码分析任何新平台如新的 FreeRTOS 芯片适配 Matter 时可参照此结构逐项落地实现PlatformManagerImpl复用GenericPlatformManagerImpl_FreeRTOS补齐_InitChipStack时钟、网络栈、熵源注册与事件循环实现ConfigurationManagerImpl与底层存储后端对应RTKConfigmatter_kvs_*并规划好chip-factory/chip-config/chip-counters等命名空间按连接技术选择实现ConnectivityManagerImpl与ThreadStackManagerImplOpenThread/FreeRTOS/LwIP 组合实现BLEManagerImpl将 CHIP 的 BleLayer 抽象映射到平台 BLE 协议栈补充熵源、日志、时间等基础能力并在args.gni/BUILD.gn中声明平台构建参数。九、总结Realtek Bee 平台在 FreeRTOS 上的 Matter 适配完整呈现了 Device Layer 的移植范式平台差异被收敛到*Impl具体类中通用逻辑全部由Generic*Impl泛型基类承载底层能力由RTKConfig、熵源、日志等小模块兜底。理解这套src/platform/realtek/freertos/下的代码结构等于掌握了一把开启任意新平台 Matter 移植的钥匙——这也是 README 强调这段代码的大部分在任何新适配中都有对应物的原因所在。【免费下载链接】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），仅供参考