ESP Crash Decoder — VS Code Extension
Decode ESP32 crash dumps directly from the serial port in VS Code.
Powered by TraceBreaker (trbr).
Designed to work with pioarduino.
Features
- Serial Monitor — Connect to any serial port, view output in real-time
- Automatic Crash Detection — Detects Guru Meditation Errors, backtraces, panics, asserts
- Crash Decoding — Decodes stack traces using
addr2line/GDB from espressif toolchains
- PlatformIO Integration — Auto-detects
firmware.elf and toolchain from .pio/build/
- Click-to-Navigate — Click on decoded file:line references to open source files
- Register Display — Shows CPU register values at the time of crash
- Multi-Arch Support — Xtensa (ESP32/S2/S3) and RISC-V (ESP32-C3/C6/H2)
Quick Start
- Open a pioarduino project in VS Code
- Build your firmware (
pio run)
- Run command: ESP Decoder: Open Serial Monitor & Crash Decoder
- Select serial port and connect
- The ELF file is auto-detected from
.pio/build/
- Crash dumps are automatically detected and decoded
Commands
| Command |
Description |
ESP Decoder: Open Serial Monitor & Crash Decoder |
Open the main monitor panel |
ESP Decoder: Select Serial Port |
Choose which serial port to use |
ESP Decoder: Select Baud Rate |
Set the communication speed |
ESP Decoder: Connect Serial Port |
Connect to the selected port |
ESP Decoder: Disconnect Serial Port |
Disconnect the serial port |
ESP Decoder: Select ELF File |
Choose ELF file for decoding |
ESP Decoder: Clear Output |
Clear serial and crash data |
Settings
| Setting |
Default |
Description |
esp-decoder.defaultBaudRate |
115200 |
Default baud rate |
esp-decoder.autoDetectElf |
true |
Auto-detect ELF from PlatformIO builds |
esp-decoder.elfPath |
"" |
Manual ELF file path |
esp-decoder.toolPath |
"" |
Manual GDB/addr2line path |
esp-decoder.targetArch |
auto |
Target architecture (auto, xtensa, riscv32) |
esp-decoder.serialMonitor.maxLines |
5000 |
Max lines in serial output |
esp-decoder.serialMonitor.autoscroll |
true |
Auto-scroll on new data |
How It Works
- Serial data is received and displayed in the Serial Monitor tab
- Incoming lines are analyzed for crash patterns (panic messages, backtraces, register dumps)
- When a crash block is detected, it appears in the Crash Events tab
- If an ELF file is configured, the crash is automatically decoded:
- Backtrace addresses are resolved to function names and source locations
- Stack memory is resolved to function names and source locations
- Register values are extracted and displayed
- Fault information (cause, core, address) is shown
- Clicking on source file references opens the file at the correct line
pioarduino Setup
The extension auto-detects:
- ELF file:
<workspace>/.pio/build/<env>/firmware.elf
- Toolchain: From packages (
~/.platformio/packages/)
- Architecture: From board configuration in
platformio.ini
Make sure you have built your project at least once before connecting the monitor.
Building the Extension
cd vscode-extension
npm install
npm run build
npm run package # Creates .vsix file
Installing
code --install-extension esp-decoder-0.1.0.vsix
Or install from the Extensions sidebar: "Install from VSIX..."
Requirements
- VS Code 1.85+
- Node.js 18+ (for the
serialport native module)
- pioarduino installed in the workspace
- A built firmware (
.elf file)
License
GPL-3.0 — same as trbr
Copyright
Jason2866
| |
