04 · 屏幕背光亮灭与 PWM 调光
用户已确认现已换成 ESP32-S3-Touch-LCD-1.28，继续使用本页 Touch 目标。之前提供的无 Touch 板资料不适用于背光和显示引脚。更换物理板卡后，旧板的烧录成功记录不代表新板已写入程序。
这块微雪板使用 GPIO2 控制 LCD 背光。我们直接使用 Zephyr 板卡已有的 pwm-lcd0 别名做亮度实验，不再沿用普通 LED 的 led0 / 外接 GPIO18 示例。
示例放在哪里
文档仓库保留完整可编辑示例：examples/waveshare-backlight/。本机已复制到固件工作区：
~/Projects/zephyr-workspace/applications/waveshare-backlight/
├── CMakeLists.txt
├── prj.conf
├── app.overlay
└── src/main.c
在新工作区首次准备时，可从文档仓库复制（本机已存在，直接跳过）：
mkdir -p ~/Projects/zephyr-workspace/applications
cp -R ~/Projects/zephyr-docs/examples/waveshare-backlight \
~/Projects/zephyr-workspace/applications/
先理解这个实验
PWM_DT_SPEC_GET(DT_ALIAS(pwm_lcd0)) 读取板卡定义的通道、周期和极性。本板默认周期为 4 ms，即 250 Hz。应用依次输出 0%、25%、50%、75%、100% 占空比，再逐级降低，每级持续 800 ms。
0% / 100% 演示背光关与开，中间几级演示 PWM 调光。这是分级变化，不是连续呼吸曲线。
板卡默认 LEDC pinctrl 还列出 GPIO4 / GPIO5。示例 overlay 将 PWM 引脚限制到 GPIO2，避免背光实验同时接管其他引脚；不修改上游板卡 DTS。
prj.conf 只启用 PWM 与日志输出，并关闭本实验不使用的 DISPLAY / INPUT。只观察背光明暗，不应期待文字或图案。
编译
source ~/Projects/zephyr-workspace/.venv-py312/bin/activate
cd ~/Projects/zephyr-workspace/zephyr
west build -p always -b esp32s3_touch_lcd_1_28/esp32s3/procpu \
../applications/waveshare-backlight -d build/waveshare-backlight
确认构建日志加载了应用的 app.overlay。可以在最终 build/waveshare-backlight/zephyr/zephyr.dts 中核对 pwm-lcd0 与 LEDC pinctrl。
烧录与观察
完成 Hello World 串口验证后，再写入这个实验：
west flash -d build/waveshare-backlight
cd build/waveshare-backlight
west espressif monitor -p /dev/ttyACM0 -b 115200
多串口时与 Hello World 一样，分别用 --esp-device / -p 指定同一块板。
串口应持续报告 Backlight duty: ...%，屏幕背光随之变化。若 PWM 返回错误，程序会打印错误码并停止；若日志正常但亮度无变化，核对具体型号、GPIO2 接线及板卡版本，先不把它记为通过。
验证记录
- 软件编译：2026-09-18，Python 3.12.14 / Zephyr v4.2.0 / SDK 0.17.2 下成功；已核对生成的 pinctrl 只映射 GPIO2。详见实验台账。
- 实板：待验证，没有自动烧录。
- 屏幕绘图、触摸和 IMU：后续独立实验。