跳到主要内容

PWM 背光

本页先观察背光效果。理解引脚从哪里来、配置怎样合并，请继续读 设备树 和 Kconfig。

当前已确认使用 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 指定同一块板。

旧 v4.2.0 固件已在实板验证持续报告 Backlight duty: 0%、25%、50%、75%、100%，屏幕背光随之变化。上面的 main 命令是独立构建环境，不能把旧实板结果当成其验证结果；也不要直接往 main 套用旧 LEDC 修复。若失败，保留当前提交、最终配置和首次驱动错误重新分析。

验证记录​

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

体验后做两次计算​

先打开示例的 app.overlay，找到 PWM_HZ(10)：频率 10 Hz 对应周期 100 ms。如果占空比为 25%，有效脉冲时间就是 25 ms。阅读 main.c 中传给 PWM API 的参数，检查是否满足脉冲宽度不大于周期。

再区分两个时间：PWM 的 100 ms 是硬件波形周期，而每档持续 800 ms 是应用等待时间。把每档等待改为 1600 ms，只应让亮度变化变慢，不应改变每档 PWM 的频率。预测后再构建和观察。

这份 10 Hz 配置保留了早期排错的实验条件，可能看到闪烁，不能当作产品背光的推荐频率。后续提高频率时需要检查当前驱动时钟及分辨率约束，并重新验证，不直接复制旧驱动补丁。

当你能解释这两个周期的区别，再回到 设备树 找 PWM 控制器、通道、引脚和极性的来源。

来源​

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