MagicRGB：基于 ESP32-S3 的按钮网络上报与 WS2812 状态灯

一个面向实际部署的 Arduino 项目：
使用 ESP32-S3 读取实体按钮状态，通过 TCP 上报事件，同时用 WS2812 灯效反馈设备连接与工作状态。

---

项目亮点

• 低耦合按钮上报：按钮按下即发送事件消息（默认消息 "2"）。
• 防抖与单次触发：内置 100ms 防抖 + 长按不重复发送，避免误触发刷屏。
• 连接稳定性增强：
  • Wi-Fi 省电关闭（避免休眠导致长连接异常）
  • TCP KeepAlive（更快发现死链）
  • 应用层心跳 PING（空闲时保持会话活性）
• 可视化状态反馈：
  • 重连成功亮绿
  • 重连失败亮红
  • 长时间空闲进入白光呼吸

---

功能说明

1) 按钮行为

• 按钮连接在 GPIO20，按下电平为 LOW。
• 按下后发送一条 TCP 文本消息：2。
• 松开后恢复可发送状态，下一次按下可再次触发。

2) 灯效行为（WS2812）

• 控制引脚：GPIO47
• 灯珠数量：4
• 设备空闲超过 5 分钟后，开始白色呼吸灯。
• 检测到连接断开后自动重连，并显示连接结果颜色。

3) 网络行为

• 开机自动连接 Wi-Fi，并连接指定 TCP 服务端。
• 空闲期按固定间隔发送 PING 心跳。
• TCP 断开后自动重连并恢复 KeepAlive 设置。

---

默认配置（可直接改）

位于 src/main.cpp：

• Wi-Fi SSID：MagicLLM
• Wi-Fi 密码：12345678
• 服务器地址：192.168.122.1
• 服务器端口：5000
• 按钮引脚：20
• WS2812 引脚：47

发布前建议将 Wi-Fi 与服务端配置改为你的实际环境参数。

---

硬件连接

ESP32-S3 ↔ 按钮

• 按钮一端接 GPIO20
• 按钮另一端接 GND

ESP32-S3 ↔ WS2812

• DIN 接 GPIO47
• 灯带供电与 ESP32 共地（必须共地）
• 若灯带较长，建议外部供电并预留限流/电源保护设计

---

软件环境

• Framework：Arduino
• Build System：PlatformIO
• Board：rymcu-esp32-s3-devkitc-1
• 依赖库：Adafruit NeoPixel@1.15.1
• 串口：115200

platformio.ini：

[env:rymcu-esp32-s3-devkitc-1]
platform = espressif32
board = rymcu-esp32-s3-devkitc-1
framework = arduino
lib_deps = adafruit/Adafruit NeoPixel@1.15.1
monitor_speed = 115200

---

快速开始

在项目根目录执行：

pio run
pio run -t upload
pio device monitor

看到串口输出连接成功后，按下按钮即可向服务端发送消息。

---

目录结构

.
├─ include/
│  └─ ws2812.hpp          # WS2812 接口声明与颜色定义
├─ src/
│  ├─ main.cpp            # 主逻辑：按钮、网络、重连、灯效
│  └─ ws2812.cpp          # WS2812 实现
├─ platformio.ini         # PlatformIO 配置
└─ README.md

---

运行流程（简版）

1. 上电初始化 WS2812 与串口。
2. 连接 Wi-Fi，并连接 TCP 服务端。
3. 监听按钮：
   • 按下发送 2
   • 松开复位发送标记
4. 空闲时发送 PING，并维护连接。
5. 连接异常时自动重连，灯光提示结果。

---

服务端联调建议

• 本项目发送的是简单文本行，适合快速接入 Python/Node/Go TCP 服务。
• 最低可用服务端能力：
  1. 接收换行分隔文本
  2. 能处理 "2" 事件
  3. 可忽略或记录 "PING"

---

常见问题（FAQ）

Q1：按下按钮没有触发？

• 确认按钮接法是否为 GPIO20 -> 按钮 -> GND。
• 确认是否与代码约定一致：按下为 LOW。

Q2：灯不亮或颜色异常？

• 确认 WS2812 数据线接到 GPIO47。
• 确认供电和地线可靠，且与开发板共地。

Q3：长时间后不再上报？

• 检查路由器/AP 是否限制空闲连接。
• 确认服务端是否稳定监听并接受重连。