Matter Realtek FreeRTOS 平台适配指南：从 PlatformManager 到 BLE 的完整移植解析-迪斯科星球

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_FreeRTOS<PlatformManagerImpl>泛型基类（一个面向 FreeRTOS 的通用平台管理器实现），平台代码只需补齐少量定制逻辑。

2.2 关键源码实现

初始化_InitChipStack（PlatformManagerImpl.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_FreeRTOS<PlatformManagerImpl>::_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完成剩余初始化。

事件循环_RunEventLoop（PlatformManagerImpl.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_FreeRTOS<PlatformManagerImpl>::_RunEventLoop(); }

在启用 TrustZone 的芯片上，事件循环启动前会按 DAC 方案分配不同大小的安全上下文：使用 CG 安全 DAC Vendor 时为 2 KB，使用 RTK 加密 DAC 时为 8 KB。

关闭_Shutdown（PlatformManagerImpl.cpp）在停机前会读取诊断数据中的 uptime，将其折算为小时并累加到ConfigurationMgr的累计运行时长（TotalOperationalHours），随后委托泛型基类完成真正的关闭流程。

2.3 单例访问入口

头文件末尾提供两个内联访问函数（PlatformManagerImpl.h）：

PlatformMgr()：返回PlatformManager公共接口单例，供所有平台通用调用；
PlatformMgrImpl()：返回平台特有实现单例，供应用访问平台专属能力（如GetStartTime()）。

两者都指向静态实例PlatformManagerImpl::sInstance。

三、ConfigurationManagerImpl：持久化配置管理

3.1 职责与分层

ConfigurationManagerImpl.cpp 实现ConfigurationManager接口，负责：

设备持久化配置的存储与读取（重启次数、累计运行时长、BootReason 等）；
大部分 API 逻辑复用Internal::GenericConfigurationManagerImpl<RTKConfig>泛型类；
底层读写委托给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 工厂复位流程

DoFactoryReset（ConfigurationManagerImpl.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 的底层存储后端

RTKConfig（RTKConfig.cpp）是持久化配置的真正落地层，封装了平台提供的matter_kvs_*键值存储接口：

接口	封装函数	说明
`matter_kvs_init()`	`InitNamespace`	初始化 KVS 模块
`matter_kvs_get`	`ReadConfigValue`/`ReadConfigValueStr`/`ReadConfigValueBin`	读取 bool/uint32/uint64/字符串/二进制
`matter_kvs_put`	`WriteConfigValue`系列	写入各类值
`matter_kvs_key_delete`	`ClearConfigValue`	删除单个键
`matter_kvs_key_find`	`ConfigValueExists`	判断键是否存在
`matter_kvs_clean`	`ClearNamespace`	清空全部存储

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 与 ThreadStackManagerImpl

5.1 ConnectivityManagerImpl

ConnectivityManagerImpl.h 与 ConnectivityManagerImpl.cpp 实现ConnectivityManager接口，提供管理设备连接能力的高层 API，其主体逻辑复用GenericConnectivityManagerImpl_Thread<>泛型类。从 BUILD.gn 的依赖可见，chip_mdns = "platform"时平台会引入OpenThreadDnssdImpl，mDNS 也由 Thread 网络栈承载，这与 ConnectivityManager 对 Thread 连接状态的集中管理相辅相成。

5.2 ThreadStackManagerImpl

ThreadStackManagerImpl.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等配置直接约束了网络栈能力范围。

六、BLEManagerImpl：BLE 能力适配

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_VENDOR=1并影响 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与底层存储后端（对应RTKConfig+matter_kvs_*），并规划好chip-factory/chip-config/chip-counters等命名空间；
按连接技术选择实现ConnectivityManagerImpl与ThreadStackManagerImpl（OpenThread/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 强调"这段代码的大部分在任何新适配中都有对应物"的原因所在。

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

企业官网建设流程全解析