ESP32C3多功能信号灯开源项目实战：从GPIO控制到WiFi远程控制

这次我们来看一个已经开源的多功能信号灯项目，核心硬件用的是 ESP32C3。这类项目在开源社区一直很受欢迎，原因很直接：芯片成本低、上手难度小、能串 WiFi 和蓝牙、可以用 Arduino 或 ESP-IDF 开发，而且“信号灯”本身就能玩出很多花样——状态指示、倒计时模拟、多色灯效、网络远程控制，全都能塞进一块小板子里。

从标题看，这个项目的重点是“多功能”三个字。它不是一颗简单闪烁的 LED，而是把多种信号灯行为封装成了可切换、可扩展的硬件方案。对我们做嵌入式、物联网或者桌面硬件玩具的开发者来说，这属于典型的“拿到代码改一改就能变成自己项目”的类型。

这篇文章不绕弯子，直接按“项目能力 -> 硬件选型 -> 环境搭建 -> 代码结构 -> 功能验证 -> 排错清单 -> 扩展方向”的顺序展开。如果你正好在找 ESP32C3 的入门实战项目，或者想做一个带 WiFi 控制的信号指示装置，这篇文章值得存下来。

1. 核心能力速览

这个项目能做什么，可以从功能、硬件门槛、开发方式和扩展空间几个维度来看。下面是整理好的速览表。

这部分信息来自公开的项目介绍和 ESP32C3 的一般技术规格。更准确的参数，比如具体支持多少种灯效、有没有 Web 控制页、引脚定义如何分配，需要以开源仓库里的 README 和原理图为准。

2. 适用场景与使用边界

2.1 它适合解决什么问题

信号灯的核心价值是“把状态可视化”。它不只是一颗灯，而是通过颜色和闪烁节奏传递信息。

常见的应用场景包括：

• 开发板状态指示：程序运行中、内存异常、网络掉线、OTA 升级完成，用不同颜色区分。
• 桌面环境监测：配合温湿度传感器，绿灯表示正常、黄灯表示偏高、红灯表示超限。
• 倒计时演示：模拟红绿灯倒计时，在创客教育、展厅演示、课程设计中很好用。
• 网络状态指示：让 ESP32C3 连接 WiFi，定时请求某个服务，把在线状态显示在灯上。
• Home Assistant 或物联网联动：如果固件支持 MQTT，可以接收服务器消息来切换灯效。

这类项目的本质是 GPIO 控制加状态机管理。如果以后要改造成其他 RGB 灯带控制、智能门铃提示器、创作现场氛围灯，只需要换一下灯的类型和驱动函数。

2.2 不适合什么场景

这个项目不适合作为实际的交通信号灯使用。原因很明确：真实交通信号灯涉及安全认证、冗余设计、故障检测和专业标准，业余 DIY 设备不能承担公共交通安全责任。

另外，如果只是想做一个“能亮”的灯，这个项目会显得复杂。它更适合愿意做一点代码定制、需要多种模式切换的开发者。现场完全不改代码直接用的“开箱即用”产品，不应该拿这个开源项目来比。

2.3 使用边界与合规提醒

• 不要将 DIY 信号灯安装在真实道路、停车场、施工区域等公共场合。
• 如果项目用到摄像头、蓝牙扫描、网络请求，注意不要采集陌生人信息。
• 使用开源代码和 PCB 设计时，遵守原作者的开源许可证条款，尤其是商用限制。
• DIY 焊接和调试时，注意电源电压，避免反接和短路。

3. 硬件平台选型：为什么要用 ESP32C3

选 ESP32C3 而不是 ESP8266，也不是 STM32，原因要从性价比、开发效率和功能需求三个角度看。

3.1 成本与性能

ESP32C3 是乐鑫推出的 RISC-V 架构芯片，单核 160MHz，内置 400KB SRAM，支持 2.4GHz WiFi 和 Bluetooth 5。虽然它是单核，但对于信号灯这种轻量控制任务来说绰绰有余。市面上常见的 ESP32C3 SuperMini 开发板价格很便宜，几块钱到十几块钱就能买到，这对 DIY 项目非常友好。

