TraceBreaker (trbr)

TraceBreaker is a simple tool for decoding and analyzing ESP backtraces

Installation

To get started, download the latest binary from the GitHub release page and unzip it to your preferred location.

ⓘ TraceBreaker includes the Arduino CLI as a binary.

Usage

Decode Using GDB

Decode stack traces from the specified ELF file directly using GDB:

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.

Decode Using Arduino CLI

Decode stack traces from the specified ELF file directly using the Arduino CLI and the installed core:

trbr decode \
 --elf-path /path/to/elf \
 --fqbn esp32:esp32:esp32da

When using -b, --fqbn, you can also include:

• -c, --arduino-cli-config Path to the Arduino CLI configuration file (valid only with FQBN)
• --additional-urls <urls> Comma-separated list of additional URLs for Arduino Boards Manager (valid only with FQBN)

Common Options

• -i, --input <path>: Path to the file to read the trace input instead of stdin (if absent, the CLI runs in interactive mode)
• -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

Security Notice

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.

Disclaimer

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:

% tree .trbr
.trbr
└── bin
    └── arduino-cli
        └── 1.2.0
            └── arduino-cli

API

trbr provides an API for decoding ESP backtraces and resolving tool paths.

ESM:

import { decode, findToolPath, resolveToolPath } from 'trbr'

CommonJS:

const { decode, findToolPath, resolveToolPath } = require('trbr')

Methods

decode

Decodes the trace content from an ELF file using GDB.

const input = 'your trace content'

const decodeResult = await decode(
  {
    elfPath: '/path/to/elf',
    toolPath: '/path/to/gdb',
    targetArch: 'xtensa', // optional
  },
  input
)

console.log(decodeResult)

---

findToolPath

Finds the GDB tool path in the installed core using the Arduino CLI.

const toolPath = await findToolPath({
  toolPathOrFqbn: 'esp32:esp32:esp32da',
  arduinoCliConfig: '/path/to/arduino-cli.yaml', // optional
  additionalUrls:
    'https://example.com/package_example_index.json,https://other.org/package_other_index.json', // optional
})

console.log(toolPath)

ⓘ The Arduino CLI runs the board details command to retrieve tool paths.

---

resolveToolPath

Resolves the tool path from the build_properties of the BoardDetailsResponse.

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,
})

console.log(toolPath)

---

License

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.