Diagnostics and Error reporting

Diagnostics and Error Reporting

Error Recording

Using the built in Diagnostics code

Verbose error reporting can be obtained by uncommenting the #define RUNDIAGNOSTIC line in SPIFlash.h and loading and running the Diagnostics.ino example.

Note: Verbosity is dependent on the type of MCU on your board and increases when the MCU might have more resources to spare.

---

Writing user specific code

error(_verbosity)

• Calling this function returns the (8-bit) error code generated by the function called immediately before this is called. If enough system resources are available, the optional VERBOSE argument can be used and a verbose troubleshooting report is printed to Serial. Refer to Diagnostics & Error reporting for further details.

• Calling the error() function (v2.4.0 onwards) will return the error code causing your code to lock up (if a defined error has occurred). If no error has occurred, the function will return 0.

  This enables a user to insert error checks as required :

  #include <SPI.h>
  #include <SPIFlash.h>
  
  SPIFlash flash;
  
  void setup() {
      flash.begin();
      if (flash.error()) {
          /*Insert troubleshooting code of choice*/
       }
  }
  
  void loop() {
      /* Rest of code */
  }
  

• As of v2.6.0 error() now takes an optional argument 'VERBOSE'. By default the verbosity argument is set to 'false' and calling error() still returns the latest error code as an unsigned byte (or 0 if no error has occured). However, running error(VERBOSE) will not only return the latest error code, but will also print it to serial. This - especially in boards with resources to spare - will result in a detailed error report printed to serial. This can be very useful in many instances. An example is given below:

  In this example begin() returns a boolean value to indicate establishment of successful comms with the flash chip. The following code is now more efficient than pre-v2.6.0, as it enables the user to catch errors where they happen.

  #include <SPI.h>
  #include <SPIFlash.h>
  
  SPIFlash flash;
  
  void setup() {
      if (!flash.begin()) {
          flash.error(VERBOSE);
          /*Insert other troubleshooting code of choice*/
       }
  }
  
  void loop() {
      /* Rest of code */
  }
  

---

Diagnostic functions

libver(b1, b2, b3)

• Returns the library version into three bytes that are supplied as arguments to the function.

• b1, b2 & b3 contain the value of the library's internal variables LIBVER, LIBSUBVER, BUGFIXVER.

  For example:

  ...includes...
  ...constructor...
  
  void setup() {
    ...
    flash.begin();
    uint8_t ver, subver, bugfix;
    flash.libver(ver, subver, bugfix);
    Serial.println("The library version in use is %d.%d.%d", ver, subver, bugfix);
    ...
  }
  ...
  

• This function should be used to determine the version of the library being used before raising an issue on GitHub.

functionRunTime()

• This function can only be called if #define RUNDIAGNOSTICS is uncommented in SPIFlash.h

• Returns the time taken to run a function. Must be called immediately after a function is run as the variable returned is overwritten each time a function from this library is called. Primarily used in the diagnostics sketch included in the library to track function time.