跳到主要内容

04 · 屏幕背光亮灭与 PWM 调光

当前已确认使用 Touch 板

用户已确认现已换成 ESP32-S3-Touch-LCD-1.28，继续使用本页 Touch 目标。之前提供的无 Touch 板资料不适用于背光和显示引脚。更换物理板卡后，旧板的烧录成功记录不代表新板已写入程序。

这块微雪板使用 GPIO2 控制 LCD 背光。我们直接使用 Zephyr 板卡已有的 pwm-lcd0 别名做亮度实验，不再沿用普通 LED 的 led0 / 外接 GPIO18 示例。

本实验由两部分组成：板卡定义来自 zephyr/boards/waveshare/esp32s3_touch_lcd_1_28/，应用工程来自 applications/waveshare-backlight/。板卡 DTS 描述真实硬件连接，应用的 main.c 控制亮度，prj.conf 开启 PWM，app.overlay 只覆盖本实验需要的 PWM 参数。west build 会把这些内容合并到 build/waveshare-backlight-main/，west flash 再烧录其中生成的 BIN 文件。

示例放在哪里​

文档仓库保留完整可编辑示例：examples/waveshare-backlight/。本机已复制到固件工作区：

~/Projects/zephyr-main-workspace/applications/waveshare-backlight/
├── CMakeLists.txt
├── prj.conf
├── app.overlay
└── src/main.c

在新工作区首次准备时，可从文档仓库复制（本机已存在，直接跳过）：

mkdir -p ~/Projects/zephyr-main-workspace/applications
cp -R ~/Projects/zephyr-docs/examples/waveshare-backlight \
  ~/Projects/zephyr-main-workspace/applications/

先理解这个实验​

PWM_DT_SPEC_GET(DT_ALIAS(pwm_lcd0)) 读取板卡定义的通道、周期和极性。实验 overlay 将周期覆盖为 100 ms，即 10 Hz；工作区同时修正了 Zephyr 4.2 ESP32-S3 LEDC 驱动的默认低速时钟初始化，并在使用 RC_FAST 前启用 8 MHz RTC 时钟，否则会出现分频值为 0 的 -22 错误。应用依次输出 0%、25%、50%、75%、100% 占空比，再逐级降低，每级持续 800 ms。

0% / 100% 演示背光关与开，中间几级演示 PWM 调光。这是分级变化，不是连续呼吸曲线。

板卡默认 LEDC pinctrl 还列出 GPIO4 / GPIO5。示例 overlay 将 PWM 引脚限制到 GPIO2，并覆盖为 10 Hz，避免背光实验同时接管其他引脚，也不修改上游板卡 DTS。

prj.conf 只启用 PWM 与日志输出，并关闭本实验不使用的 DISPLAY / INPUT。只观察背光明暗，不应期待文字或图案。

编译​

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
west build -p always -b esp32s3_touch_lcd_1_28/esp32s3/procpu \
  ../applications/waveshare-backlight -d build/waveshare-backlight-main

确认构建日志加载了应用的 app.overlay。可以在最终 build/waveshare-backlight-main/zephyr/zephyr.dts 中核对 pwm-lcd0 与 LEDC pinctrl。

烧录与观察​

完成 Hello World 串口验证后，再写入这个实验：

west flash -d build/waveshare-backlight-main --esp-device /dev/ttyACM0
cd build/waveshare-backlight-main
west espressif monitor -p /dev/ttyACM0 -b 115200

多串口时与 Hello World 一样，分别用 --esp-device / -p 指定同一块板。

串口已在实板上验证会持续报告 Backlight duty: 0%、25%、50%、75%、100%，屏幕背光随之变化。若 PWM 返回错误，先确认使用的是最新工作区固件和已启用 LEDC 时钟修复的源码。

验证记录​

  • 软件编译：2026-09-18，Python 3.12.14 / Zephyr v4.2.0 / SDK 0.17.2 下成功；已核对生成的 pinctrl 只映射 GPIO2。详见实验台账。
  • 实板：2026-09-18 已烧录并验证串口日志与背光亮度变化通过。
  • 屏幕绘图、触摸和 IMU：后续独立实验。

来源​

板卡设备树 · 引脚定义 · 微雪背光说明