/esp-exception-decoder

ESP8266/ESP32 Exception Decoder Extension for the Arduino IDE

Primary LanguageTypeScriptMIT LicenseMIT

ESP Exception Decoder

Tests

⚠️ This project is in an early state.

Arduino IDE extension lets you get a more meaningful explanation of the stack traces and backtraces you get on ESP8266/ESP32. This extension is the reimplementation of the famous ESP8266/ESP32 Exception Stack Trace Decoder tool, written in Java.

ESP8266/ESP32 Exception Decoder Extension

⚠️ This extension has nothing to do with the Visual Studio Code extension for Arduino. This extension does not work in VS Code.

Installation

  • Download the latest extension from the GitHub release page. The asset filename is esp-exception-decoder-${VERSION}.vsix, where ${VERSION} is the latest version.
  • When the Arduino IDE is not running, copy the downloaded extension into the folder named plugins folder under Arduino IDE's configuration folder. If the plugins folder does not exist, create it.
    • On Windows, it's under C:\Users\<username>\.arduinoIDE\plugins where <username> is your Windows username.
    • On Linux and macOS, it's under ~/.arduinoIDE/plugins.

      ℹ️ If you get stuck, follow the Installation section of the documentation of the Arduino IDE 3rd party themes. The procedure is the same.

Usage

  • Open a sketch in the Arduino IDE and verify it.
  • Upload the sketch to an ESP8266/ESP32 board.
  • Open the Serial Monitor view and monitor the output for exceptions.
  • When you get an exception, open the Exception Decoder terminal:
    • Open the Command Palette with Ctrl/⌘+Shift+P,
    • Type ESP Exception Decoder: Show Decoder Terminal and
    • Press Enter.
  • Copy the exception stack trace/backtrace from the Serial Monitor view.
  • Paste the stack trace/backtrace to the Exception Decoder terminal.

    ℹ️ See more on copy and paste in the terminal here.

ESP Exception Decoder in Action

Hints

  1. You can enable blinking cursors in the decoder terminal with the "terminal.integrated.cursorBlinking": true setting.

  2. The "terminal.enablePaste": true setting enables pasting to the decoder terminal with the keyboard.

  3. You can tune the terminal font size with the setting "terminal.integrated.fontSize": 12.

    ℹ️ Reference the Advanced settings documentation of the Arduino IDE for more details.

    ⚠️ Customizing the terminal colors with the workbench.colorCustomizations setting is yet to be supported by Eclipse Theia (eclipse-theia/theia#8060). Hence, this feature is missing from the Arduino IDE.

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

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

Development

  1. Install the dependencies

    npm i

    ⚠️ You need Node.js >=16.14.0.

  2. Build the extension

    npm run compile

    ℹ️ Execute npm run package if you want to bundle the VSIX for production.

  3. Test the extension

    npm run test

    ℹ️ You can run the slow test with the npm run test-slow and all the tests with the npm run test-all command.

Hints

  • If you use VS Code for development, you can use the predefined Launch Configurations to debug the extensions and the tests. See how to test VS Code extensions.
  • This extension uses the vscode-arduino-api to communicate with the Arduino IDE.
  • This extension was built from the helloworld VS Code extension template.

Acknowledgments