Arduino Debugger  1.0
A C++ Library to add debugging features via the Arduino IDE's Serial Moniter
Debugger Class Reference

#include <Debugger.h>

Inherited by DebuggerF.

Public Member Functions

 Debugger (bool is8Bit)
 Debugger Constructor. More...
 
void turnOff ()
 Turn debugging info off. More...
 
void turnOn ()
 Turn debugging info on. More...
 
void breakpoint ()
 Set a breakpoint with no name. More...
 
void breakpoint (char name[])
 Set a breakpoint with a label to help indentify which breakpoint in the program is being viewed. More...
 
void repeat ()
 Display the value of hardware pins and watched variables & update the default counter[0]. More...
 
void repeat (byte value)
 Display the value of hardware pins and watched variables and update the default counter. More...
 
void repeat (byte id, byte value)
 Display the value of hardware pins and watched variables and update the chosen counter. More...
 
void repeat (byte id, byte value, byte data)
 Display the chosen data information and update the chosen counter. More...
 
void setCounter (byte id, byte value)
 Set a chosen counter's maximum value. More...
 
void print ()
 Display the value of hardware pins and watched variables, only once. More...
 
void print (char name[])
 Display the value of hardware pins and watched variables, only once. More...
 
void print (char name[], byte data)
 Display the chosen data information. More...
 
void add (void *var_ptr, Type type, char var_name[])
 Add a variable to the debugger's watch list. More...
 
void remove (char var_name[])
 Remove a variable to the debugger's watch list. More...
 
virtual void displayVariables ()
 Display all variables being watched with their current values. More...
 
virtual void updateVariables ()
 Prompt the user for the value to update the chosen variable to. More...
 
void displayPins ()
 Display current Digital/Analog value of all pins. More...
 
void displaySubsetPins ()
 Display current Digital/Analog value for the subset of pins. More...
 
void setSubsetPins (byte digital_pins[], byte size_d, byte analog_pins[], byte size_a)
 Set a subset of Digital/Analog pins to display to the user. More...
 
void resetSubsetPins ()
 No longer use a subset list of pins. More...
 
void updatePins (bool displayAll)
 Prompt the user for the value to update the digital pin to. More...
 
long getNumber (bool &valid, Type type)
 Retrieve a number from the user and ensure it is both valid and fits within a set number of bytes. More...
 
char getChar ()
 Retrieve a single character from the user. More...
 
bool getBool (bool &valid)
 Retrieve a boolean from the user. More...
 
void pause ()
 Pause the currently running Arduino program. More...
 
void clearScreen ()
 Clear the screen on Serial Monitor. More...
 
void clearBuffer ()
 Clear the Serial Buffer. More...
 
void drawStars ()
 Print a series of asterisks on the Serial monitor. More...
 

Protected Member Functions

void printName (char name[])
 Display an array variable's name. More...
 
byte getSize (char name[])
 Parse the size of an array from it's name. More...
 
virtual void displayArray (Variable var)
 Display an array variable's data. More...
 
virtual void updateArray (Variable var)
 Prompt the user for the value to update the chosen index's value to. More...
 
byte getSelection ()
 Retrieve a menu selection via the Serial Monitor. More...
 
int timedPeek ()
 Perform a Serial peek with a set timeout period (1 second) More...
 

Protected Attributes

bool _is8Bit
 This boolean helps determine if the microcontroller uses 8-Bit or 32-Bit registers. More...
 
bool debuggingIsOn = true
 
Variable var_watch [10]
 Holds information on the variable's being tracked. More...
 
byte top_var_watch = 0
 References max number of variables currently being watched. More...
 
bool usePinList = false
 Set to true by setPins() and allows the debugger to show a subset of pins. More...
 
byte digital_size = 0
 Number of digital pins in the subset. More...
 
byte analog_size = 0
 Number of analog pins in the subset. More...
 
byte digital_pins [10]
 Array listing the subset of digital pins. More...
 
