03 · 微雪板卡 Hello World 验证
用户已确认现已换成 ESP32-S3-Touch-LCD-1.28，继续使用本页 Touch 目标。之前提供的无 Touch 板资料不适用于背光和显示引脚。更换物理板卡后，旧板的烧录成功记录不代表新板已写入程序。
目标板：Waveshare ESP32-S3-Touch-LCD-1.28。本页取代原来的 DevKitC 操作步骤。
本页使用的 samples/hello_world 是应用工程，板卡硬件定义仍来自 Zephyr 的 boards/waveshare/esp32s3_touch_lcd_1_28/。-b esp32s3_touch_lcd_1_28/esp32s3/procpu 选择板卡目标，-d build/waveshare-hello 保存该应用的独立构建产物；构建完成后只烧录这个目录中的 zephyr/zephyr.bin。
2026-09-18 已在官方 main（提交 52b48529aec，版本 4.4.99）完成该板目标的编译验证；实板此前已用 v4.2.0 验证启动。main 固件可使用同样的串口流程烧录验证。
1. 关机后重新进入环境
source ~/Projects/zephyr-main-workspace/.venv-py312-main/bin/activate
export ZEPHYR_SDK_INSTALL_DIR=~/.local/opt/zephyr-sdk-1.0.1
cd ~/Projects/zephyr-main-workspace/zephyr
python --version
west --version
git describe --tags --always
预期分别为 Python 3.12.14、west 1.5.0、v4.2.0。每个新终端都需要激活一次；源码、依赖与 SDK 不需要重新安装。
2. 编译本板固件
west build -p always -b esp32s3_touch_lcd_1_28/esp32s3/procpu \
samples/hello_world -d build/waveshare-hello-main
-p always 清理的是指定构建目录的旧产物。成功后生成：
build/waveshare-hello-main/zephyr/zephyr.elf
build/waveshare-hello-main/zephyr/zephyr.bin
本板默认使用 Simple boot，本次不启用 sysbuild / MCUboot。已编译过且未修改代码时，直接进行下一步即可。
3. 确认 USB 串口
用支持数据传输的 Type-C 线连接板卡。此板接口通过 CH343P 连接 UART0，不需要为这个 Hello World 额外配置 USB CDC。
ls -l /dev/serial/by-id/
python -m serial.tools.list_ports -v
根据插拔前后变化确认本板对应设备，记录稳定的 by-id 路径。不要照抄他人的 /dev/ttyUSB0；没有 by-id 时，以串口枚举输出为准。
本机已确认的串口权限问题
2026-09-18 在宿主机确认板卡枚举为 /dev/ttyACM0，设备属组为 dialout、权限为 0660；当前 fedora 会话不在 dialout 组。实际烧录错误为 Permission denied，不是固件编译失败。
在自己的终端执行一次：
sudo usermod -aG dialout fedora
newgrp dialout
第一条修改组成员，第二条进入使用新组的子 shell；执行后继续在这个子 shell 中操作。也可退出桌面登录后重新登录，让整个会话生效。仅开一个继承旧桌面会话的新终端不一定生效。
id -nG
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
确认 id -nG 包含 dialout 后再烧录。上面的用户名只适用于本机 fedora；其他电脑按实际用户名和串口属组调整。不需要 sudo west 或 chmod 777。
4. 烧录
本板已验证的最短流程
下面第一条 cd 很重要：west flash -d build/waveshare-hello 要从 Zephyr 源码目录执行；进入构建目录后再执行会把路径重复成 build/waveshare-hello/build/waveshare-hello。
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
west flash -d build/waveshare-hello-main --esp-device /dev/ttyACM0
cd build/waveshare-hello
west espressif monitor -p /dev/ttyACM0 -b 115200
--esp-device /dev/ttyACM0 必须保持在同一行。不要写成 --esp- 换行再写 device；Shell 会把它拆成错误参数。
烧录将替换板上当前演示固件。确认只连接目标实验板后，从 Zephyr 源码目录执行：
west flash -d build/waveshare-hello
多串口或自动识别失败时先查看 runner 帮助：
west flash -d build/waveshare-hello -H
本版本 ESP32 runner 使用 --esp-device 指定串口。下面一行需要把占位路径改为上一步查到的实际设备：
west flash -d build/waveshare-hello --esp-device /dev/serial/by-id/替换为实际设备
正常情况下不需要按 BOOT：west flash 会通过 CH343P 的 DTR/RTS 自动进入下载模式。只有自动下载失败时，才按住 BOOT、按一下 RESET、松开 BOOT 后重试。烧录完成后必须确认 BOOT 已松开，否则复位时会再次进入 DOWNLOAD(USB/UART0)。Permission denied 时看串口排错，不要用 sudo 运行整套 west。
5. 查看串口并复位
关闭其他占用端口的软件，进入这个构建目录：
cd ~/Projects/zephyr-main-workspace/zephyr/build/waveshare-hello-main
west espressif monitor -p /dev/ttyACM0 -b 115200
如果设备名不是 /dev/ttyACM0，替换 -p 后面的路径；也可以使用稳定的 by-id 路径：
west espressif monitor -p /dev/serial/by-id/替换为实际设备 -b 115200
监视器就绪后按 RESET，BOOT 保持松开，观察启动输出。退出使用 Ctrl+]。此扩展的 -d 是地址解码开关，不是构建目录参数。
预期输出包含（示意，版本后缀可变化）：
*** Booting Zephyr OS ... ***
Hello World! esp32s3_touch_lcd_1_28/esp32s3/procpu
本例只向串口打印一次，不会在圆屏上显示 Hello World。没有输出先检查串口、波特率与复位时机，不要把黑屏当作固件失败。
若停在 waiting for download
用户曾实测烧录日志已出现 Hash of data verified，随后一度看到 boot:0x10 (DOWNLOAD(USB/UART0))、waiting for download。这表示当时 ROM 处于下载模式，尚未执行 Flash 中的 Hello World。
先用 Ctrl+] 退出现有监视器，确认 BOOT 完全松开。使用显式释放 DTR / RTS 的串口终端排除自动复位线影响：
python -m serial.tools.miniterm --dtr 0 --rts 0 /dev/ttyACM0 115200
打开后只按一下 RESET，不要按 BOOT。预期启动模式变为 SPI_FAST_FLASH_BOOT，随后检查 Zephyr / Hello World 输出。退出仍用 Ctrl+]。
若仍显示 DOWNLOAD，下一步检查 BOOT 是否卡住及 GPIO0 是否被外部接线拉低；本次实测已经变为 SPI 启动并成功运行，因此不需要额外烧录 bootloader。
6. 记录结果
- 串口确认来自该板 CH343P。
- 编译和烧录命令成功。
- RESET 后收到 Hello World。
- 在实验手记保存实际日志。
下一步：背光亮灭与分级调光。
官方来源
是否需要额外烧录 bootloader
本机生成配置明确为 CONFIG_ESP_SIMPLE_BOOT=y，板卡官方 v4.2.0 文档说明这种模式使用单一镜像，不需要额外二级 bootloader。通过 west 将当前 zephyr.bin 写入 0x0 即可；不要混入 Arduino / ESP-IDF 的 bootloader 或分区表。
boot:0x10 与 boot:0x30 后都显示 DOWNLOAD 时，都尚未尝试 Flash 启动，不能据此判断是否缺少固件。先排查 GPIO0 / BOOT 和复位控制线。对于 Linux 串口，还可在退出监视器后检查关闭 HUPCL 与硬件流控的影响：
stty -F /dev/ttyACM0 -hupcl -crtscts
python -m serial.tools.miniterm --dtr 0 --rts 0 /dev/ttyACM0 115200
打开后仅按 RESET，BOOT 保持松开。这是排查步骤，尚未确认能解决该实板问题；若仍停在 DOWNLOAD，需确认实际按键/接线照片，或由有条件的用户测量 GPIO0 在复位时是否保持高电平。不要未经确认就短接引脚。
根据 Touch 原理图继续检查
微雪资料页同时列出原版和 Rev3 原理图。已核对的 Rev3 原理图中，Key1 将 GPIO0 拉到地，Key2 将 RESET 拉到地；CH343P 的 DTR / RTS 通过双三极管连接这两条信号。因此按键、外接线路和自动下载电路都需要考虑，不能仅凭 DOWNLOAD 日志确定是哪一个导致。
若前面的 miniterm 检查仍停在下载模式，退出所有串口监视器，BOOT 保持松开，运行下面的检查脚本。它不写 Flash，在同一个串口连接内释放 BOOT、脉冲复位并读取 10 秒日志，避免在复位与读取之间重新打开端口。
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
python ~/Projects/zephyr-docs/scripts/serial-boot-check.py /dev/ttyACM0
- 出现
SPI_FAST_FLASH_BOOT：已进入 Flash 启动，继续检查后面的 Zephyr 输出或具体报错。 - 新日志仍为
DOWNLOAD：仍需排查 GPIO0 电平及自动下载电路；提供板背面版本/按键照片和完整新日志，不能据此认定缺 bootloader。 - 没有输出：自动复位或 UART 读取尚未证实有效，不能当作启动成功。
本次实际启动日志还出现了 SHA-256 comparison failed，随后 Simple boot 明确打印 Attempting to boot anyway... 并成功进入 Zephyr。这是当前镜像启动时的校验提示，不影响本次运行结果；后续若升级 Zephyr 或切换启动链，再单独检查镜像哈希配置。