{"id":26539753,"url":"https://github.com/dankeboy36/trbr","last_synced_at":"2025-07-25T11:13:11.098Z","repository":{"id":282957834,"uuid":"944914918","full_name":"dankeboy36/trbr","owner":"dankeboy36","description":"TraceBreaker: Decode and analyze ESP backtraces","archived":false,"fork":false,"pushed_at":"2025-03-20T20:31:11.000Z","size":457,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-20T22:02:37.005Z","etag":null,"topics":["esp","esp32","gdb","riscv","xtensa"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dankeboy36.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-08T08:16:18.000Z","updated_at":"2025-03-20T10:58:26.000Z","dependencies_parsed_at":"2025-03-17T21:50:37.954Z","dependency_job_id":null,"html_url":"https://github.com/dankeboy36/trbr","commit_stats":null,"previous_names":["dankeboy36/trace-breaker","dankeboy36/trbr"],"tags_count":0,"template":false,"template_full_name":"dankeboy36/get-arduino-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankeboy36%2Ftrbr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankeboy36%2Ftrbr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankeboy36%2Ftrbr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dankeboy36%2Ftrbr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dankeboy36","download_url":"https://codeload.github.com/dankeboy36/trbr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244885697,"owners_count":20526296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp","esp32","gdb","riscv","xtensa"],"created_at":"2025-03-22T00:18:50.519Z","updated_at":"2025-07-25T11:13:11.080Z","avatar_url":"https://github.com/dankeboy36.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TraceBreaker (`trbr`)\n\n**TraceBreaker** is a simple tool for decoding and analyzing ESP backtraces, supporting ESP32 and ESP8266 platforms.\n\n![trbr](/static/trbr.gif)\n\n## Installation\n\nTo get started, download the latest binary for Windows, macOS, or Linux from the [GitHub release page](https://github.com/dankeboy36/trbr/releases/latest) and unzip it to your preferred location.\n\n\u003e **ⓘ** **TraceBreaker** includes the **[Arduino CLI](https://github.com/arduino/arduino-cli)** as a binary.\n\n## Usage\n\n### Decode Using GDB\n\nDecode stack traces from the specified ELF file directly using GDB:\n\n```sh\ntrbr decode \\\n --elf-path /path/to/elf \\\n --tool-path /path/to/gdb\n```\n\nWhen using `-t, --tool-path`, you can specify `-A, --target-arch`. Otherwise, it defaults to `xtensa`. Valid options include:\n\n- `xtensa`, `esp32c2`, `esp32c3`, `esp32c6`, `esp32h2`, `esp32h4`.\n\n### Decode Using Arduino CLI\n\nDecode stack traces from the specified ELF file directly using the Arduino CLI and the [installed core](https://docs.arduino.cc/learn/starting-guide/cores/):\n\n```sh\ntrbr decode \\\n --elf-path /path/to/elf \\\n --fqbn esp32:esp32:esp32da\n```\n\nWhen using `-b, --fqbn`, you can also include:\n\n- `--arduino-cli-config` Path to the Arduino CLI configuration file (valid only with FQBN)\n- `--additional-urls \u003curls\u003e` Comma-separated list of additional URLs for Arduino Boards Manager (valid only with FQBN)\n\n### Decode Coredump Files\n\nTraceBreaker 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.\n\nThis mode allows you to decode coredump data instead of standard backtrace input.\n\nExample usage:\n\n```sh\ntrbr decode \\\n --elf-path /path/to/elf \\\n --tool-path /path/to/gdb \\\n --input /path/to/coredump/file \\\n --coredump-mode\n```\n\n### Common Options\n\n- `-i, --input \u003cpath\u003e`: Path to the file to read the trace input. If omitted, the tool reads from stdin interactively.\n- `-d, --debug`: Enable debug output for troubleshooting (default: false)\n- `-C, --no-color`: Disable color output in the terminal (env: NO_COLOR)\n- `-h, --help`: Display help for the command\n\n### Security Notice\n\nPlease be aware that the builds for Windows are [not signed](https://github.com/dankeboy36/trbr/issues/7), and those for macOS are [not notarized](https://github.com/dankeboy36/trbr/issues/8).\n\n#### macOS\n\n\u003e ⚠ Please note that this approach is risky as you are lowering the security on your system, therefore we strongly discourage you from following it.\n\nWhen you start `trbr`, a warning will appear:\n\n\u003e “trbr” Not Opened\n\n\u003e Apple could not verify “trbr” is free of malware that may harm your Mac or compromise your privacy.\n\nFollow 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.\n\n### Disclaimer\n\nThis 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](https://github.com/dankeboy36/esp-exception-decoder) 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.\n\nThe 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:\n\n```sh\n% tree .trbr\n.trbr\n└── bin\n    └── arduino-cli\n        └── 1.2.0\n            └── arduino-cli\n```\n\n## API\n\n![NPM Version](https://img.shields.io/npm/v/trbr)\n\n`trbr` provides an API to programmatically decode ESP backtraces, coredump, and resolve tool paths.\n\n#### ESM:\n\n```js\nimport { decode, findToolPath, resolveToolPath } from 'trbr'\n```\n\n#### CommonJS:\n\n```js\nconst { decode, findToolPath, resolveToolPath } = require('trbr')\n```\n\n### Methods\n\n#### `decode`\n\nDecodes the trace content from an ELF file using GDB.\n\n```js\nconst input = 'your trace content'\n\nconst decodeResult = await decode(\n  {\n    elfPath: '/path/to/elf',\n    toolPath: '/path/to/gdb',\n    targetArch: 'xtensa', // optional\n  },\n  input\n)\n```\n\nDecodes an ESP coredump (in [ELF format](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/kconfig.html#config-esp-coredump-data-format))\n\n```js\nconst input = '/path/to/coredump'\n\nconst decodeResult = await decode(\n  {\n    elfPath: '/path/to/elf',\n    toolPath: '/path/to/gdb',\n    targetArch: 'xtensa', // optional\n  },\n  {\n    inputPath: input,\n    coredumpMode: true,\n  }\n)\n```\n\n---\n\n#### `findToolPath`\n\nFinds the GDB tool path in the installed core using the Arduino CLI.\n\n```js\nimport { FQBN } from 'fqbn'\n\nconst toolPath = await findToolPath({\n  arduinoCliPath: '/path/to/arduino-cli',\n  fqbn: new FQBN('esp32:esp32:esp32da'),\n  arduinoCliConfigPath: '/path/to/arduino-cli.yaml', // optional\n  additionalUrls:\n    'https://example.com/package_example_index.json,https://other.org/package_other_index.json', // optional\n})\n```\n\n\u003e **ⓘ** The Arduino CLI runs the [`board details`](https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_board_details/) command to retrieve tool paths.\n\n---\n\n#### `resolveToolPath`\n\nResolves the tool path from the `build_properties` of the [`BoardDetailsResponse`](https://arduino.github.io/arduino-cli/latest/rpc/commands/#boarddetailsresponse).\n\n```js\nimport { FQBN } from 'fqbn'\n\nconst buildProperties = {\n  'build.tarch': 'riscv32',\n  'build.target': 'esp',\n  'tools.riscv32-esp-elf-gdb.path': '/path/to/gdb',\n  // other properties\n}\n\nconst toolPath = await resolveToolPath({\n  fqbn: new FQBN('esp32:esp32:esp32h2'),\n  buildProperties,\n})\n```\n\n---\n\n## License\n\n`trbr` is licensed under the **GNU General Public License v3.0 (GPLv3)**. For more details, check the [LICENSE](LICENSE).\n\n`trbr` includes the Arduino CLI as a binary. Refer to the official [Arduino CLI licensing disclosure](https://github.com/arduino/arduino-cli/blob/a39f9fdc0b416e2b5ccf13438bb001cc05e68db4/README.md?plain=1#L46-L51).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdankeboy36%2Ftrbr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdankeboy36%2Ftrbr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdankeboy36%2Ftrbr/lists"}