3.2 开发环境成熟

ESP32C3 同时支持 Arduino、ESP-IDF 和 PlatformIO。Arduino 生态的最大优势是库多，比如 FastLED 能直接驱动 WS2812B 灯带，Ticker 能实现非阻塞定时器，WiFiManager 能解决配网问题。这些库都是现成的，信号灯项目要用的话，代码量可以被压得很低。

如果从 ESP-IDF 的角度看，ESP32C3 的 FreeRTOS 支持也不错，适合在信号灯的基础上继续叠加传感器采集、网络协议栈等任务。所以这个芯片既适合快速验证，也适合做正式产品原型。

3.3 与 ESP8266 的对比

ESP8266 也有 WiFi，价格甚至更低，但它的 GPIO 数量少、蓝牙功能缺失、开发体验相对旧。很多新的开源项目已经转向 ESP32 系列。ESP32C3 作为入门级 RISC-V 芯片，未来兼容性更好，这也是它能成为热门 DIY 芯片的原因之一。

3.4 开发板型号差异

需要注意，市面上 ESP32C3 开发板有不同尺寸引脚定义。SuperMini、合宙 ESP32C3、官方 DevKitM，板载 LED 引脚、串口引脚、Flash 大小都可能不同。所以在连接信号灯前，必须先确认开发板的引脚图，否则程序烧进去会发现灯不亮。

4. 硬件设计与元件清单

从 DIY 的角度，做这款多功能信号灯不需要太复杂的设备。常规做法是先把模块在面包板上验证，然后再画 PCB 或者做洞洞板焊接。

4.1 基础元件清单

如果不想用多颗独立 LED，可以直接使用 WS2812B 灯珠或 8 位 RGB 灯环。这样只需要一个 GPIO 就能控制多个颜色，代码也能复用 FastLED 库。

4.2 引脚连接参考

下面的引脚表是一个常见示例，实际项目的引脚分配以开源仓库的原理图为准。这里以 ESP32C3 的可编程 GPIO 为例：

接 LED 的时候，必须串联限流电阻。ESP32C3 的 GPIO 输出电压是 3.3V，普通 LED 工作电流建议控制在 5mA 到 20mA。如果直接接 LED 不串电阻，电流过大可能烧坏 GPIO 或者整个开发板。

// LED GPIO 定义，实际使用前需要按开发板调整 #define PIN_LED_RED 2 #define PIN_LED_YELLOW 3 #define PIN_LED_GREEN 4

4.3 供电方案

ESP32C3 开发板一般通过 USB 供电，电压 5V，板载稳压芯片会把电压降到 3.3V。若要脱离电脑独立运行，可以用 5V 充电宝、充电头或 3.7V 锂电池。

锂电池供电时要注意，普通 ESP32C3 开发板不一定有锂电池充电管理电路。如果直接接锂电池到板子的 3.3V 引脚，存在电压过高或稳压不稳的风险。最好使用带充电保护的一体化电源模块，或者自己加一颗锂电池保护板。

如果想降低功耗，可以研究 ESP32 的 modem sleep 和 light sleep 模式。信号灯在待机时不需要全速运行，激活省电模式之后，电池供电的续航会明显提升。

5. 开发环境准备

5.1 安装 Arduino IDE

从 Arduino 官网下载 Arduino IDE 2.x，安装完成后打开“开发板管理器”。在“文件 -> 首选项 -> 附加开发板管理器网址”中，添加乐鑫的 ESP32 开发板索引地址：

https://espressif.github.io/arduino-esp32/package_esp32_index.json

然后打开“工具 -> 开发板 -> 开发板管理器”，搜索esp32，找到esp32 by Espressif Systems，点击安装。

