ESP32C3-SuperMini PlatformIO板级配置：从USB CDC到Flash分区实战

简介：ESP32-C3 SuperMini 开发板以超小尺寸和 RISC-V 架构受到众多物联网及嵌入式开发者关注，尤其适合可穿戴设备、传感器节点等体积受限的场景，但 PlatformIO 官方仓库中并未直接内置该板卡的板级定义，导致创建项目时无法找到对应型号。这份支持文件压缩包填平了这个缺口，内含 super_mini_esp32c3.json 板定义文件、pins_arduino.h 引脚定义文件以及 README 说明文档，共 3 个文件，打包后仅 2KB，轻量实用。按照说明将两个核心文件分别放置到 espressif32 平台的 boards 目录和 framework-arduinoespressif32 的 variants 对应目录，PlatformIO 即可正确识别 ESP32-C3 SuperMini，并自动加载 Arduino 引脚映射，省去手工编写板卡配置的繁琐流程，同时避免引脚错乱导致的编译或下载失败，也便于在多台电脑或团队间同步开发环境。对于准备从 Arduino IDE 迁移到 PlatformIO 的入门用户，以及希望在命令行中快速搭建 ESP32-C3 开发环境的进阶玩家，这套文件都能有效降低初始化成本。该资源已有 1275 人学习下载，是 SuperMini 开发者值得收藏的基础工具。

1. ESP32C3-SuperMini 支持文件：先把板级参数对齐再谈点灯

十几块钱一块的ESP32C3-SuperMini，插上电脑往往不被PlatformIO认识，大多数人顺手选esp32-c3-devkitm-1替代，结果烧录找不到串口、LED点在不存在的引脚上、4MB Flash被当2MB分区用。这份PlatformIO支持文件做的是很窄的事：给出能被espressif32平台直接加载的board定义、USB CDC开关和Flash参数，让SuperMini在第一次编译时就用正确的板级配置，而不是靠一堆论坛帖子里拼出来的flags硬凑。适合从ESP8266转过来、想用RISC-V低功耗板做小体积联网项目的人，也适合在同一批板卡上批量铺工程的人。多数翻车不是代码问题，而是板级描述没对齐。

2. 为什么这块板对不上官方board定义：C3硬件与PlatformIO的装载方式

2.1 同为ESP32-C3，SuperMini和原厂开发板差异在哪

很多人第一次拿到SuperMini都会有一个错觉：芯片是ESP32-C3，那直接拿官方esp32-c3-devkitm-1的board定义来编译不就行了？我当年也这么干过，结果固件烧进去，串口监控里除了上电乱码什么都没有。后来才想明白，C3这块芯片和它所在的小板子，其实是两套数据：芯片决定指令集、主频、外设控制器；板子决定哪些引脚被引出、哪个GPIO接了LED、Flash是多大的、USB口是否启用了CDC模式。

ESP32-C3是一颗RISC-V架构的单核芯片，主频160MHz，带2.4G Wi-Fi和Bluetooth LE，最特别的是内部集成了一个USB-Serial-JTAG控制器。这意味着它不像ESP8266那样必须外挂一颗CP2102或CH340才能让电脑识别串口，只要把USB线的D+/D-接到芯片的USB引脚，再把固件里对应的USB CDC功能打开，电脑上就会直接多出一个串口。SuperMini正是利用这一点，把板子做得又小又便宜，省掉了一整颗USB转串口芯片。

代价就是PlatformIO侧的工作量多了。原厂官方开发板的board定义，默认考虑的是原厂参考设计的引脚布局和外设分配，不会把“SuperMini这颗板载LED接在GPIO8”“BOOT按键接在GPIO9”写进去。SuperMini的丝印虽然直接把引脚标成GPIO0到GPIO10，看起来和芯片手册一一对应，但哪些引脚可以做ADC、哪些引脚能安全复用、Flash容量是4MB还是2MB，这些参数都散落在板卡布局和批次说明里，没法只靠芯片型号推断。

2.2 PlatformIO的board JSON怎么生效：每处字段都是编译时参数

PlatformIO在espressif32这个平台下面维护了一个boards目录，里面每个JSON文件对应一块开发板。当你执行pio run时，PlatformIO会先解析这个JSON得到一组默认键值对，然后用platformio.ini里的board_build.*配置去覆盖。JSON里的字段不是装饰品，编译时都会被真实消费：build.f_cpu告诉编译器跑什么主频，build.f_flash告诉底层库Flash初始化速率，build.flash_size决定分区表和Bootloader能用的地址范围，build.mcu直接决定编译目标芯片是esp32c3还是别的型号。

