ESP Exception Decoder

⚠️ This project is in an early state.

Arduino IDE extension allows you to get a more meaningful explanation of the stack traces and backtraces you encounter on ESP8266/ESP32. This extension is a reimplementation of the well-known ESP8266/ESP32 Exception Stack Trace Decoder tool, which was originally written in Java. The RISC-V decoder implementation was ported from esp_idf_monitor.

⚠️ This extension is not related to the Visual Studio Code extension for Arduino. Please note that this extension does not work in VS Code.

Installation

1. Download the latest extension from the GitHub release page. The filename should be esp-exception-decoder-${VERSION}.vsix, where ${VERSION} is the latest version.
2. Make sure the Arduino IDE is not running. Then, copy the downloaded extension into the plugins folder located in the Arduino IDE's configuration directory. If the plugins folder does not exist, create it.
   • On Windows, it's under %UserProfile%\.arduinoIDE\plugins (typically C:\Users\<username>\.arduinoIDE\plugins where <username> is your Windows username).
   • On Linux and macOS, it's under ~/.arduinoIDE/plugins.

     ⓘ If you encounter issues, refer to the Installation section of the documentation for Arduino IDE 3rd party themes. The steps are very similar.

Update

To update to the latest or a more recent version of the decoder extension, simply copy the new version file into the same plugins folder alongside the current version. The Arduino IDE will automatically use the most recent version of the extension. If desired, you can delete the older version to keep your plugins folder organized.

Usage

1. Open a sketch in the Arduino IDE and verify it.
2. Upload the sketch to your ESP8266/ESP32 board.
3. Open the Serial Monitor view to monitor the output for exceptions.
4. When an exception occurs, open the Exception Decoder terminal:
   • Open the Command Palette using Ctrl/⌘+Shift+P.
   • Type ESP Exception Decoder: Show Decoder Terminal and press Enter.
5. Copy the exception stack trace/backtrace from the Serial Monitor view.
6. Paste the stack trace/backtrace into the Exception Decoder terminal.

   ⓘ For more details on copying and pasting in the terminal, check here.

Hints

• Enable blinking cursors in the decoder terminal by setting "terminal.integrated.cursorBlinking": true.

• Allow pasting in the decoder terminal by setting "terminal.enablePaste": true.

• Adjust the terminal font size with the setting "terminal.integrated.fontSize": 12.

  ⓘ Refer to the Advanced settings documentation of the Arduino IDE for more details.

  ⚠️ Customizing terminal colors with the workbench.colorCustomizations setting is currently unsupported in Eclipse Theia (eclipse-theia/theia#8060). Therefore, this feature is missing from the Arduino IDE.

  ⚠️ Arduino IDE must support path links that contain spaces in the decoder terminal. (eclipse-theia/theia#12643)

  ⚠️ terminal.integrated.rightClickBehavior is not supported in the Arduino IDE. (eclipse-theia/theia#12644)

Development

1. Install the dependencies:

   npm i

   ⚠️ You need Node.js version >=16.14.0.

2. Build the extension:

   npm run compile

   ⓘ Use npm run package to bundle the VSIX for production.

3. Test the extension:

   npm run test

   ⓘ You can run the slow test with npm run test-slow and all tests with npm run test-all.

Hints

• If you are using VS Code for development, you can take advantage of predefined Launch Configurations to debug the extensions and tests. For guidance on how to test VS Code extensions, see the documentation.
• This extension utilizes the vscode-arduino-api to communicate with the Arduino IDE.
• The extension was created from the helloworld VS Code extension template.

Acknowledgments

• Special thanks to @per1234 for his dedication to open-source contributions.
• Thanks to @me-no-dev for the original implementation.