byte analog_pins [10]
 Array listing the subset of analog pins. More...
 
byte counters [5] = {0,0,0,0,0}
 Allows for 5 individual update counters. More...
 
byte counters_max [5] = {0,0,0,0,0}
 Tracks the maximum value for each counter. More...
 

Constructor & Destructor Documentation

◆ Debugger()

Debugger::Debugger ( bool  is8Bit)

Debugger Constructor.

This constructor will set the is8Bit boolean to determine if the microcontroller uses 8Bit or 32Bit registers

Parameters
is8BitTrue - 8Bit | False - 32Bit

Member Function Documentation

◆ add()

void Debugger::add ( void *  ptr,
Type  type,
char  name[] 
)

Add a variable to the debugger's watch list.

A watched variable can be viewed or updated via the breakpoint method. The update method will only display the value of the variables added.

Parameters
ptrThe memory location of a variable being watched
typeThis is an enum representing the variable's data type
nameThe name of variable being watched

◆ breakpoint() [1/2]

void Debugger::breakpoint ( )

Set a breakpoint with no name.

The breakpoint method will provide a menu to the user so that they can view & update the systems:

  • Hardware Pins
  • Watched Variables

◆ breakpoint() [2/2]

void Debugger::breakpoint ( char  name[])

Set a breakpoint with a label to help indentify which breakpoint in the program is being viewed.

The breakpoint method will provide a menu to the user so that they can view & update the systems:

  • Hardware Pins
  • Watched Variables
Parameters
nameA string for labeling the breakpoint.

◆ clearBuffer()

void Debugger::clearBuffer ( )

Clear the Serial Buffer.

This method will remove any characters within the Serial Buffer

◆ clearScreen()

void Debugger::clearScreen ( )

Clear the screen on Serial Monitor.

This method will "clear" the screen by feeding a series of newlines to move the location in the Serial Monitor to be further down.

◆ displayArray()

void Debugger::displayArray ( Variable  var)
protectedvirtual

Display an array variable's data.

This method will display all of the values inside of an array variable.

Warning
This implementation does not support floats. Floats are handled by DebuggerF's implementation of this method
This method does not provide data protection. It cannot determine if it is viewing data outside the array! I.e. no out-of-bounds errors will be given like in Java. Ensure that the size listed in the arrays name (varName_SIZE) is correct

Reimplemented in DebuggerF.

◆ displayPins()

void Debugger::displayPins ( )

Display current Digital/Analog value of all pins.

This method will display the current state of all Digital & Analog Pins. Analog Pin states range from 0-1023. Digital Pins have 3 potential states:

  • HIGH (Power In)
    • Receiving power in
  • HIGH
    • Providing power out
  • LOW
    • No Power

The method also allows for the state of a Digital Pin to be updated (HIGH/LOW).

Note
Currently, this method does not supported viewing/updating PWM values.

◆ displaySubsetPins()

void Debugger::displaySubsetPins ( )

Display current Digital/Analog value for the subset of pins.

This method will display the current state of the Digital & Analog Pins referenced in the current subset. Analog Pin states range from 0-1023. Digital Pins have 3 potential states:

  • HIGH (Power In)
    • Receiving power in
  • HIGH
    • Providing power out
  • LOW
    • No Power

The method also allows for the state of a Digital Pin to be updated (HIGH/LOW).

Note
If digital_size is 0, then the digital pins will not be displayed. If analog_size is 0, then the analog pins will not be displayed.

◆ displayVariables()

void Debugger::displayVariables ( )
virtual

Display all variables being watched with their current values.

This method will display each of the variables (w/ their values) that have been added to the watch list (via add() method).

Warning
This implementation does not support floats. Floats are handled by DebuggerF's implementation of this method
Note
This method uses the displayArray() method to display any array variables.

Reimplemented in DebuggerF.

◆ drawStars()

void Debugger::drawStars ( )