SuperMini支持文件里的board JSON和官方board定义的核心差异，可以用一张表看清：

单看表格会觉得改动很少，但这几个字段只要错一个，行为就差很远。usb_cdc_on_boot不打开，USB口在固件运行时就是纯供电口，连不上监控。flash_size写错，烧录器虽然能写进去，但分区表和文件系统偏移会错位，跑起来要么重启循环，要么格式化分区失败。

还有一个容易忽略的加载顺序问题：PlatformIO查找board文件时，项目级boards目录和用户级~/.platformio/boards目录里的自定义JSON，优先级高于平台内置定义。这就是为什么拿到支持文件后不建议把json直接丢进platformio安装目录去覆盖官方文件，而是单独以esp32c3-supermini.json命名放好，避免同名冲突。JSON的每个字段都不是一次性配置，它们会在项目编译前被合并进构建环境，所以改完json需要重启PlatformIO或者重新执行pio run才能生效。

2.3 USB CDC、烧录协议和Flash容量：支持文件要保证的核心决策

第一件要决策的是USB CDC怎么接管串口。ESP32-C3内部USB控制器可以模拟一个CDC串口，Arduino框架里对应的就是Serial对象。只有在board定义里把usb_cdc_on_boot打开，固件启动时才会把USB口初始化为串口设备，否则USB口在电脑里只是一个JTAG调试接口，你的Serial.println数据会被丢进虚空里。常见做法是把这个开关放在board JSON中，而不是写在每个工程的代码里，省得每个项目都去加编译宏。

第二件是烧录协议。SuperMini底部没有传统ESP8266那种手动拨动的跳线帽，Type-C口接上后，esptool通过DTR和RTS信号组合让芯片自动进入下载模式。JSON里upload.protocol写成esptool，PlatformIO会用espressif官方烧录工具去握手。但如果是劣质USB线或者电脑前置USB口供电不稳，DTR/RTS时序会被打断，现象就是esptool一直打印等待包头。这个坑我在第五部分细说。

第三件是Flash容量，也是这块板历史上最容易翻车的地方。SuperMini常见标注为4MB Flash，但不同批次确实存在2MB和4MB混发的情况，甚至有这批4MB、下批2MB的情况。支持文件按4MB作为默认值写，如果你手上的板子实际是2MB，需要在platformio.ini里加一行board_build.flash_size = 2MB。Flash容量直接决定能做多大OTA分区、能不能同时放下固件和文件系统，项目早期不确认的话，后期加功能时会突然发现固件超过分区上限，那才是真难改。

这三个参数基本决定了“编译能不能过、烧录能不能连上、运行能不能看到日志”。后面的章节就是把这个支持文件拆开，看每一处是怎么落地的。

3. 支持文件内部拆解：board JSON和platformio.ini的关键参数

3.1 board JSON拆解：vendor、build、upload每个字段的用途

把支持文件解压后，核心是一个json文件，文件名字类似esp32c3-supermini.json。打开后你会看到platformio标准的board结构，我挑最关键的字段拆一下：

{ "build": { "arduino": { "usb_cdc_on_boot": true, "usb_jtag_enable": false }, "core": "esp32", "crystal_freq": "40", "f_flash": "80000000L", "f_cpu": "160000000L", "flash_mode": "dio", "flash_size": "4MB", "mcu": "esp32c3", "partitions": "default.csv", "variant": "esp32c3" }, "name": "ESP32C3-SuperMini", "upload": { "maximum_ram_size": 327680, "maximum_size": 4194304, "protocol": "esptool", "require_upload_port": true }, "vendor": "SuperMini" }

这个JSON是支持文件的骨架，build段里每一项都会被编译系统读取。arduino.usb_cdc_on_boot置true，是让USB口枚举成串口的关键。f_flash是Flash时钟频率，80000000L表示80MHz，和C3内置Flash控制器常用配置一致。flash_mode用dio，DIO模式兼容性最好，如果硬件Flash线序或焊接有问题，QIO模式可能出现奇怪的随机重启，DIO虽然在极端性能上稍慢，但作为小批量板卡默认值更稳妥。