安装完成后，在“工具 -> 开发板”里选择ESP32C3 Dev Module或对应的开发板型号。如果使用 SuperMini，一般选择ESP32C3 Dev Module，然后设置正确的端口。

5.2 安装 PlatformIO（可选）

PlatformIO 更适合工程化开发。在 VS Code 中安装 PlatformIO 插件后，新建项目时选择Espressif ESP32-C3 Dev Module作为开发板，框架选Arduino。它会自动下载工具链，不需要手动配置环境变量。

[env:esp32-c3-devkitm-1] platform = espressif32 board = esp32-c3-devkitm-1 framework = arduino monitor_speed = 115200

5.3 测试串口连接

把 ESP32C3 开发板用 USB 线连接到电脑。在 Arduino IDE 的设备管理器中，如果看到 USB 串口设备，说明驱动正常。如果无法识别，可能是板载 USB 芯片驱动问题，也可能 USB 线只是充电线没有数据传输功能，换一根数据线再试。

打开串口监视器，波特率设置成 115200，复位开发板。正常会看到启动日志，类似：

ESP-ROM:esp32c3-api1-20210207 Build:Feb 7 2021 rst:0x1 (POWERON),boot:0xc (SPI_FAST_FLASH_BOOT)

看到这段日志，说明开发板和电脑之间的通信链路是通的，可以开始烧录程序。

6. 固件功能设计与代码结构

信号灯的“多功能”表现在行为模式上。一次完整的信号灯逻辑可以拆成三层：

1. 硬件层：控制 GPIO 输出，管理 LED 亮灭。
2. 行为层：定义模式，比如红灯常亮、绿灯闪烁、黄灯呼吸。
3. 交互层：通过按键切换模式、通过串口指令控制、通过 WiFi 远程控制。

6.1 项目文件结构

参考常见的 ESP32 开源项目布局，信号灯项目的代码可以分成下面几部分：

esp32c3-signal-lamp/ ├── src/ │ ├── main.cpp # 主程序入口 │ ├── lamp_mode.h # 模式枚举与配置 │ ├── lamp_ctrl.h # LED 控制封装 │ ├── button.h # 按键扫描 │ └── wifi_mgr.h # WiFi 连接封装 ├── include/ ├── lib/ ├── platformio.ini # PlatformIO 配置 └── README.md

如果是 Arduino IDE 的写法，可以不太刻意追求目录结构，但建议把“LED 控制”和“模式切换”写成独立函数，不要在 loop 里堆逻辑。

6.2 基础信号灯控制代码框架

下面这段代码是典型的信号灯控制框架，使用非阻塞逻辑。可以看到，这里没有用delay()，而是用millis()做时间差判断，这样后续加按键扫描和 WiFi 任务时，不会被 LED 闪烁卡住。

#include <Arduino.h> #define PIN_LED_RED 2 #define PIN_LED_YELLOW 3 #define PIN_LED_GREEN 4 unsigned long lastToggle = 0; bool ledState = false; enum LampMode { MODE_OFF, MODE_RED_STEADY, MODE_GREEN_STEADY, MODE_RED_BLINK, MODE_GREEN_BLINK, MODE_ALTERNATE }; LampMode currentMode = MODE_OFF; void setAllLeds(bool red, bool yellow, bool green) { digitalWrite(PIN_LED_RED, red ? HIGH : LOW); digitalWrite(PIN_LED_YELLOW, yellow ? HIGH : LOW); digitalWrite(PIN_LED_GREEN, green ? HIGH : LOW); } void applyMode(LampMode mode) { switch (mode) { case MODE_OFF: setAllLeds(false, false, false); break; case MODE_RED_STEADY: setAllLeds(true, false, false); break; case MODE_GREEN_STEADY: setAllLeds(false, false, true); break; default: break; } } void setup() { pinMode(PIN_LED_RED, OUTPUT); pinMode(PIN_LED_YELLOW, OUTPUT); pinMode(PIN_LED_GREEN, OUTPUT); Serial.begin(115200); applyMode(MODE_RED_STEADY); } void loop() { // 预留按键扫描和模式切换逻辑 }

