Debugging

When developing software, debugging is very helpful for assisting with coding, and finding problems. Debugging can be performed:

• Using a hardware PIC Programmer/Debugger, like the Microchip ICD 3
• Using a Debug Terminal, like the USB port of the board and the Netcruzer USB Terminal

Using a hardware Debugger, like the Microchip ICD 3, break points can be set in code, and single stepped from within the IDE (MPLAB IDE or MPLAB X IDE). See IDE and Debugger help for additional information. Using a hardware Debugger has the obvious disadvantage of extra expense.

Seeing that all SBC66 Boards boards have USB ports, it can be used for outputting debug messages, receiving commands, and requesting information. See the Debugging section in the "Webserver Project" for an example of how the USB port is used for debugging.

Debug Terminal

The Debug Terminal is very efficient and easy to use. Just plug your board into a USB port of your PC, and debug messages will be received on the Netcruzer USB Terminal.

The "nz_debug.c" file contains code that implements a Debug Terminal. It's main function is to send and receive debug messages to and from a configurable port. By default it is configured to use the USB HID port of the board, and the Netcruzer USB Terminal (Application running on PC, and connected to board via USB port). This configuration allows the Netcruzer USB Terminal to:

• Display debug messages received from the board. Throughout the code there are DEBUG_PUT_STR and DEBUG_PUT_WORD macros that send debug message to the debug port (configued to use the USB HID port)
• Send messages to the board. These messages are parsed in the debugService() function in "debug.c".
• Request information from the board. These requests are also parsed in the debugService() function. For example, entering "ip" in the "Send Debug Text" box of the Netcruzer USB Terminal, and sending it, will result in the board's current IP address to be sent by the board, and displayed in the Netcruzer USB Terminal.

All *.c files that want to send debug messages should have the following defined at the top of the file (where XXX is the filename):

//Add debugging to this file. The DEBUG_CONF_XXX macro sets debugging to desired level, and is configured in "Debug Configuration" section of projdefs.h file
#if !defined(DEBUG_CONF_XXX)
    #define DEBUG_CONF_XXX     DEBUG_CONF_DEFAULT   //Default Debug Level, disabled if DEBUG_LEVEL_ALLOFF defined, else DEBUG_LEVEL_ERROR
#endif
#define MY_DEBUG_LEVEL   DEBUG_CONF_XXX
#include "nz_debug.h"

The DEBUG_PUT_XX functions defined in nz_debug.h (DEBUG_PUT_STR() for example) can than be used to write debug information.

• The first parameter in all DEBUG_PUT_XX functions is the Debug Level, and can be DEBUG_LEVEL_CRITICAL, DEBUG_LEVEL_ERROR, DEBUG_LEVEL_WARNING or DEBUG_LEVEL_INFO. Critical is the highest level.
• The second parameter is the debug data that is written, and depends on the function (For example, is a string for DEBUG_PUT_STR)

The "Debug Configuration" section in the projdefs.h file is used to set the debug level of each file. For example, for the main.c file, the following define will result in only macros with a Debug Level equal to, or higher than, "Warning" to be executed.

#define DEBUG_CONF_MAIN             DEBUG_LEVEL_WARNING

For this example, the following code will result in a debug message being sent to the debug port.

DEBUG_PUT_STR(DEBUG_LEVEL_WARNING, "\nSomething seems wrong in main.c!");

This is the case because we set the Debug Level of DEBUG_CONF_MAIN to warning, meaning all debug messages with Critical, Error or Warning level will be sent. The following message will however not be sent (and not generate any code):

DEBUG_PUT_STR(DEBUG_LEVEL_INFO, "\nSomething interesting happened in main.c!");

Additionally the following line in the projdefs.h file will disable all debug messages. It is commented by default. For production code, it is a good idea uncommenting this line. This will make the code smaller and faster (no debug messages are sent).

#define DEBUG_LEVEL_ALLOFF

Details

Debugging is implemented in the nz_debugDefault.c file. It provides a simple way for the application to send and receive text based debug messages. The debugPutString() and debugPutWord() functions can be used to write text based debug information to the debug port. The debugGetString() function is used to get the last received debug message.

By default debugging is configured to use the USB HID port, and the Netcruzer USB Terminal. This can be changed if debugging should use some other port, like a Serial Port, UDP or something else.

Using the Netcruzer USB Terminal for debugging is very efficient and easy. The debugService() function in "debug.c" parses strings received from the Netcruzer USB Terminal (entered in the "Send Debug Text" box), and sends a reply debug message. This reply message is displayed in the "Received From Device" message box. To try it, connect the USB port of the board, start the Netcruzer USB Terminal, and enter "ip" in the "Send Debug Text" box. The current IP address should be received from the board, and displayed in the "Received From Device" message box.