ESP32-C3 Robot App

// objective: understand the rig before touching it

// objective: know which file does what

// objective: stop being mystified by .ino files

An .ino file is C++ with two cheats:

void setup() {
    pinMode(LED, OUTPUT);
    blink();          // OK in .ino
}
void loop() { delay(1000); }
void blink() {
    digitalWrite(LED, HIGH);
}

#include <Arduino.h>   // injected
void blink();          // injected

void setup() {
    pinMode(LED, OUTPUT);
    blink();
}
void loop() { delay(1000); }
void blink() {
    digitalWrite(LED, HIGH);
}

// objective: read the build orders

[env:esp32-c3-devkitm-1]
platform     = espressif32 @ 6.7.0   ; PINNED — ESP-IDF 5.1, fixes RMT bug
board        = esp32-c3-devkitm-1    ; pin map + flash size
framework    = arduino               ; activates Arduino API
monitor_speed = 115200               ; serial baud rate

build_flags =
    -D FASTLED_RMT_MAX_CHANNELS=1    ; C3 has only 2 RMT slots
    -D FASTLED_RMT_BUILTIN_DRIVER=1  ; use IDF's tested RMT driver

lib_deps =
    RemoteXY                         ; phone control via BLE
    fastled/FastLED @ ^3.7.0         ; NeoPixel (version pinned)
    madhephaestus/ESP32Servo         ; servo library
    adafruit/Adafruit GFX Library    ; OLED graphics
    adafruit/Adafruit SSD1306        ; OLED driver

// objective: stop typing commands. Press numbers.

Accordion menu: press a letter (s, b, w, g) to expand a section, or just type the number directly. Numbers always work whether expanded or not.

// objective: install everything, transparently

Pick option 0. The launcher runs four automatic levels:

// objective: see what happens when you press "compile"

Option 10 = full flash = compile + upload + monitor in one shot.

// objective: know what gets written where

The 3 binaries are written at fixed offsets in the chip's 4 MB flash:

// objective: force the chip into bootloader mode manually

// objective: let anyone flash via Chrome — no terminal required

// objective: diagnose like a pro

pacman -Syu
pacman -S mingw-w64-ucrt-x86_64-python mingw-w64-ucrt-x86_64-python-pip

// objective: turn a wall of hex into a function name

When the ESP32-C3 panics, you get a "Guru Meditation" register dump. Those 0x4038xxxx addresses look like noise — but they're real instructions in your firmware. The addr2line tool maps them back to filename.cpp:line_number. This is the move that solved BUG-001.

Three registers to read first:

• MEPC — where the CPU was when it died. 0x4038xxxx = inside flash code (decode!). 0x3fc8xxxx = inside RAM = corrupted return address.
• RA — where it was returning to. Decode this to find the caller.
• MCAUSE — why it died. 0x01 = invalid code jump. 0x05/0x07 = bad memory access. 0x02 = illegal instruction.

// run 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 0x40389094

# Output:
_global_interrupt_handler at .../riscv/interrupt.c:66
ESP32RMTController::interruptHandler at .../idf4_rmt_impl.cpp:827
vPortEnterCritical at .../freertos/port/riscv/port.c:246

// reading the stack

• Repeating frames at fixed offsets (e.g. every 0xC0 bytes) = recursion. Intentional or runaway (stack overflow).
• Counter decrementing across frames = loop variable, often recursion depth.
• Same RA repeated across many frames = function calling itself (or being re-interrupted).

That's exactly what BUG-001 looked like: ESP32RMTController::interruptHandler repeating 9× with 192-byte frames = the ISR re-entering itself before iret, overflowing the stack in milliseconds.

// the workflow

// objective: skip the menu when you know what you're doing

# compile
python -m platformio run

# upload
python -m platformio run -t upload --upload-port COM3

# erase chip
python -m esptool --chip esp32c3 --port COM3 erase_flash

# serial monitor
python -m platformio device monitor -b 115200 --port COM3

# clean
python -m platformio run -t clean

# update everything
python -m platformio pkg update

If pio is on PATH, drop the python -m prefix.

// objective: build the same code without PlatformIO

The source in 01_src/ is plain Arduino C++ — Arduino IDE 2.x can compile it too. You'll redo the config by hand (no platformio.ini in IDE land).

Setup checklist

What won't carry over from PlatformIO