这段代码只是初始框架，还不能算最终成品。真正的“多功能”还需要把闪烁时序、按键切模式、串口指令都加进去。

6.3 非阻塞闪烁实现

如果需要红灯以 500ms 间隔闪烁，可以这样写：

unsigned long previousMillis = 0; const unsigned long interval = 500; void loop() { unsigned long now = millis(); if (now - previousMillis >= interval) { previousMillis = now; ledState = !ledState; digitalWrite(PIN_LED_RED, ledState ? HIGH : LOW); } }

这种写法的好处是，在 LED 闪烁的同时，仍然可以响应按键、读取传感器数据、处理网络请求。如果换成delay(500)，整个程序在延时期间会被阻塞，所有其他任务都会停摆。

6.4 按键切换模式

按键扫描一般要处理“按下”“释放”“长按”三种状态。最简单的做法是读取 GPIO 电平，检测下降沿触发切换：

#define PIN_BUTTON 9 int lastButtonState = HIGH; unsigned long lastDebounceTime = 0; const unsigned long debounceDelay = 50; void setupButton() { pinMode(PIN_BUTTON, INPUT_PULLUP); } void updateButton() { int reading = digitalRead(PIN_BUTTON); if (reading != lastButtonState) { lastDebounceTime = millis(); } if ((millis() - lastDebounceTime) > debounceDelay) { if (reading == LOW) { // 按键按下，切换到下一个模式 currentMode = (LampMode)((currentMode + 1) % MODE_ALTERNATE); applyMode(currentMode); Serial.print("Switch to mode: "); Serial.println(currentMode); } } lastButtonState = reading; }

这里用了 50ms 消抖时间，避免机械按键抖动导致一次按下触发多次模式切换。

6.5 串口指令控制

除了按键，还可以用串口接收指令。比如输入R切红灯、G切绿灯、B切换闪烁模式。下面是一个简单的命令处理函数：

void handleSerialCommand() { if (Serial.available() > 0) { char cmd = Serial.read(); switch (cmd) { case 'R': currentMode = MODE_RED_STEADY; applyMode(currentMode); break; case 'G': currentMode = MODE_GREEN_STEADY; applyMode(currentMode); break; case 'F': currentMode = MODE_RED_BLINK; break; default: Serial.println("Unknown command"); break; } } }

在loop()中调用handleSerialCommand()后，就可以通过串口监视器直接切换信号灯模式。这个功能对调试非常有用，不需要每次改代码重新烧录。

7. 功能测试与效果验证

完成代码编写后，不要急着做 PCB，先在面包板上验证所有模式。下面是一套可复用的测试流程。

7.1 测试准备

1. 按引脚表连接 LED、电阻和按键。
2. 为开发板烧录测试固件。
3. 打开串口监视器，波特率 115200。
4. 准备一个万用表，必要时测量 GPIO 输出电压。

7.2 测试矩阵

7.3 失败判断

• LED 不亮：检查引脚号、共阴共阳接法、电阻值、GPIO 是否复用为下载模式。
• 按键无反应：检查是否使用INPUT_PULLUP，接线是否接对 GND。
• 闪烁频率不准：millis()溢出或中断处理阻塞，分析时间戳打印。
• 烧录后一直重启：可能是供电不足，或 GPIO 引脚在启动时有特殊状态，比如 GPIO9 在 ESP32C3 中是 boot 引脚，按键接在 GPIO9 上会影响启动。

8. 网络能力与远程控制扩展

ESP32C3 最值得玩的地方是联网。信号灯如果只停在本地按键控制，其实没有完全发挥芯片能力。更实用的做法是让信号灯支持 WiFi 配网和远程指令下发。

8.1 WiFi 连接代码框架

下面这个代码段演示了如何让 ESP32C3 作为 WiFi Station 连接路由器：

