ESP32 点亮第一盏灯：外接 LED 和板载 RGB 灯要分开看

先做一个自己能解释的输出

第一份程序的目标是看见“我修改的代码确实在这块板上运行”。这次不用板载灯作为唯一证据，而是把一只普通红色LED接到GPIO4。你会得到明确的电流路径、可核对的串口日志，以及复位后重复出现的现象。

本文固定官方DevKitC-1 v1.1与N8R8模组。开发板外观相似不代表RGB连接相同；如果标签、板修订或USB电路不同，先回引脚与接线基础篇核对。只有资料检查不能证明你手上的LED已经闪烁，下面的现象均是等待实板执行的验收。

做到这里，你应该看到

说出板修订、模组后缀、外接灯GPIO和串口所用USB接口。

参考：[1] 乐鑫：ESP32-S3-DevKitC-1 v1.1，排针与RGB修订

先断电，把LED与电阻串成一条路

准备Kingbright WP7113ID红LED、330Ω电阻、面包板和导线。电阻限制电流。厂家1.9V典型正向压降是在10mA条件下给出的；若仅用它做近似计算，(3.3−1.9)/330约4.2mA。这不是本电路电流或压降的实测结果，低电流时压降也会改变。

GPIO4对应J1第4脚。用丝印找“4”，不要把代码里的4理解成任意一排的第4个孔。LED短脚或平边通常对应阴极，脚剪短后应以二极管挡确认。电阻在LED前后都可，只要串联。只用USB给开发板供电，不把5V连接到GPIO。

本篇外接灯固定为Kingbright WP7113ID（规格书V.14A），使用330Ω、±5%、额定0.25W电阻；如果沿用F03的1kΩ电阻，也可保留，亮度更低，程序不变。更换电阻必须先断电。

点击查看大图 ↗

参考：[1] 乐鑫：ESP32-S3-DevKitC-1 v1.1，排针与RGB修订[2] Arduino-ESP32 3.3.12：GPIO API与模式[5] Kingbright WP7113ID规格书 V.14A：极性、10mA条件压降与额定值

完整程序只负责一件事：每500毫秒翻转

setup先把GPIO4配置为输出并拉低，保证复位初始化后从灭灯开始。loop用两个状态量保存上次切换的时刻和当前亮灭状态，每经过500毫秒翻转一次。完整亮灭周期是约1000毫秒；不要把日志间隔与完整周期混为一谈。

DEMO_RGB默认false，第一轮不要改它。Serial日志会报告软件时钟和输出状态；它证明程序执行到写引脚的位置，实际灯光还要看外接电路。

// SPDX-License-Identifier: MIT
#include <Arduino.h>
constexpr uint8_t LED_PIN = 4;
// DevKitC-1 v1.1 RGB is GPIO38. Generic esp32s3 variant defaults to GPIO48.
constexpr uint8_t RGB_PIN = 38;
constexpr bool DEMO_RGB = false;
uint32_t lastChange = 0;
bool illuminated = false;
void setup() {
  Serial.begin(115200);
  pinMode(LED_PIN, OUTPUT);
  digitalWrite(LED_PIN, LOW);
  if (DEMO_RGB) rgbLedWrite(RGB_PIN, 0, 0, 0);
  Serial.println("P01 external LED GPIO4; period=1000ms");
}
void loop() {
  const uint32_t now = millis();
  if (uint32_t(now - lastChange) >= 500) {
    lastChange = now;
    illuminated = !illuminated;
    digitalWrite(LED_PIN, illuminated ? HIGH : LOW);
    if (DEMO_RGB) rgbLedWrite(RGB_PIN, 0, illuminated ? 16 : 0, 0);
    Serial.printf("t=%lu external=%u\n", (unsigned long)now, illuminated);
  }
}

参考：[2] Arduino-ESP32 3.3.12：GPIO API与模式[3] Arduino-ESP32 3.3.12：RGB LED接口

编译、上传，先看软件再看灯

下载本篇示例，保留以slug命名的目录和同名.ino，不要只复制中间几行。按环境篇安装CLI 1.5.1与esp32 core 3.3.12。下面命令在仓库根目录运行，PORT替换为board list中随插拔变化的真实串口。使用USB-to-UART口，CDC关闭时日志不走原生USB口。

1. 断电检查LED极性、串联电阻和共地后，用USB-to-UART连接电脑。
2. 编译成功后上传；关闭其他占用串口的监视器，再打开115200监视器。
3. 按RESET，观察external=1/0交替，记录10个完整周期是否亮灭一致。
4. 再次RESET，确认从初始灭灯重新开始。改间隔为1000再上传一次，可以确认电脑编译的正是这份源码。

arduino-cli compile --fqbn 'esp32:esp32:esp32s3:FlashSize=8M,PSRAM=opi,FlashMode=qio,PartitionScheme=default_8MB,CDCOnBoot=default,USBMode=hwcdc' examples/esp32/esp32-led-first-program
arduino-cli upload --fqbn 'esp32:esp32:esp32s3:FlashSize=8M,PSRAM=opi,FlashMode=qio,PartitionScheme=default_8MB,CDCOnBoot=default,USBMode=hwcdc' -p PORT examples/esp32/esp32-led-first-program
arduino-cli monitor -p PORT --config baudrate=115200

做到这里，你应该看到

记录实际编译结果、端口、复位后日志以及LED是否与external状态一致。

再比较板载RGB，别依赖猜测的LED_BUILTIN

完成外接灯后，可以把DEMO_RGB改成true再上传。官方v1.1把RGB数据脚接到GPIO38，程序用rgbLedWrite(38,0,16,0)发送低亮度绿色。它是可寻址灯珠，内部控制器接收颜色时序；把数据脚永久置HIGH不是发送一种颜色。

固定core里的泛型esp32s3 variant默认PIN_RGB_LED为48。这解释了为什么照搬LED_BUILTIN的程序在v1.1上可能没有预期现象。本文显式写38，只适用于核对过的v1.1；初版GPIO48与第三方板均需按各自原理图修改，而非轮流试引脚。

点击查看大图 ↗

参考：[1] 乐鑫：ESP32-S3-DevKitC-1 v1.1，排针与RGB修订[3] Arduino-ESP32 3.3.12：RGB LED接口[4] Arduino-ESP32 3.3.12：泛型S3引脚默认值

日志与灯分开排，最后恢复默认

有交替日志但外接灯不亮：断电后依次检查GPIO4丝印、面包板孔组、电阻是否串联、LED方向；用万用表确认而非带电乱插。一直亮时查是否误接3V3，或另一段程序重复写引脚。

没有日志：先确认USB-to-UART端口和115200，点RESET；只有供电灯亮不代表USB数据正常。连接超时时关闭串口，按住BOOT并点RESET后释放BOOT再上传，上传后RESET退出下载模式。

RGB不亮而外接灯正常：先确认DEMO_RGB=true和板修订，保留日志，恢复false即可继续后续按钮课程。不要为一只灯改动存储或启动保留引脚。

做到这里，你应该看到

能指出故障在程序、串口还是外接电路，并把默认示例恢复到可重复的基线。