TraceBreaker is a simple tool to decode and analyze ESP backtraces
npm install trbrtrbr)TraceBreaker is a simple tool for decoding and analyzing ESP backtraces, supporting ESP32 and ESP8266 platforms.
!trbr
To get started, download the latest binary for Windows, macOS, or Linux from the GitHub release page and unzip it to your preferred location.
> ⓘ TraceBreaker includes the Arduino CLI as a binary.
Decode stack traces from the specified ELF file directly using GDB:
``sh`
trbr decode \
--elf-path /path/to/elf \
--tool-path /path/to/gdb
When using -t, --tool-path, you can specify -A, --target-arch. Otherwise, it defaults to xtensa. Valid options include:
- xtensa, esp32c2, esp32c3, esp32c6, esp32h2, esp32h4, esp32p4.
Decode stack traces from the specified ELF file directly using the Arduino CLI and the installed core:
`sh`
trbr decode \
--elf-path /path/to/elf \
--fqbn esp32:esp32:esp32da
When using -b, --fqbn, you can also include:
- --arduino-cli-config Path to the Arduino CLI configuration file (valid only with FQBN)--additional-urls
- Comma-separated list of additional URLs for Arduino Boards Manager (valid only with FQBN)
TraceBreaker supports decoding coredump files using the -c, --coredump-mode option. When this option is enabled, you should provide the coredump file path using the -i, --input option.
This mode allows you to decode coredump data instead of standard backtrace input.
Example usage:
`sh`
trbr decode \
--elf-path /path/to/elf \
--tool-path /path/to/gdb \
--input /path/to/coredump/file \
--coredump-mode
- -i, --input : Path to the file to read the trace input. If omitted, the tool reads from stdin interactively.-d, --debug
- : Enable debug output for troubleshooting (default: false)-C, --no-color
- : Disable color output in the terminal (env: NO_COLOR)-h, --help
- : Display help for the command
Please be aware that the builds for Windows are not signed, and those for macOS are not notarized.
#### macOS
> ⚠ Please note that this approach is risky as you are lowering the security on your system, therefore we strongly discourage you from following it.
When you start trbr, a warning will appear:
> “trbr” Not Opened
> Apple could not verify “trbr” is free of malware that may harm your Mac or compromise your privacy.
Follow the instructions from the "If you want to open an app that hasn't been notarized or is from an unidentified developer" section of this page to bypass the security restriction: https://support.apple.com/en-us/HT202491.
This project uses the Arduino CLI as a binary. When you download and use TraceBreaker, you will be using the Arduino CLI for all GDB tool path resolutions based on the Fully Qualified Board Name (FQBN). I rewrote the ESP Exception Decoder extension logic for the Arduino IDE 2.x, where the Arduino CLI is always available. I appreciate the Arduino CLI project and the people working on it, so I decided to reuse as much of their work as possible. It’s fantastic.
The first time trbr requires the Arduino CLI, it will unpack the binary to a temporary location. Specifically, it will unpack to $TMPDIR/.trbr/bin/$ARDUINO_TOOL/$VERSION/$ARDUINO_TOOL, where $ARDUINO_TOOL is arduino-cli and $VERSION is the version that trbr uses. For example:
`sh`
% tree .trbr
.trbr
└── bin
└── arduino-cli
└── 1.2.0
└── arduino-cli
trbr provides an API to programmatically decode ESP backtraces, coredump, and resolve tool paths.
#### ESM:
`js`
import { decode, findToolPath, resolveToolPath } from 'trbr'
#### CommonJS:
`js`
const { decode, findToolPath, resolveToolPath } = require('trbr')
#### decode
Decodes the trace content from an ELF file using GDB.
`js
const input = 'your trace content'
const decodeResult = await decode(
{
elfPath: '/path/to/elf',
toolPath: '/path/to/gdb',
targetArch: 'xtensa', // optional
},
input
)
`
Decodes an ESP coredump (in ELF format)
`js
const input = '/path/to/coredump'
const decodeResult = await decode(
{
elfPath: '/path/to/elf',
toolPath: '/path/to/gdb',
targetArch: 'xtensa', // optional
},
{
inputPath: input,
coredumpMode: true,
}
)
`
---
#### findToolPath
Finds the GDB tool path in the installed core using the Arduino CLI.
`js
import { FQBN } from 'fqbn'
const toolPath = await findToolPath({
arduinoCliPath: '/path/to/arduino-cli',
fqbn: new FQBN('esp32:esp32:esp32da'),
arduinoCliConfigPath: '/path/to/arduino-cli.yaml', // optional
additionalUrls:
'https://example.com/package_example_index.json,https://other.org/package_other_index.json', // optional
})
`
> ⓘ The Arduino CLI runs the board details command to retrieve tool paths.
---
#### resolveToolPath
Resolves the tool path from the build_properties of the BoardDetailsResponse.
`js
import { FQBN } from 'fqbn'
const buildProperties = {
'build.tarch': 'riscv32',
'build.target': 'esp',
'tools.riscv32-esp-elf-gdb.path': '/path/to/gdb',
// other properties
}
const toolPath = await resolveToolPath({
fqbn: new FQBN('esp32:esp32:esp32h2'),
buildProperties,
})
`
---
trbr is licensed under the GNU General Public License v3.0 (GPLv3). For more details, check the LICENSE.
trbr` includes the Arduino CLI as a binary. Refer to the official Arduino CLI licensing disclosure.