#include <WiFi.h> const char* ssid = "your_ssid"; const char* password = "your_password"; void setupWifi() { WiFi.mode(WIFI_STA); WiFi.begin(ssid, password); Serial.print("Connecting to WiFi"); while (WiFi.status() != WL_CONNECTED) { delay(500); Serial.print("."); } Serial.println(); Serial.print("Connected, IP address: "); Serial.println(WiFi.localIP()); }

连接成功后，可以通过 HTTP Server 或 MQTT 客户端接收外部指令。这边建议优先考虑 HTTP，因为 HTTP 的逻辑更简单，适合入门。

8.2 HTTP 控制接口示例

如果需要通过浏览器控制信号灯，可以在 ESP32C3 上运行一个轻量级 HTTP Server：

#include <WebServer.h> WebServer server(80); void handleRoot() { String html = "<html><body>"; html += "<h1>ESP32C3 Signal Lamp</h1>"; html += "<p><a href=\"/red\">Red On</a></p>"; html += "<p><a href=\"/green\">Green On</a></p>"; html += "<p><a href=\"/off\">All Off</a></p>"; html += "</body></html>"; server.send(200, "text/html", html); } void setupWebServer() { server.on("/", handleRoot); server.on("/red", []() { setAllLeds(true, false, false); server.send(200, "text/plain", "red on"); }); server.on("/green", []() { setAllLeds(false, false, true); server.send(200, "text/plain", "green on"); }); server.on("/off", []() { setAllLeds(false, false, false); server.send(200, "text/plain", "off"); }); server.begin(); }

在setup()中调用setupWebServer()，在loop()中调用server.handleClient()。之后手机和电脑在同一局域网内，浏览器输入开发板 IP 就能打开控制页面。

8.3 MQTT 接入物联网平台

MQTT 更适合做设备联动。信号灯作为 MQTT 客户端，订阅主题lamp/mode，服务器往这个主题发消息，信号灯就切换模式。核心代码逻辑：

// MQTT 客户端逻辑需要使用 PubSubClient 库 // 以下为伪代码示意，需按实际库和服务器配置调整 void mqttCallback(char* topic, byte* payload, unsigned int length) { String message; for (unsigned int i = 0; i < length; i++) { message += (char)payload[i]; } if (message == "red") { setAllLeds(true, false, false); } else if (message == "green") { setAllLeds(false, false, true); } }

接入 MQTT 后，信号灯就能被 Home Assistant、Node-RED 或其他服务端程序控制。这也是“多功能”的高级形态。

9. 资源占用与性能观察

ESP32C3 不像电脑显卡那样有“显存占用”，但对单片机项目来说，监控 Flash、RAM 和 CPU 占用同样重要。

9.1 编译输出观察

用 Arduino IDE 编译时，底部控制台会输出类似下面这些信息：

Sketch uses 231334 bytes (22%) of program storage space. Global variables use 13728 bytes (30%) of dynamic memory.

如果你发现全局变量使用量接近 400KB 上限，说明代码中定义了大数组或 String 对象太多。信号灯项目的全局变量占用一般不高，但如果加了 WiFi、HTTP Server，内存占用会明显上升。

9.2 运行期波动

信号灯闪烁本身对 CPU 消耗很低。真正影响性能的是 WiFi 连接和网络请求。在loop()中调用server.handleClient()时，如果业务逻辑里有delay()，会拖慢响应速度。所以提醒一点：所有耗时操作，包括网络重连、灯效切换，都尽量改成非阻塞或放到事件回调里处理。

9.3 降低功耗

想用电池供电时，要注意 WiFi 是全系统功耗大户。不需要网络功能的场景，可以在空闲时关闭 WiFi，需要时再唤醒。ESP32C3 的WiFi.mode(WIFI_OFF)可以关闭无线，配合esp_light_sleep_start()能进入浅睡眠。

#include "esp_pm.h" #include "esp_sleep.h" void enterLightSleep() { WiFi.mode(WIFI_OFF); esp_sleep_enable_timer_wakeup(10 * 1000000); // 定时 10 秒唤醒 esp_light_sleep_start(); }

