编译问题
| 现象 | 原因 | 处理 |
|---|
| PlatformIO 找不到库 | 打开了错误目录 | 必须直接打开含 platformio.ini 的工程目录。 |
| PlatformIO 尝试联网 | 换了平台版本或加入外部库 | 恢复原有 platformio.ini，不要添加 lib_deps。 |
找不到 task_logic.cpp | 打开了工具包根目录或错误子目录 | 在 VS Code 中直接打开选中的 arduino_pio\工程名。 |
无法烧录或没有串口
- 换一根确认能传数据的 USB 线，不能只供电。
- 运行
tools\detect_ports.ps1，确认 COM 号。
- 关闭占用串口的监视器，再执行烧录。
- 自动下载失败时：按住 BOOT，点一下 RESET，松开 BOOT，再烧录。
- 烧录后看不到输出：确认 115200 波特率并按一下 RESET。
RGB LED 不亮或颜色不对
- 将
CT_RGB_PIN 在 GPIO38 与 GPIO48 之间切换。
- 先发
SELFTEST，观察红、绿、蓝依次显示。
- 若颜色交换，检查驱动发送顺序；板载灯默认按 GRB 发送。
- 亮度默认较低是为了保护眼睛和供电，颜色值可提高到 255。
Touch 乱跳
- 上电校准的 300 ms 内不要触碰导电片。
- 输入
TOUCH CAL 重新校准。
- 用
SET TOUCH_DELTA 20 或更高数值降低灵敏度。
- 缩短导线，导电片远离 USB 线、蜂鸣器线和人体持续接触区域。
- 先连续查看
TOUCH READ，再确定阈值，不要猜固定原始值。
ADC 抖动或读数异常
- 确保输入范围为 0–3.3 V，并与开发板共地。
- 悬空 ADC 一定会乱跳；没有传感器时用电位器或固定分压。
- 优先使用 ADC1 的 GPIO1，避免 ADC2 与无线功能相互影响。
- 在信号源与地之间并联 0.1 μF 电容可进一步抑制噪声。
- 题目边界附近需增加迟滞，不能只用一个裸比较条件。
NVS 保存失败或参数异常
- 先输入
FACTORY 恢复带版本号和校验的数据结构。
- 修改参数后必须输入
SAVE，然后断电重启验证。
- 不要在 GPIO ISR、定时器 ISR 中写 NVS。
- 若更改了配置结构体，必须递增版本号，否则旧数据会被误读。