📚 课程目录第3章 Matter协议栈在nRF54上的移植与构建

3. Matter协议栈在nRF54上的移植与构建

Matter 在 nRF54 系列上的落地，本质上是把三块内容拼装成一个可烧录的固件：Nordic 提供的 nRF Connect SDK（NCS，基于 Zephyr RTOS）、上游 connectedhomeip 的 CHIP 协议栈，以及应用自身的 Matter 设备逻辑。nRF54 属于较新的平台，其 SoC 支持、外设驱动与低功耗特性主要由 NCS 侧提供，因此工程上通常不采用“裸 CHIP + 自建 RTOS”的方式，而是以 NCS 为宿主，把 CHIP 作为 Zephyr 模块（module）集成进来。理解这条集成路径，比记住某条命令更重要。

一、整体集成结构：谁依赖谁

NCS 的构建体系是 Zephyr 的 west + CMake + Kconfig 三层结构。CHIP 以 west module 的形式被引入，通过 west.yml 的 manifest 声明仓库与版本；Zephyr 的模块机制在配置阶段把 CHIP 的 CMake 文件纳入构建，CHIP 再通过 Kconfig 选项决定启用哪些集群、哪些传输（Thread/Wi-Fi）、是否启用 Matter 认证所需的测试能力。应用层则通过 CONFIG_CHIP_* 与 CONFIG_OPENTHREAD_* 等选项，把设备类型、配网方式、线程角色固定下来。

二、CHIP 库集成：manifest 与模块声明

在 NCS 工程中，CHIP 不是通过 git clone 手动放进 modules/ 就完事，而是通过 west manifest 管理。典型做法是在应用目录下维护一个 west.yml，把 connectedhomeip 作为额外 project 加入，并锁定到与当前 NCS 版本兼容的 tag 或 commit。例如 NCS v2.7 对应的 CHIP 版本通常需要参考 Nordic 的 release note，不能随意取 main 分支，否则 Zephyr API 变更会导致编译失败。

manifest:
  remotes:
    - name: ncs
      url-base: https://github.com/nrfconnect
    - name: project-chip
      url-base: https://github.com/project-chip
  projects:
    - name: nrf
      remote: ncs
      revision: v2.7.0
    - name: connectedhomeip
      remote: project-chip
      revision: v1.3.0.0
      path: modules/lib/connectedhomeip
  self:
    path: app

执行 west update 后，CHIP 会被拉到 modules/lib/connectedhomeip。此时 Zephyr 的模块发现机制会读取该目录下的 zephyr/module.yml，把 CHIP 的 CMake 与 Kconfig 接入构建。若该文件缺失或路径不对，构建阶段会出现“找不到 chip 目标”的错误，这是集成中最常见的第一个坑。

三、Zephyr RTOS 配置：Kconfig 与 devicetree

配置分两层：Kconfig 决定“编译什么功能”，devicetree overlay 决定“硬件怎么接”。对于 Matter over Thread 的 nRF54 设备，核心配置项如下（示例值，需按实际板型调整）：

# prj.conf
CONFIG_CHIP=y
CONFIG_CHIP_ENABLE_APP_SIGNATURE_VERIFICATION=y
CONFIG_CHIP_DEVICE_PRODUCT_ID=0x8000
CONFIG_CHIP_DEVICE_VENDOR_ID=0x1234
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=1
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION_STRING="1.0.0"

CONFIG_NETWORKING=y
CONFIG_NET_IPV6=y
CONFIG_OPENTHREAD=y
CONFIG_OPENTHREAD_MTD=y
CONFIG_OPENTHREAD_FTD=n
CONFIG_OPENTHREAD_SHELL=y

CONFIG_CHIP_ENABLE_SLEEPY_END_DEVICE_SUPPORT=y
CONFIG_CHIP_SED_POLL_INTERVAL=500

CONFIG_MCUBOOT=y
CONFIG_BOOTLOADER_MCUBOOT=y
CONFIG_CHIP_OTA_REQUESTOR=y

其中 CONFIG_OPENTHREAD_MTD 表示最小线程设备，适合电池供电的传感器；若设备需要做 Thread 路由器，则改为 CONFIG_OPENTHREAD_FTD=y。Sleepy End Device 的 poll interval 直接影响功耗与响应延迟，500 ms 是常见折中值，但认证测试中若对响应时间有要求，需要重新评估。

devicetree overlay 主要处理 nRF54 的射频与天线控制。例如 nrf54l15dk_nrf54l15_cpuapp.overlay 中需要确认 &radio 节点使能、status = "okay"，并检查 zephyr,ieee802154 是否指向正确的射频实例。若使用外部天线，还需配置 nordic,antenna 相关属性。这些内容不写进 Kconfig，而是通过 overlay 在编译期注入。

四、构建与烧录：从 west build 到设备启动

构建命令通常如下，注意 -b 指定板型，--sysbuild 用于同时构建 MCUboot 与应用镜像：

west build -b nrf54l15dk/nrf54l15/cpuapp \
  --sysbuild \
  -d build_matter_light \
  -- -DCONF_FILE="prj.conf;overlay-matter.conf"

构建完成后，产物位于 build_matter_light/ 下。若启用了 sysbuild，会生成 mcuboot/zephyr/zephyr.hex 与 matter_light/zephyr/zephyr.hex，以及合并后的 merged.hex。烧录时推荐直接烧 merged.hex，避免引导区与应用的地址冲突：

west flash -d build_matter_light --erase

烧录后通过 RTT 或 UART 查看日志。正常启动会看到 OpenThread 初始化、Matter 栈启动、以及设备进入配网广播状态。若日志停在 CHIP: Transport: Failed to initialize，通常说明 Thread 网络接口未就绪或射频未使能，应回到 devicetree overlay 检查 radio 节点状态。

nRF54 的加密加速单元（CryptoCell）在 CHIP 的 PASE/CASE 会话建立中会被调用。若构建时未启用 CONFIG_NRF_SECURITY 或 CONFIG_PSA_CRYPTO，配网阶段可能出现会话建立超时。建议在 prj.conf 中显式打开 PSA 加密后端。

五、常见集成问题与判断依据

移植过程中最值得关注的不是“能不能编译”，而是“编译出来的固件行为是否符合 Matter 规范”。以下三个判断点可以作为检查依据：第一，设备能否在 15 秒内完成 BLE 配网并切换到 Thread；第二，配网后能否被 Matter 控制器（如 chip-tool）发现并读取 Basic Information 集群；第三，OTA 请求器是否能在收到查询镜像请求后正确上报软件版本。若第二点失败但第一点成功，问题通常出在 Thread 网络参数或 SRP 注册，而非 CHIP 本身。

另外，nRF54 的 flash 分区需要与 MCUboot 的 slot 布局对齐。若 CONFIG_CHIP_OTA_REQUESTOR 启用但分区表未预留 secondary slot，OTA 会在下载阶段失败。建议在 pm_static.yml 中明确 mcuboot、slot0_partition、slot1_partition 与 factory_data 的地址和大小，并在构建后通过 west build -t partition_manager_report 核对。

把以上环节串起来，nRF54 上的 Matter 移植可以概括为：用 west manifest 锁定 CHIP 版本，用 Kconfig 裁剪协议栈与 Thread 角色，用 devicetree overlay 对接 nRF54 射频，用 sysbuild 生成可烧录的合并镜像，最后以配网、集群读取和 OTA 三个行为作为验收依据。每一步的输入与输出都可在构建目录和 RTT 日志中找到对应证据，而不是靠“感觉能跑”。