flash_size写4MB，对应maximum_size里的4194304字节，编译器和链接器会按这个上限约束固件大小。upload段里的protocol用esptool，require_upload_port意思是烧录时必须显式指定串口，避免pio run -t upload时PlatformIO猜错设备。最容易被忽略的是variant字段，esp32c3这个variant决定Arduino核心会用哪一套管脚定义文件，如果漏了或者写错，即使编译通过，某些引脚功能的底层映射也会错位。

3.2 platformio.ini模板：一份可以直接复制改用的配置

拿到支持文件里的JSON还只是第一步，真正在工程里起作用的是platformio.ini。我一般会直接用这个模板作为起点：

[env:esp32c3_supermini] platform = espressif32 board = esp32c3-supermini framework = arduino monitor_speed = 115200 upload_port = /dev/ttyACM0 board_build.flash_size = 4MB board_build.arduino.usb_cdc_on_boot = true

platform指定用espressif32平台，这是PlatformIO对ESP32全系芯片的支持平台。board就是要加载的JSON文件名，注意这里不要带.json后缀。monitor_speed虽然对USB CDC来说没那么严格，但统一按115200设置可以避免日后切换外部UART时还要改配置。upload_port建议写死，Linux下一般是/dev/ttyACM0，Windows下是COM3或COM4，macOS下是/dev/cu.usbmodemXXXX，不建议用auto，尤其是电脑上同时插了USB转串口模块时，自动选择经常选错。

board_build.flash_size这一行放在platformio.ini里其实是对JSON默认值再做一次确认，好处是同一个工程里如果换了2MB Flash的板子，只需要把这行改成2MB，不用动JSON。board_build.arduino.usb_cdc_on_boot同理，优先用ini里这份，因为工程级配置的改动会被git记录，后期同事拿到代码时一眼能看到这块板子启用了什么特殊配置。

3.3 引脚映射与外设复用：丝印数字和外设的真实对应

SuperMini的丝印直接印的是GPIO编号，这本身很直观，但有几个引脚不是普通IO那么简单。我整理了一张常用引脚对照表，是按大多数批次SuperMini的共性做的：

GPIO8这个LED引脚很低电平点亮，也就是digitalWrite(GPIO8, LOW)时LED亮，HIGH时灭，和很多开发板默认习惯相反。GPIO9是BOOT相关的引脚，如果板上有按键，按住它再复位可以让芯片进入下载模式；但正常用esptool自动下载时不需要手动按。注意不要把GPIO9长期接高电平或低电平再复位，可能误进Bootloader导致固件不启动。还有GPIO11和GPIO12在C3内部连接外部Flash，SuperMini根本没有引出，不用考虑。

提示：如果要用I2C或SPI，别依赖“默认引脚”这种说法。ESP32-C3的外设可以通过GPIO矩阵重映射到大部分引脚，推荐在代码里用Wire.begin(SDA_PIN, SCL_PIN)这种方式显式指定，这块板子迭代批次多，硬件版本之间细节有差异。

4. 实操：装好boards文件、编译上传带日志的点灯程序

4.1 支持文件放哪里：用户级和项目级boards目录

拿到下载包后，里面的JSON文件需要让PlatformIO能找到。两种常见放置方式，一个是全局安装，所有工程都能用，适合机器上多个项目都用SuperMini的人；另一个是项目级放置，跟着代码库走，适合团队协作。命令可以这样执行：

# 方案一：放到用户级boards目录，所有项目可用 mkdir -p ~/.platformio/boards cp esp32c3-supermini.json ~/.platformio/boards/ # 方案二：放到当前项目下的boards目录 mkdir -p boards cp esp32c3-supermini.json boards/

方案一的路径在Linux和macOS下是~/.platformio/boards，Windows下是C:\Users\你的用户名.platformio\boards。注意如果找不到这个目录，先确认PlatformIO有没有正常安装，执行pio --version能看到版本号就说明装好了。方案二把JSON放进项目boards目录，PlatformIO在加载board时会优先于平台内置定义查找这个地方。这样做的优势是同一个仓库里所有同事拉下来后，board配置一致，不会出现两个人用了不同版本的board定义。复制后重启一下VS Code或重开终端，确保平台缓存刷新。

4.2 空工程初始化与第一份platformio.ini配置

新建一个项目目录，在里面初始化一个空工程：

mkdir supermini_test cd supermini_test pio project init --board esp32c3-supermini

