Save exception details and stack trace anytime and anywhere the ESP8266 crashes
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples Library now accepts offset and size parameters passed into the constr… Nov 11, 2018
extras
src Returned EEPROM.begins and ends to their rightful place Nov 11, 2018
.gitignore Initial release Aug 14, 2016
.travis.yml Description of examples Aug 16, 2016
LICENSE Initial release Aug 14, 2016
examples.md Library now accepts offset and size parameters passed into the constr… Nov 11, 2018
keywords.txt Initial release Aug 14, 2016
library.json Library now accepts offset and size parameters passed into the constr… Nov 11, 2018
library.properties Fixed incomplete stack trace Aug 18, 2016
quick-start.md Review documentation Aug 19, 2016
readme.md Library now accepts offset and size parameters passed into the constr… Nov 11, 2018

readme.md

EspSaveCrash Build Status

Save exception details and stack trace anytime and anywhere the ESP8266 crashes. Implement it in your sketch in two simple steps.

Overview

Do you face random crashes of ESP8266? Do you have difficulty to capture diagnostic information because module is in remote location? Or maybe module crashes after several hours of operation and it is inconvenient to keep serial monitor open until it fails?

EspSaveCrash is a handy little library that will keep automatically catching and saving crash information to ESP8266 module's flash in case it fails due to exception or software WDT. You will then be able to analyze the crash log and decode the stack trace using ESP Exception Decoder.

You will implement it in your sketch in two simple steps:

  1. Include the library
#include "EspSaveCrash.h"
  1. Declare object
EspSaveCrash SaveCrash;
  1. Print out saved crash details
SaveCrash.print();

To clear existing crash history from the flash use SaveCrash.clear().

Check section Quick Start for sample implementation of this library and tracking down where the program crash happened. More code samples are available in section Examples, that also covers access to saved information remotely with a web browser.

alt text alt text
Quick Start Code Examples

Compatibility

Functionality

  • Registers callback to automatically capture and save crash details
  • Captures several crashes to save them to ESP8266 module's flash
  • Captures exceptions and software WDT restarts (not hardware WDT)
  • The following information is saved:
    • Time of crash using the ESP's milliseconds counter
    • Reason of restart - see rst cause
    • Exception cause - see EXCCAUSE
    • epc1, epc2, epc3, excvaddr and depc
    • Stack trace in format you can analyze with ESP Exception Decoder
  • Automatically arms itself to operate after each restart or power up of module
  • Saves crash details within defined flash space and then stops

Example output of SaveCrash.print():

alt text

Examples

Library comes with example sketches that let you trigger some exceptions and see how to visualize saved data.

Please check separate section how to use example sketches and what particular functionality they provide.

Tested With

Arduino Core

Programming Environment

  • Arduino IDE 1.6.9 portable version running on Windows 7 x64
  • PlatformIO IDE 1.3.0 CLI 2.11.0 running on Windows 7 x64
  • Visual Micro 1606.17.10 with Visual Studio Community 2015 running on Windows 7 x64

Installation

  • Arduino IDE - use Library Manager in Arduino IDE and search for EspSaveCrash.
  • PlatformIO IDE - use PlatformIO's Library Manager. In particular execute pio lib install 376.
  • Visual Micro - installation procedure is the same as for Arduino IDE above.

Contribute

Feel free to contribute to the project in any way you like!

If you find any issues with code or descriptions please report them using Issues tab above.

Author

krzychb

Credits

  • Preparation of this library has been inspired by issue #1152 in esp8266 / Arduino repository.
  • Development was possible thanks to Ivan Grokhotkov, who clarified how to register a crash callback and suggested to save crash information on flash.
  • Actual implementation of library has been done thanks to djoele who provided first working code and suggested to convert it into general functionality.

License

GNU LESSER GENERAL PUBLIC LICENSE - Version 2.1, February 1999