The launch.sh menu has 20 numbered options grouped into sections. Numbers always work — letters (s, b, w, g) just expand the visual section.

Group: 🧰 Toolchain (s)

Group: 🔥 Deploy (b)

Group: 🌐 Cyberspace (w)

Group: 📜 Misc

Group: 📡 Git ops (g)

Annotated walk-through of every line in this project's platformio.ini, with explanation and gotchas.

[platformio] section

[env:esp32-c3-devkitm-1] section

Common directives NOT in this project (but useful to know)

RMT — Remote Control Transceiver

Hardware peripheral for generating precise pulse trains without CPU involvement. Originally for IR remotes, but FastLED uses it to drive WS2812 NeoPixels at 800 kHz with sub-150-ns timing — impossible to bit-bang reliably.

The full forensic — including the IDF 4.x ISR re-entry bug that triggered BUG-001 — is in the audit page.

Partition table

Flash memory is divided into named regions. The bootloader reads partitions.bin at offset 0x8000 to know where everything else lives.

# Default Arduino-ESP32 layout (4 MB flash):
nvs       data 0x9000   0x5000     # 20 KB — saved settings
otadata   data 0xe000   0x2000     # 8 KB — OTA pointer
app0      app  0x10000  0x140000   # 1.25 MB — your firmware
app1      app  0x150000 0x140000   # 1.25 MB — OTA backup
spiffs    data 0x290000 0x170000   # 1.4 MB — file system

If you don't need OTA, switch to huge_app.csv (3 MB single app slot). For audio assets, switch to large_spiffs.csv.

USB JTAG/Serial vs UART

The ESP32-C3 Super Mini has native USB — the chip itself implements USB-CDC over its built-in USB JTAG/Serial peripheral. There is NO external UART chip (no CP210x, no CH340).

GPIO strapping pins — gotchas

Some GPIOs have special meaning at boot. Using them for sensors / LEDs without thinking can prevent the chip from booting.

ESP32-C3 SuperMini — board-specific quirks

The exact dev-board this project uses. Reference page: randomnerdtutorials.com / Getting Started with ESP32-C3 Super Mini. Things that bite you on this specific board:

When the ESP32-C3 panics, you get a "Guru Meditation" register dump in the serial monitor. Here's how to turn the hex into source-line info.

The dump structure

Guru Meditation Error: Core 0 panic'ed (Instruction access fault)
Core 0 register dump:
MEPC    : 0x3fc9027c   # where it died
RA      : 0x4038c53c   # return address (where it would have gone)
SP      : 0x3fc8f8d0   # stack pointer at crash
MCAUSE  : 0x00000001   # why it died
MTVAL   : 0x3fc9027c   # offending address (load/store cause)

MCAUSE codes

Address ranges — where it points

Running addr2line

# Linux / macOS / Git Bash:
~/.platformio/packages/toolchain-riscv32-esp/bin/riscv32-esp-elf-addr2line \
    -fipe .pio/build/esp32-c3-devkitm-1/firmware.elf \
    0x4038c53c 0x403801ee 0x4038907e

# Output:
ESP32RMTController::interruptHandler at .../FastLED/.../idf4_rmt_impl.cpp:827
vPortEnterCritical at .../freertos/port/riscv/port.c:246
xPortEnterCriticalTimeout at .../freertos/port/riscv/port.c:198

Common crash signatures

The Web Serial API (W3C) lets a webpage talk directly to USB-serial devices — no plugins, no native install. flash.html and monitor.html use it.

Browser support

Security model

• HTTPS or localhost only. File:// URLs and plain HTTP rejected.
• User gesture required. The port-picker dialog only opens after a real user click.
• Per-origin permission. Once granted, the origin remembers the device for next time.
• One owner at a time. Only one app can hold a serial port. Close PlatformIO monitor before connecting from the browser.

Minimal example

// 1 — request a port (must be in a click handler)
const port = await navigator.serial.requestPort();
await port.open({ baudRate: 115200 });

// 2 — read a stream of bytes
const decoder = new TextDecoderStream();
port.readable.pipeTo(decoder.writable);
const reader = decoder.readable.getReader();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log(value);   // chunk of UTF-8 text
}

// 3 — write
const writer = port.writable.getWriter();
await writer.write(new TextEncoder().encode("hello\n"));
writer.releaseLock();

// 4 — close
await port.close();