Print a series of asterisks on the Serial monitor.

◆ getBool()

bool Debugger::getBool ( bool &  valid)

Retrieve a boolean from the user.

This method will read an ASCII string from the Serial port and convert it, if possible, to a boolean value. This method will set valid to false if the entry can not be converted to True or False.

Warning
The validation is very simple. Only the first character is checked and all others are truncated from the Serial buffer. This means the method only checks for F/f or T/t. So if you enter "Today" this will be converted to the boolean value true. This was done to simplify the logic but does allow for invalid inputs from the user.
Parameters
valid- a boolean (passed by reference) to check if the value retrieved was valid(true) or invalid(false)
Returns
bool - The boolean representation of the user's entry.

◆ getChar()

char Debugger::getChar ( )

Retrieve a single character from the user.

This method will read an ASCII number from the Serial port

Note
No validation is performed. All characters are considered valid for this method. This could mean returning an ASCII Carriage Return or New Line.
Returns
char - The character entered by the user

◆ getNumber()

long Debugger::getNumber ( bool &  valid,
Type  type 
)

Retrieve a number from the user and ensure it is both valid and fits within a set number of bytes.

This method will read an ASCII number from the Serial port using Arduino'saves Serial Library. This method checks for valid values on 8-Bit & 32-Bit microcontrollers:

  • 8-Bit:
    • Int (2 Bytes)
    • Long (4 Bytes)
  • 32-Bit:
    • Int (4 Bytes)
    • Long (8 Bytes)
Note
If the converted number causes overflow or does not fit within the set number of bytes (parameter), this method will set the parameter valid to false.
Parameters
valid- a boolean (passed by reference) to check if the value retrieved was valid(true) or invalid(false)
type- The type of number being used
Returns
long - The number entered by the user

◆ getSelection()

byte Debugger::getSelection ( )
protected

Retrieve a menu selection via the Serial Monitor.

This method will prompt the user for a menu selection and allow the user to either enter a numeric selection or quit the menu with Q or q.

Note
This menu allows for a maximum value of 253. 255 is a conversion of the ASCII letter Q and 254 is used to denote an invalid number has been entered. An invalid entry is a non-numeric value ("Hello!") or a number less than 0 (negative) or greater than 253.
Returns
byte The user's menu selection

◆ getSize()

byte Debugger::getSize ( char  name[])
protected

Parse the size of an array from it's name.

This method will parse an array variable's size from the Variable.name attribute. The expected format for array names is as follows:

varName_SIZE

An example of an array name would be:

int data_entries = {3, 2, 1};

Formatted name: data_entries_3

Warning
If no underscore is found, then an error message will be displayed.

◆ pause()

void Debugger::pause ( )

Pause the currently running Arduino program.

This method will pause the arduino program and wait until the user enters a value via the Serial port to continue

Note
This method requires the Serial port to have a connection in order to work correctly.

◆ print() [1/3]

void Debugger::print ( )

Display the value of hardware pins and watched variables, only once.

This method will display the current state of the board's hardware pins and current value for variables added to the watch list. If a subset of pins has been chosen, then only the current state for subset will shown. This method does not pause the running program.

Note
This method does not pause the running Arduino Program

◆ print() [2/3]

void Debugger::print ( char  name[])

Display the value of hardware pins and watched variables, only once.

This method will display the current state of the board's hardware pins and current value for variables added to the watch list. If a subset of pins has been chosen, then only the current state for subset will shown. This method does not pause the running program.

Note
This method does not pause the running Arduino Program
Parameters
name- An identifier for where the print statement has been placed in the running program

◆ print() [3/3]

void Debugger::print ( char  name[],
byte  data 
)

Display the chosen data information.

This method will display the chosen information based on the constants VARIABLES (0), PINS (1), and ALL_DATA (2). This allows the programmer to view only the variables in the watchlist, the state of the hardware pins (subset of pins displayed if set), or both sets of information.

