板卡移植

“换一块板”至少有三种不同工作。先判断属于哪一种，否则很容易为改一个 GPIO 复制出整套板卡文件。

情况	先做什么
上游已支持的板，应用想换引脚或停用外设	写应用 overlay / .conf
自己画的 PCB，SoC 已受 Zephyr 支持	新建板卡定义，复用 SoC、驱动
新 SoC 或没有驱动的外设	额外做 SoC 支持或驱动/binding，板卡文件不能代替它

ESP32-S3-Touch-LCD-1.28 属于第一种；自制 ESP32-S3 圆屏 PCB 通常属于第二种，但取决于器件是否已有驱动。

硬件信息

动代码前先记录：

芯片具体型号，Flash 大小/模式，PSRAM 类型/大小，晶振和电源条件。
下载接口、控制台 UART、BOOT/RESET 电路，下载与运行的启动引脚状态。
LCD 的控制器型号、SPI 总线、CS/DC/RESET/背光及有效电平。
触摸/传感器 I2C 地址、IRQ/RESET，引脚是否需要上拉。
哪些外设共享总线，哪些 GPIO 已被启动、存储器或其他功能占用。

例如“屏幕都是 240×240”不意味着驱动可通用。分辨率、控制器型号、初始化序列、像素顺序和引脚都是不同的信息。

板卡文件

在基线源码中查看：

cd ~/Projects/zephyr-main-workspace/zephyr
ls boards/waveshare/esp32s3_touch_lcd_1_28

这个版本采用当前硬件模型，主要文件为：

文件	作用	自制板要核对什么
board.yml	板卡名称、厂商、SoC 列表	新名称与真实芯片
Kconfig.板卡名	选择 SoC / CPU 相关符号	所选芯片和目标核
板卡_限定名.dts	内存、chosen、总线与器件	芯片容量、连接及设备状态
板卡-pinctrl.dtsi	外设信号到引脚的映射	每根信号与原理图一致
板卡_限定名_defconfig	基础软件配置	控制台、串口、GPIO 等基础支持
Kconfig.defconfig	带条件的板级默认值	硬件需要的默认值，非业务功能集合
Kconfig	额外板级配置规则，可选	没有需求就不额外添加
board.cmake	west flash/debug 的 runner	实际烧录器、调试器及参数
目标 .yaml、doc/	测试元数据与使用说明	板卡能力与验证记录

板卡 target 中的斜线在文件限定名中通常换成下划线。以本板为例：

target: esp32s3_touch_lcd_1_28/esp32s3/procpu
DTS:    esp32s3_touch_lcd_1_28_esp32s3_procpu.dts
默认值: esp32s3_touch_lcd_1_28_esp32s3_procpu_defconfig

不要混用其他 Zephyr 年代的 board Kconfig 模板。先读同一提交、同一 SoC 的一个板卡目录。

板卡目录

以下以尚不存在的 my_s3 为说明，不是可直接烧录到任意 ESP32-S3 PCB 的成品：

firmware/boards/mycompany/my_s3/
├── board.yml
├── Kconfig.my_s3
├── my_s3_esp32s3_procpu.dts
├── my_s3-pinctrl.dtsi
├── my_s3_esp32s3_procpu_defconfig
├── board.cmake
└── doc/index.rst

从相同 SoC 的受支持板卡参考实现开始，保留源文件许可/版权说明。改名不能只改目录：YAML 名称、Kconfig 符号、DTS include、CPU 限定名、默认配置文件名都要对应。

board.yml 的基本形式：

board:
  name: my_s3
  full_name: My ESP32-S3 Board
  vendor: mycompany
  socs:
    - name: esp32s3

Kconfig.my_s3 的主核选择示意：

config BOARD_MY_S3
    select SOC_ESP32S3
    select SOC_ESP32S3_PROCPU if BOARD_MY_S3_ESP32S3_PROCPU

这些是按本基线文件结构展示的片段，不是完整 BSP。厂商标识及提交上游所需元数据还应按目标版本规范检查。

设备树配置

首先只配置能启动、能看日志的部分：

引入正确的 SoC dtsi。
设置真实 Flash 容量与适用分区布局，不能照抄另一块板的 16 MB。
chosen 指定 SRAM、Flash、代码分区、console 等必要角色。
打开实际连接的 UART，配置波特率和 pinctrl。
核对 PSRAM；型号、模式和接线不明时不要直接启用。
先不加屏幕、触摸、Wi-Fi、LVGL，缩小初次失败范围。

UART 的形状例如：

/ {
    chosen {
        zephyr,console = &uart0;
        zephyr,shell-uart = &uart0;
    };
};

&uart0 {
    status = "okay";
    current-speed = <115200>;
    pinctrl-0 = <&uart0_default>;
    pinctrl-names = "default";
};

uart0_default 必须在 pinctrl 中实际定义，映射到 PCB 真实 UART 引脚。这段只展示 UART，省略的内存与分区配置必须从真实硬件补齐。

defconfig 的基础项可能包括：

CONFIG_GPIO=y
CONFIG_SERIAL=y
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y
CONFIG_CLOCK_CONTROL=y

并非所有 SoC 都需要完全相同的默认值，以同版本参考板和 Kconfig 依赖为准。应用中的 LOG、LVGL、网络业务配置仍留在 prj.conf。

BOARD_ROOT 配置

BOARD_ROOT 指向包含 boards 子目录的根目录。上述布局应传 firmware，不是 firmware/boards/mycompany/my_s3：

cd ~/Projects/embedded-workspace/zephyr
west build -p always -b my_s3/esp32s3/procpu samples/hello_world \
  -d ../build/my-s3-hello \
  -- -DBOARD_ROOT="$HOME/Projects/embedded-workspace/firmware"

命令仅在你已完成板卡文件之后执行。先确认日志选中了自己的 DTS，再检查 zephyr.dts 和 .config；如果仍显示微雪目标，当前并没有在验证新板。

也可以在应用 CMake 中、find_package 之前设置 BOARD_ROOT；初学先用命令行显式指定，减少隐藏条件。

硬件验证

阶段	做什么	失败时先看
1	Hello World，反复上电可启动	启动脚、Flash/分区、console 引脚与 runner
2	安全引脚 GPIO 输出，核对电平	有效电平、引脚复用、供电
3	单独测试 I2C/SPI 器件	总线地址、频率、CS/RESET、上拉
4	显示驱动测试，再接 LVGL	初始化序列、颜色格式、缓冲内存
5	加入触摸并核对坐标	IRQ、电平、坐标范围和旋转
6	增加网络、传感器和电源管理	内存/线程/时序及完整功能回归

移植完成不是“能编译”。至少记录实际板卡版本、Zephyr 提交、配置、串口日志和上电/复位行为。调试时不要同时换 SDK、上游提交、引脚和应用。

驱动与 SoC 支持

先找 compatible 对应的 binding，再找驱动实现。有 binding 不保证当前构建已启用驱动；没有 compatible 也不能随便写个名字就使用现有代码。

确实缺驱动时，通常需要 YAML binding 描述属性、驱动 C 实现 API、Kconfig 控制编译、CMakeLists 将驱动加入构建，以及 DTS 中的实例。放在自己的 Zephyr module 时还需模块发现配置。若 MCU 本身不受支持，还涉及启动、IRQ、时钟、内存与架构支持，工作量远大于本章的板级连接适配。

参考：官方板卡移植指南及本机同版本微雪板卡目录。

硬件信息​

板卡文件​

板卡目录​

设备树配置​

BOARD_ROOT 配置​

硬件验证​

驱动与 SoC 支持​