完整教程：ESP32-S3 内置 RGB 灯详解与控制实战

网罗开发（小红书、快手、视频号同名）

  大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员
大家好，我是展菲！
全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

文章目录

• • 前言
  • 板载 RGB 灯到底是什么结构
  • 为什么 `RGB_BUILTIN = 97`？
  • 真正的 RGB 引脚在哪？（不同板子不一样）
  • 为什么不能用 digitalWrite？
  • 可直接运行的 RGB 控制例程
  • rgbLedWrite() 背后的原理
  • 常见问题
  • • 1）为什么我什么都没看到灯亮？
    • 2）为什么我能打印 97，但灯不亮？
    • 3）能否自己控制 GPIO48 来模拟 WS2812？
  • 总结
  • 附：真实工作流示意图

前言

——一次性搞懂 RGB_BUILTIN = 97 的真正含义

在使用 ESP32-S3（尤其是官方 DevKitC 系列）开发时，很多同学第一次运行板载 RGB 灯代码时都会遇到一个经典迷惑点：

Serial.println(RGB_BUILTIN);

串口竟然打印出：

97

然后你去翻 GPIO 编号表，发现根本没有 GPIO97 这种引脚？！
更离谱的是：你用 digitalWrite(97, HIGH) 根本无法点亮板载灯。

这时你可能会疑惑：

• RGB_BUILTIN = 97 到底是什么？

• RGB 灯真实引脚是哪一个？

• 为什么不能像控制普通 GPIO 那样控制它？

• rgbLedWrite() 背后到底干了什么？

本文一次性全部讲清楚，并带你完成从“搞懂原理”到“可运行 Demo”的完整实战。

板载 RGB 灯到底是什么结构

大多数 ESP32-S3 DevKitC 上的板载 RGB 灯 不是普通三色 LED，
而是一个独立驱动的 WS2812 / SK6812 数字 RGB LED。

特点是：

功能	描述
供电	5V / 3.3V
控制方式	单线串行协议（非 GPIO 高低电平）
支持	24-bit RGB + 亮度
控制外设	RMT / LEDC 自动生成时序

所以它不能用普通 GPIO 的 digitalWrite() 控。

为什么 RGB_BUILTIN = 97？

Arduino-ESP32 框架为了“跨板通用”，加入了一个虚拟编号：

• RGB_BUILTIN = 97 并非真实物理 GPIO

• 它是 SDK 定义的 RGB 控制通道 ID

• 真实控制引脚依然是板载硬件确定的 GPIO（如 GPIO48）

你会在这类路径中看到：

hardware/esp32/variants/esp32s3/pins_arduino.h

其中包含类似：

#define RGB_BUILTIN 97
#define RGB_BUILTIN_PWR 48

这说明：

RGB_BUILTIN 不是引脚，而是“LED 通道编号 97”
真正驱动 WS2812 的管脚是 GPIO48。

真正的 RGB 引脚在哪？（不同板子不一样）

板型	RGB_BUILTIN	RGB 实际 GPIO	说明
ESP32-S3 DevKitC-1	97	GPIO48	最常见
ESP32-S3-BOX Lite	97	GPIO38	音箱系列
ESP32-S3-EYE	无	无板载 RGB
某些第三方板	97	GPIO8 / GPIO2	需看原理图

最简单确认方式：

打开官方原理图（DevKitC-1 示例）

[图片上传失败…(image-69c325-1764857206853)]

可以看到 RGB LED（WS2812）接在 GPIO48 上。

为什么不能用 digitalWrite？

因为 WS2812 协议需要 800kHz 精准时序：

• T0H：0.35µs

• T0L：0.80µs

• T1H：0.70µs

• T1L：0.60µs

普通 GPIO 无法做到，所以需要 RMT/LEDC 等外设自动生成波形。

Arduino 提供专用接口：

rgbLedWrite(RGB_BUILTIN, r, g, b);

底层自动：

• 初始化控制通道（虚拟编号 97）

• 将其映射到真实的 GPIO（如 48）

• 使用 RMT 输出 WS2812 数据帧

可直接运行的 RGB 控制例程

下面这段代码你可以直接复制上传，100% 能亮灯。

#include <Arduino.h>
  #include "esp32-hal-ledc.h"
  void setup() {
  Serial.begin(115200);
  delay(1000);
  #ifdef RGB_BUILTIN
  Serial.print("RGB_BUILTIN: ");
  Serial.println(RGB_BUILTIN);
  // 依次输出 RGB 三色
  rgbLedWrite(RGB_BUILTIN, 255, 0, 0);   // 红
  delay(500);
  rgbLedWrite(RGB_BUILTIN, 0, 255, 0);   // 绿
  delay(500);
  rgbLedWrite(RGB_BUILTIN, 0, 0, 255);   // 蓝
  delay(500);
  // 呼吸灯示例
  for (int b = 0; b < 255; b++) {
  rgbLedWrite(RGB_BUILTIN, b, b, b);
  delay(5);
  }
  for (int b = 255; b >= 0; b--) {
  rgbLedWrite(RGB_BUILTIN, b, b, b);
  delay(5);
  }
  #endif
  }
  void loop() {}

运行后串口会输出：

RGB_BUILTIN: 97

同时板载灯依次亮 → 红 → 绿 → 蓝 → 呼吸灯。

rgbLedWrite() 背后的原理

[图片上传失败…(image-3377e7-1764857206853)]

调用 rgbLedWrite(97) 时会触发：

1. 将 虚拟 LED 通道 97 映射到板子的真实 GPIO（如 48）

2. 设置 LEDC / RMT 时序控制器

3. 将 RGB 参数打包为 24-bit WS2812 帧

4. 自动输出精准波形

这就是你看到 “为什么不用 digitalWrite” 的原因。

常见问题

1）为什么我什么都没看到灯亮？

可能的原因：

• 你用的并不是 DevKitC 原装板

• 你的板子没有 RGB（如 S3-EYE、N8R2）

• RGB 引脚实际不是 GPIO48（第三方板）

解决方案：
查看板载丝印
查官方原理图
查 Arduino variant 文件

2）为什么我能打印 97，但灯不亮？

你用了 digitalWrite(97)

这对数字 LED 完全无效。

3）能否自己控制 GPIO48 来模拟 WS2812？

理论上可以，但时序要求太严。
不建议。
直接用 rgbLedWrite() 即可。

总结

结论	说明
RGB_BUILTIN = 97	虚拟编号，不是 GPIO
实际引脚通常是 GPIO48	需看原理图确认
不能用 digitalWrite	WS2812 需要时序控制
应使用 rgbLedWrite()	框架封装好 WS2812 驱动
原理：RMT / LEDC 输出波形	SDK 自动处理

附：真实工作流示意图

+---------------------+
|  rgbLedWrite(97)    |
+----------+----------+
           |
           v
+---------------------+
|   Arduino LED API   |
+----------+----------+
           |
           v
+-------------------------+
|   RGB Controller (97)   |  <-- 虚拟通道 ID
+----------+--------------+
           |
           v
+-------------------------+
|  RMT / LEDC Waveform    |
+----------+--------------+
           |
           v
+-------------------------+
|   GPIO48 → WS2812 LED   |  <-- 实际 GPIO
+-------------------------+