Debugging

Debugging

Unwanted Reboots

The device restarts itself if fatal errors or unhandled exceptions occur.

Using Platformio Monitor

When building a firmware yourself, you might be able to start the Platformio monitor after writing the firmware image. Visual Studio Code does that for you by default. If an unwanted reboot occurs, the backtrace will automatically be filtered and translated to lines of code.

Capturing the Serial Output

Many users do not build their firmware themselves, or can attach the Platformio monitor to the device. In such instances, it is advised to find a way to capture the device's serial log. The web console output is not conclusive. Tools like minicom -C <capturefile> may be used on Linux, or Putty on Windows, which also has an option to write a log file.

The log will contain valuable information. Not all errors are equal, but a backtrace should always be printed to the serial console as part of the error handling before the device actually reboots. This backtrace tells what functions were involved when the error occurred.

Additional Required Information

• The commit hash the firmware was built from that produced the backtrace.
• The platform the firmware was built for, like generic_esp32.

Decoding the Backtrace

The backtrace contains addresses of the functions that most recently were called. These can be translated using addr2line, but require a compatible ELF file. That file is created as part of the default platformio build and can be (re)build for the commit and platform in question, if required.

A tool like schlimmchen's ESP backtrace decoder can make it easier to decode the whole backtrace. It requires the platform, backtrace file, and ELF file as input, searches the addr2line utility that was installed by Platformio, and feeds the addresses to addr2line.