从旧版教程迁移

本页依据 文档基线与后续更新 中记录的 Zephyr main 快照更新。

仓库原有教程多以 2021—2022 年源码和工具环境为背景。 升级应先选定 Zephyr 目标版本，再读取每个跨越版本的官方迁移指南， 不能一次替换几个头文件就认为已完成迁移。

环境与工作区

  1. 用 Python 虚拟环境安装当前版本所需依赖；本次基线要求 Python 3.12。

  2. 获取目标 Zephyr 修订版后执行 west update，使模块与清单一致。

  3. 按目标版本安装 Python 依赖与 SDK。

  4. 用当前完整 board target 重新构建，清理旧 CMake 缓存。

  5. 在真实硬件验证外设、存储、镜像布局和协议行为。

常见变化

早期教程内容

当前处理方式

本地说明

系统 Python 安装、Python 3.6

虚拟环境；核对当前最低版本

搭建开发环境并运行第一个应用

Windows 旧 Chocolatey/MSYS2 拼装流程

官方 winget 与 SDK 流程

Windows 原生开发环境

SDK 只支持 Linux

按主机平台安装兼容 SDK

搭建开发环境并运行第一个应用

west init --mr v2.5.0

明确选择发布标签或提交号

工作区、清单与版本更新

nrf52840dk_nrf52840 等旧板名

查当前硬件模型的完整目标

应用构建、Kconfig 与 Devicetree

<kernel.h>、<logging/log.h> 等路径

使用 <zephyr/...> 命名空间

内核

<zephyr/fs/nvs.h> 与 subsys/fs/nvs

新头文件 <zephyr/kvss/nvs.h> 与 subsys/kvss/nvs

NVS 非易失键值存储

FIXED_PARTITION_*

当前 PARTITION_* 公共宏

Flash Map 与分区

k_pipe_put/get 的输出长度与 min_xfer

k_pipe_write/read 返回实际长度，处理部分传输

管道：字节流与新版 API

wait 后手动 clear 事件

需要消费时考虑 k_event_wait_safe 等接口

事件对象

CONFIG_NUM_MBOX_ASYNC_MSGS=y

它是整数容量；结合资源池设计流控

邮箱

旧日志引擎与 log_strdup

当前 logger 打包机制与日志模式选项

日志系统使用指南

写完流后继续使用已 flush 上下文

flush 结束会话，后续会话重新初始化

Stream Flash 流式写入

存储格式是单独的迁移任务

固件能重新编译不表示旧数据一定兼容。分区地址、sector 数量、写块大小、数据 CRC、 ID 含义以及应用结构体布局发生变化，都要确认已有设备的数据迁移策略。 不要在挂载失败时直接清空存储作为通用升级方案。

本次更新采用官网 latest 的固定源码快照。NVS 头文件和分区宏等近期变化，在较早 稳定版本中可能不存在；维护发布版应用时，应按对应版本头文件选择接口。

上游迁移入口

查看 发布说明目录 中各版本的 Migration Guide。管道重写的跨版本背景见 4.1 迁移指南；最新分支上的声明以本次固定提交为准。

上游依据