ESP8266 + PlatformIO Serial Console Monitoring with Exception Decoding
Part of the Getting Started with ESP8266 + Arduino series.
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.
1. Run 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 Error: 'esp8266_exception_decoder'.
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 platformio.ini
In your project’s platformio.ini, add:
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.
monitor_filters tells pio device monitor:
esp8266_exception_decoder: Decodes ESP8266 crash exceptionsdefault: 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 platformio.ini:
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.
5. 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.
(I have another blog post that works through debugging this crash.)