Warning
The data parameter must be valid entry (0-2), otherwise no information will be displayed, only a warning message
Parameters
name- An identifier for where the print statement has been placed in the running program
data- the type of information to display.

◆ printName()

void Debugger::printName ( char  name[])
protected

Display an array variable's name.

This method will parse an array variable's name from the Variable.name attribute. The expected format for array names is as follows:

varName_SIZE

An example of an array name would be:

int data_entries = {3, 2, 1};

Formatted name: data_entries_3

Warning
If no underscore is found, then an error message will be displayed. Also, this method does not verify that there is a number after the underscore. It only trims the variable name to remove the last underscore and the characters after it.

◆ remove()

void Debugger::remove ( char  var_name[])

Remove a variable to the debugger's watch list.

This method will remove a variable from the watch list based on its name.

Warning
This method requires an exact match and is case sensitive.
Parameters
var_nameThe name of variable being removed

◆ repeat() [1/4]

void Debugger::repeat ( )

Display the value of hardware pins and watched variables & update the default counter[0].

This method is hard coded to 3 iterations.

This method will display the current state of the board's hardware pins and current value for variables added to the watch list. If a subset of pins has been chosen, then only the current state for subset will shown. This method then decrements the default counter [0]. If the default counter reaches 0, then the Serial Monitor will be paused and the counter will be reset.

◆ repeat() [2/4]

void Debugger::repeat ( byte  value,
byte  id 
)

Display the value of hardware pins and watched variables and update the chosen counter.

This method will display the current state of the board's hardware pins and current value for variables added to the watch list. If a subset of pins has been chosen, then only the current state for subset will shown. This method then decrements the chosen counter. If the chosen counter reaches 0, then the Serial Monitor will be paused and the counter will be reset.

Parameters
value- Value for the chosen counter
id- index of the chosen counter

◆ repeat() [3/4]

void Debugger::repeat ( byte  value,
byte  id,
byte  data 
)

Display the chosen data information and update the chosen counter.

This method will display the chosen information based on the constants VARIABLES (0), PINS (1), and ALL_DATA (2). This allows the programmer to view only the variables in the watchlist, the state of the hardware pins (subset of pins displayed if set), or both sets of information. The chosen counter is also decremented and if it reaches 0 then the Serial Monitor will be paused and the counte reset.

Warning
The id is validated and must be a valid index for the counters_max array.
The data parameter must be valid entry (0-2), otherwise no information will be displayed, only a warning message
Parameters
value- Value for the chosen counter
id- the index of the chosen counter
data- the type of information to display.

◆ repeat() [4/4]

void Debugger::repeat ( byte  value)

Display the value of hardware pins and watched variables and update the default counter.

This method will display the current state of the board's hardware pins and current value for variables added to the watch list. If a subset of pins has been chosen, then only the current state for subset will shown. This method then decrements the default counter [0]. If the default counter reaches 0, then the Serial Monitor will be paused and the counter will be reset.

Parameters
value- Value for the default (0) counter

◆ resetSubsetPins()

void Debugger::resetSubsetPins ( )

No longer use a subset list of pins.

This method will turn of the subset feature.

Note
This method does not actually remove the subset of pins. Instead it flips a boolean (usePinList) to determine if a subset of pins should be displayed. This means the arrays digital_pins and analog_pins are not modified.

◆ setCounter()

void Debugger::setCounter ( byte  id,
byte  value 
)

Set a chosen counter's maximum value.

This method will set the number of times a specific counter can be called before pausing the Serial Monitor.

Note
No validation is performed on value. All byte values are considered valid, from 0 to 255.
id is validated and must be a possible index for the counters_max array
Parameters
id- The index of the counter being set
value- The max value for the chosen counter

◆ setSubsetPins()

void Debugger::setSubsetPins ( byte  d_pins[],
byte  size_d,
byte  a_pins[],
byte  size_a 
)