10. 常见问题与排查方法

环境问题、接线问题、代码问题，会同时出现在这种硬件 DIY 项目中。把常见的问题整理成一张排查表，能省掉大量反复试错的时间。

11. 最佳实践与使用建议

11.1 先把 GPIO 分配到“安全引脚”

ESP32C3 不是所有 GPIO 都能随便接外部设备。比如 GPIO9 是 BOOT 引脚，GPIO8 一般接板载 LED，GPIO18 一般是 USB D-，不能作为普通 IO 使用。做硬件设计前，先查芯片数据手册或开发板引脚图。这个检查比写代码更重要。

11.2 保持代码结构干净

一个信号灯项目看起来简单，但功能多了以后，很容易变成一坨if else。建议把模式枚举、LED 驱动、按键扫描、WiFi 逻辑分开。后续要增加“蜂鸣器报警”或者“红外遥控”功能，只需要新增一个模块，不需要大改主逻辑。

11.3 LED 驱动选型

如果是单色 LED 加限流电阻，最简单；如果是 RGB 共阴或共阳 LED，要确认引脚接法和驱动电平；如果是 WS2812B 灯带，用 FastLED 库能省很多事。不同的灯模块，代码里的驱动部分完全不同，所以原项目的灯珠型号需要确认。

11.4 日志输出规范

建议在所有关键动作后加Serial.println。比如按键按下、模式切换、WiFi 连接成功。日志是嵌入式调试的重要手段，不要省略。

11.5 保存一套最小可运行配置

在开发过程中，保持一个“最简单的点亮 LED”程序作为基线。如果后面改了代码灯不亮了，重新烧录基线程序，马上能判断是硬件坏了还是代码出错。这个习惯能大幅提高调试效率。

12. 电路与 PCB 设计建议

如果已经验证完面包板，希望把项目做成固定的小板子，可以考虑自己画 PCB。

12.1 原理图设计要点

• ESP32C3 的供电引脚需要加 10uF 和 0.1uF 滤波电容。
• 每个 LED 串一颗限流电阻。
• 按键一端接 GPIO，另一端接 GND，使用内部上拉。
• 预留串口 TX/RX 引脚，方便后续烧录和调试。
• 如果是锂电池供电，加充电管理芯片和 USB 输入路径切换。

12.2 PCB 布局建议

信号灯的 PCB 不需要高速布线，优先考虑的是体积和接口位置。LED 尽量放在板子边缘，方便开孔安装；按键放在另一侧，避免误触；USB 口朝外，方便插线供电。

如果不想自己画板，也可以用洞洞板手工焊接，工程量不大。

13. 从开源项目变成自己的作品

这个 ESP32C3 多功能信号灯项目的价值，不在于“装一个红绿灯”，而在于它演示了 GPIO 控制、状态机管理、按键交互、WiFi 通信这些基础能力。拿到源代码之后，建议按下面的顺序改造：

1. 先原样烧录，跑通基础模式。
2. 修改引脚定义，适配自己的开发板和灯珠。
3. 增加一种新的信号灯模式，比如黄灯呼吸效果。
4. 接入 WiFi，做局域网控制。
5. 再加一个传感器，根据环境数据自动切换灯效。

每一步都是独立的小挑战，改完以后，整个项目的功能边界已经远超最初版本。

如果这是你第一次玩 ESP32C3，这篇文章里涉及的硬件接线和代码片段已经很够用了。如果已经在玩物联网，可以把信号灯当成一个“带状态输出的传感器节点”，接入你的家庭服务器或云平台。

不管你是想做一个桌面状态灯，还是想在创客教育里用低成本硬件演示“信号与系统”，这个开源项目都值得拉下来跑一遍。先从点亮一颗 LED 开始，然后逐步把功能叠上去。你会发现，ESP32C3 的玩法比想象中多得多。