初始化完成后，把platformio.ini改成前面第三章那个模板。如果pio project init报错说不认识这个board，说明JSON没有被加载到，回到4.1步骤检查boards目录的位置，或者临时加一行board = esp32c3-supermini再重新执行init。这个报错在Linux下最常见的原因是把JSON放到了当前目录而没有放到项目boards目录，PlatformIO的board搜索路径里并不会包含任意目录。

4.3 点灯加日志：Serial和Serial0在C3上是两个东西

接下来写一个最简单的点灯程序，同时把它当作串口日志的验证程序。新建src/main.cpp，写入：

#include <Arduino.h> #define LED_BUILTIN 8 void setup() { pinMode(LED_BUILTIN, OUTPUT); digitalWrite(LED_BUILTIN, LOW); Serial.begin(115200); delay(100); } void loop() { digitalWrite(LED_BUILTIN, HIGH); Serial.println("[C3] LED ON"); delay(1000); digitalWrite(LED_BUILTIN, LOW); Serial.println("[C3] LED OFF"); delay(1000); }

这段代码里最关键的是Serial.println而不是Serial0.println。ESP32-C3的Arduino核心中，Serial对应的是USB CDC串口，也就是Type-C数据线直接枚举出来的那个串口；Serial0才是芯片的硬件UART0，需要外接USB转TTL才能看到。很多人第一次在这块板上用Serial0去打印，插着Type-C线却什么都看不到，实际上数据走了芯片的UART0引脚，根本没有转成USB。GPIO8作为板载LED，低电平点亮，所以setup里先写LOW确保亮起，再循环里一高一低切换。

4.4 编译上传与串口监控命令

编译和上传可以一条命令完成：

pio run -e esp32c3_supermini -t upload

如果一切正常，终端会看到esptool的烧录进度，然后自动重启芯片。接着打开串口监控：

pio device monitor

在这个监控界面里，你按板子上的RST复位，应该能看到程序输出的[C3] LED ON和[C3] LED OFF。如果monitor里没有输出，先确认设备管理器或ls /dev/ttyACM*里有没有出现新串口；如果串口出现了但没数据，大概率是上一次烧录时CDC没有打开，重新检查platformio.ini里的usb_cdc_on_boot配置。如果串口监控完全打不开，提示设备不存在，多半是串口号写错或者驱动没就绪，可以先退出monitor，把upload_port那行注释掉，再执行pio device list看PlatformIO识别到了什么设备。

5. 避坑与常见问题：烧录失败时先检查这四个地方

5.1 上传卡在等待包头，提示Timed out waiting for packet header

现象：pio run -t upload执行后一直输出Connecting...，最后报超时，固件根本没有写进去。

原因：最常见的是USB线只有充电能力没有数据线，D+/D-根本不通，芯片的USB CDC没有枚举成功。其次是电脑前置USB口供电不足，esptool握手时序被干扰。还有一部分批次SuperMini的自动下载电路需要先手动让芯片复位，如果板子上没有EN按钮，就只能靠拔插USB线来触发。

解决：先把USB线换成一根确认能传数据的线，插到电脑后置USB口。如果还是超时，按住板上的BOOT键不放再重新插线，这时再执行上传，等看到Writing...再松开BOOT键。我一般会在项目里固定一个专门用于测试的USB口，避免Win下多串口设备同时插入导致端口错乱。如果每次都要手动按BOOT，检查JSON里的upload字段是否正常，板子的DTR/RTS自动下载时序可能没有被正确触发。

5.2 编译下载都成功，但分区表和数据总对不上

现象：固件烧进去了，芯片也重启了，但程序里初始化文件系统失败，或者用OTA上传固件时提示空间不足。

原因：board JSON里的flash_size是4MB，但手上的SuperMini实际是2MB Flash版本，或者反过来，板子是4MB但JSON默认写成了2MB，bootloader把整个Flash布局按错容量规划了。ESP32的分区表在编译时就已经写死在固件里，bootloader也是按指定Flash大小生成的，两者与物理容量不一致时，运行阶段就会出现各种地址错乱。

解决：先用esptool读一次真实Flash大小。PlatformIO自带esptool，可以直接执行擦除然后重新烧录：

pio run -t erase

擦除完成后正常重新上传，esptool会打印Chip is ESP32-C3 and Flash size is 4MB这样的信息，以这个打印为准确认物理容量。如果确认是2MB，把platformio.ini里的board_build.flash_size改成2MB，同时把board_build.partitions改成合适的OTA分区表，再重新编译上传。