Set a subset of Digital/Analog pins to display to the user.

This method will set the digital_pins & analog_pins member arrays. These are used for displaying a subset of available digital and analog pins which will reduce the amount of information displayed to and shifted through by the user.

Warning
This method cannot verify that size_d or size_a match the number of pins in d_pins or a_pins. If a pin is missing from the subset, please ensure that size_d and size_a are correct.
Parameters
d_pinsAn array of the digital pin numbers
size_dThe size of d_pins, i.e. the number of digital pins being included
a_pinsAn array of the analog pin numbers
size_aThe size of a_pins, i.e. the number of analog pins being included

◆ timedPeek()

int Debugger::timedPeek ( )
protected

Perform a Serial peek with a set timeout period (1 second)

Note
This code was taken from the Arduino Library's Serial communication method. The original method is protected, so it was transferred here for our use.

◆ turnOff()

void Debugger::turnOff ( )

Turn debugging info off.

This method will prevent update() and breakpoint() methods displaying debugging information. It will only affect these two methods. All other methods will potentially display error messages.

◆ turnOn()

void Debugger::turnOn ( )

Turn debugging info on.

This method will allow update() and breakpoint() methods to display debugging information.

◆ updateArray()

void Debugger::updateArray ( Variable  var)
protectedvirtual

Prompt the user for the value to update the chosen index's value to.

This method will prompt the user for a new value to use for a chosen array at a chosen array index.

Note
The variable is only updated if a valid value is entered. Invalid values will cause error messages to be displayed.
Warning
Data validation is limited. This method will attempt to ensure impossible data isn't used (ex. a byte set to -1) but does not guarantee to stop all invalid data entries

Reimplemented in DebuggerF.

◆ updatePins()

void Debugger::updatePins ( bool  displayAll)

Prompt the user for the value to update the digital pin to.

This method will prompt the user for the digital pin to update and its new value.

Note
If an invalid value is entered, no change will be made to the pin. Also, only the first character is actually used.
Parameters
displayAllTrue - Display all pins | False - only display the subset of pins

◆ updateVariables()

void Debugger::updateVariables ( )
virtual

Prompt the user for the value to update the chosen variable to.

This method will prompt the user for a new value to use for a chosen variable and validate the new value.

Note
The variable is only updated if a valid value is entered. Invalid values will cause error messages to be displayed.
Warning
Data validation is limited. This method will attempt to ensure impossible data isn't used (ex. a byte set to -1) but does not guarantee to stop all invalid data entries}

Reimplemented in DebuggerF.

Member Data Documentation

◆ _is8Bit

bool Debugger::_is8Bit
protected

This boolean helps determine if the microcontroller uses 8-Bit or 32-Bit registers.

True - registers will be cast for 8-bits uint8_t False - registers will be cast for 32-bits uint32_t

◆ analog_pins

byte Debugger::analog_pins[10]
protected

Array listing the subset of analog pins.

◆ analog_size

byte Debugger::analog_size = 0
protected

Number of analog pins in the subset.

◆ counters

byte Debugger::counters[5] = {0,0,0,0,0}
protected

Allows for 5 individual update counters.

◆ counters_max

byte Debugger::counters_max[5] = {0,0,0,0,0}
protected

Tracks the maximum value for each counter.

◆ debuggingIsOn

bool Debugger::debuggingIsOn = true
protected

◆ digital_pins

byte Debugger::digital_pins[10]
protected

Array listing the subset of digital pins.

◆ digital_size

byte Debugger::digital_size = 0
protected

Number of digital pins in the subset.

◆ top_var_watch

byte Debugger::top_var_watch = 0
protected

References max number of variables currently being watched.

◆ usePinList

bool Debugger::usePinList = false
protected

Set to true by setPins() and allows the debugger to show a subset of pins.

◆ var_watch

Variable Debugger::var_watch[10]
protected

Holds information on the variable's being tracked.


The documentation for this class was generated from the following files: