As part of my efforts to debug a crash during an ISR on ESP8266, using the PlatformIO toolchain, I had to figure out how to get the PlatformIO
device monitor tool to decode stack traces printed to the serial console.
For reference, when this crash first happened, I got a printout like this one in my console when the board reset. Not particularly helpful.
It was fairly straightforward to get
platformio device monitor to decode these traces for me, but there were a few things I had to figure out, which I’ll detail here.
While reading this post, recall that the CLI tool
pio is just a shorter name for the
platformio tool. I’ll shorten most
platformio … calls here to
pio …, since that’s what I’m actually typing at my terminal.
platformio device monitor from the project directory
I had previously been running
pio device monitor -e d1_mini -b 115200 from a random terminal window in my home directory. But if you run it from your project’s directory — the same one that contains
platformio.ini — the tool will pick up on settings stored in the
platformio.ini file when you run
pio device monitor.
2. Be sure the
espressif8266 platform is installed and up-to-date
Based on some initial searching, I knew I had to enable the
esp8266_exception_decoder filter, but
pio device monitor … --filter esp8266_exception_decoder gave me an error, something like
If you have problems using this filter, run
pio platform install espressif8266 to make sure the platform is installed, and
pio platform update espressif8266 to ensure it’s up-to-date.
3. Add monitor settings to
In your project’s
monitor_speed = 115200 ; set to the baud rate you pass to Serial.begin(…) monitor_filters = esp8266_exception_decoder, default
mointor_speed is fairly self-explanatory; if you’re using a baud rate other than the default of
9600, you need to tell
pio device monitor what baud rate to use.
pio device monitor:
esp8266_exception_decoder: Decodes ESP8266 crash exceptions
default: Remove typical terminal control codes
4. Build using the debug configuration
By default, PlatformIO builds your project in release mode, which “does not contain symbolic debug information and is optimized for the firmware size or speed.” This means the information needed for exception decoding is missing.
Instead, you need to use the
debug build configuration, which means your project “is compiled with full symbolic debug information and no optimization.”
To do this, add the following to
build_type = debug
It should be possible to set this up for a separate build environment in
platformio.ini and use that environment for debugging, but honestly, I haven’t figured that out yet, and anyway I don’t know well that works with the PlatformIO integration for CLion, my preferred IDE. I found it easiest just to add this line, and I’ll comment/remove it when I’m done.
A word of warning: I had written some comments and commented out a few lines in my
platformio.ini file, and something I did with the
platformio CLI tool erased all my comments. So, note that comments in this file are not necessarily persistent.
pio device monitor
Run your project on the ESP8266 board, using the
debug build type, and then run
pio device monitor from your project directory.
The next time your project crashes, you should — hopefully — get a decoded crash log, which looks like this! That particular stack trace still isn’t quite a smoking gun, but it’ll get you on the right track.