5.3 插上Type-C后电脑没有任何反应

现象：板子接上电脑，设备管理器或者lsusb里完全看不到新设备，连未知设备都没有。

原因：除了USB线问题外，还有一种情况是这块SuperMini的Type-C座子焊接不良，或者复制时板子本身已经处于深度睡眠或短路状态。少数批次会出现Type-C口只通电、数据引脚没接出来的问题。

解决：先换线试，再换电脑接口试。确认不行的前提下，把这根Type-C口的数据引脚补焊一遍，或者不再依赖板载USB烧录，改用外接USB-TTL模块接GPIO0的UART引脚直接烧录。外接烧录时把USB-TTL的TX接到芯片的RX引脚，RX接芯片的TX引脚，共地，然后按住BOOT键再上电，用esptool走UART协议写固件。这个方案比较折腾，我用来验证板子是不是彻底挂了，很多时候是USB座虚焊。

5.4 通电后一直重启复位循环

现象：程序看起来烧录成功，但板子反复重启，串口监控里不断出现boot信息或者显示Brownout detector was triggered。

原因：第一次碰到都以为是代码问题，实际上绝大多数是供电不足。SuperMini这种小板子没有稳压电路的大电容余量，USB线长、线径细或者电脑USB口功率偏低，芯片内部电压跌落就会触发掉电复位。另一个原因是用GPIO口外接了大电流设备，直接从板子取电导致3.3V不稳。

解决：换一根短线粗线，插机箱后置USB口；如果外接了传感器或显示屏，它的VCC线不要从SuperMini板子引脚取电，单独找一块3.3V稳压板供电，把GND跟SuperMini统一就可以。代码里也可以在setup开头加一个delay(500)，等电源稳定后再初始化外设，虽然不是根治，但很多启动时序敏感的外设会稳定很多。

6. 进阶：用envdump验证board参数，改出适合OTA的分区表

6.1 用envdump确认板级参数真正生效

新拿到一块板卡时，我习惯先跑一遍envdump，把board定义里那些编译参数的最终结果打出来，比对着文档猜快得多：

pio run -e esp32c3_supermini -t envdump | grep -E "FLASH_SIZE|F_CPU|CDC"

输出里能看到编译时实际使用的Flash大小、主频和USB CDC相关宏定义。这一步能在动手写代码前就把板子硬件和固件配置对齐，避免改了JSON但没生效的情况。如果发现FLASH_SIZE跟你期望不一致，优先查platformio.ini里有没有board_build.flash_size覆盖了JSON默认值，板级配置和工程配置都是后写的覆盖先写的。

6.2 自定义分区表，OTA与文件系统共存

SuperMini经常被用来做小体积节点，只烧一个固定固件还不够，我在实际项目里几乎都会给这种板子配上OTA和文件系统。PlatformIO默认的default.csv分区表给应用分区只留了约1.3MB，对ESP32-C3这种小Flash的芯片来说足够跑大多数轻量固件，但如果你想把Web页面或配置JSON放到文件系统，空间就会很紧。我一般会使用一个自定义分区表文件，在项目根目录下创建partitions_supermini.csv：

# name, type, subtype, offset, size nvs, data, nvs, 0x9000, 0x5000, otadata, data, otadata, 0xe000, 0x2000, app0, app, ota_0, 0x10000, 0x1C0000, app1, app, ota_1, 0x1D0000,0x1C0000, spiffs, data, spiffs, 0x390000,0x70000,

然后在platformio.ini里指定使用这份分区表：

board_build.partitions = partitions_supermini.csv

这个布局做了两件事：把应用分成两个OTA槽位，每个约1.75MB，足够放一个带WiFi连接、MQTT、固件升级逻辑的中等固件；文件系统分到了约448KB，用来存Web页面或配置参数。4MB Flash末尾留了一点余量。注意C3没有传统ESP32那种单独的“no OTA”跑法，也可以在分区表里只留一个app槽，但我更推荐两个槽都保留，因为OTA升级时如果新固件损坏，bootloader还能回滚到旧版本，这块板子便宜，返修一次的人工成本早超过板子本身了。

从那以后我每次给新板子建工程，都强制走一遍这个流程：先放好board JSON，再跑envdump确认参数，最后擦除Flash看一次真实容量。看起来多花五分钟，实际上能省掉一整个晚上的“串口玄学”。希望帮到你。

本文还有配套的精品资源，点击获取