Filmote: /* But how do I turn sections on and off? */

2024-08-17T02:49:24Z

But how do I turn sections on and off?

← Older revision		Revision as of 02:49, 17 August 2024
Line 108:		Line 108:
	</pre>		</pre>

	This technique can be extended to provide granular logging within a procedure itself. The example below shows how the level of logging could be refined in <code>Procedure B<code.		This technique can be extended to provide granular logging within a procedure itself. The example below shows how the level of logging could be refined in <code>Procedure B</code>.

	<pre>		<pre>

Filmote: /* But how do I turn sections on and off? */

2024-08-17T02:48:54Z

But how do I turn sections on and off?

← Older revision		Revision as of 02:48, 17 August 2024
Line 85:		Line 85:

	void loop() {		void loop() {

	#ifdef DEBUG		#ifdef DEBUG
	Serial.println(“Loop(): Start”);		Serial.println(“Loop(): Start”);
Line 92:		Line 91:
	proc_A();		proc_A();
	proc_B(12, 14);		proc_B(12, 14);

	}		}

Filmote: /* Debugging Code is Valuable */

2024-08-17T02:48:34Z

Debugging Code is Valuable

← Older revision		Revision as of 02:48, 17 August 2024
Line 29:		Line 29:
	It uses C / C++ prototypes to define an identifier <code>DEBUG</code> (line 001) that indicates whether the application is in debug mode or not. Lines 004 – 006 define function prototypes that will log a string or decimal value to the serial port using a syntax similar to the <code>print()</code> and <code>println()</code> functions.		It uses C / C++ prototypes to define an identifier <code>DEBUG</code> (line 001) that indicates whether the application is in debug mode or not. Lines 004 – 006 define function prototypes that will log a string or decimal value to the serial port using a syntax similar to the <code>print()</code> and <code>println()</code> functions.

	If the <code>DEBUG</code> identifier is not defined, the prototype functions are declared again but this time with no body (lines 08 – 10). This has the result of effectively dropping the function at compile time – resulting in a smaller compilation unit. Rather than deleting the <code>'#define DEBUG</code> line, I simply prefix the identifier with a few characters to change its value.		If the <code>DEBUG</code> identifier is not defined, the prototype functions are declared again but this time with no body (lines 008 – 010). This has the result of effectively dropping the function at compile time – resulting in a smaller compilation unit. Rather than deleting the <code>'#define DEBUG</code> line, I simply prefix the identifier with a few characters to change its value.

	Now that we have defined both the identifier and the prototype functions, we can use them in the following way. To log a simple message or variable value, use the prototype function:		Now that we have defined both the identifier and the prototype functions, we can use them in the following way. To log a simple message or variable value, use the prototype function:

Filmote: /* But how do I turn sections on and off? */

2024-08-17T02:48:09Z

But how do I turn sections on and off?

← Older revision		Revision as of 02:48, 17 August 2024
Line 96:		Line 96:

	void proc_A() {		void proc_A() {

	#ifdef DEBUG_PROC_A		#ifdef DEBUG_PROC_A
	Serial.println(“proc_A(): Start”);		Serial.println(“proc_A(): Start”);
	#endif		#endif
			... actual code.
	}		}

	void proc_B(uint8_t param1, uint8_t param2) {		void proc_B(uint8_t param1, uint8_t param2) {

	#ifdef DEBUG_PROC_B		#ifdef DEBUG_PROC_B
	Serial.print(“proc_B(): Start);		Serial.print(“proc_B(): Start);
	#endif		#endif
			... actual code.
	}		}
	</pre>		</pre>

Filmote: Created page with "Most modern programming languages, such as C# or Java, and their respective development environments provide extensive tools for profiling and debugging code. As such, developers take for granted the ability to set break points or alter variable values and code on the fly. The Arduboy with its limited resources provides none of these facilities and debugging is often performed by logging status information to the console. Therefore developing on the Arduino and Ardubo..."

2024-08-17T02:47:25Z

Created page with "Most modern programming languages, such as C# or Java, and their respective development environments provide extensive tools for profiling and debugging code. As such, developers take for granted the ability to set break points or alter variable values and code on the fly. The Arduboy with its limited resources provides none of these facilities and debugging is often performed by logging status information to the console. Therefore developing on the Arduino and Ardubo..."

New page

Most modern programming languages, such as C# or Java, and their respective development environments provide extensive tools for profiling and debugging code. As such, developers take for granted the ability to set break points or alter variable values and code on the fly. The Arduboy with its limited resources provides none of these facilities and debugging is often performed by logging status information to the console.

Therefore developing on the Arduino and Arduboy is like stepping back in time for some developers - forcing them to re-think how to debug applications.

== Debugging Code is Valuable ==

Due to the limited memory in an Arduino environment, most developers will add temporary logging within a troublesome procedure and then strip it out when the issue is resolved. Over the life of a project, the same logging code may be added and removed from a single procedure a number of times!

I think logging code is valuable and should remain in the application at all times and be turned on or off at the flick of a switch.

Consider the following code:

<pre>
001 #define DEBUG
002
003 #ifdef DEBUG
004 #define DEBUG_print(x) Serial.print(x)
005 #define DEBUG_printDec(x) Serial.print(x, DEC)
006 #define DEBUG_println(x) Serial.println(x)
007 #else
008 #define DEBUG_print(x)
009 #define DEBUG_printDec(x)
010 #define DEBUG_println(x)
011 #endif
</pre>

It uses C / C++ prototypes to define an identifier <code>DEBUG</code> (line 001) that indicates whether the application is in debug mode or not. Lines 004 – 006 define function prototypes that will log a string or decimal value to the serial port using a syntax similar to the <code>print()</code> and <code>println()</code> functions.

If the <code>DEBUG</code> identifier is not defined, the prototype functions are declared again but this time with no body (lines 08 – 10). This has the result of effectively dropping the function at compile time – resulting in a smaller compilation unit. Rather than deleting the <code>'#define DEBUG</code> line, I simply prefix the identifier with a few characters to change its value.

Now that we have defined both the identifier and the prototype functions, we can use them in the following way. To log a simple message or variable value, use the prototype function:

<pre>
DEBUG_print(“Player X position : “);
DEBUG_println(x);
</pre>

For more complex logging, conditional include the code if the <code>DEBUG</code> identifier is defined:

<pre>
#ifdef DEBUG
for (byte x = 0; x < card_count; x++) {
Serial.println(card[x]);
}
#endif
</pre>

== But how do I turn sections on and off? ==

As a program grows and more debugging code is added, you will invariably run into two problems – firstly, you have so much information being logged that you cannot see the forest for the trees and, secondly, that the actual logging code is taking up a significant portion of the minimal memory available.

The following technique allows you to enable and disable logging overall and at the procedural level.

In the previous example, a single identifier named <code>DEBUG</code> was used to turn on or off all debugging code. Identifier definitions can be nested in the Arduboy environment to create a hierarchy of debugging flags as shown below.

<pre>
#define DEBUG

#ifdef DEBUG
#define DEBUG_PROC_A
#endif
#ifdef DEBUG
#define DEBUG_PROC_B
#endif
</pre>

This definition provides an overall debugging identifier and individual identifiers for two procedures, <code>A</code> & <code>B</code>. Overall debugging can be enabled or disabled by changing the <code>DEBUG</code> identifier to something else. Subsequent definitions of the identifiers <code>DEBUG_PROC_A</code> and <code>DEBUG_PROC_B</code> will be skipped as they are conditioned on the presence of identifier <code>DEBUG</code>.

Debugging of individual procedures can be controlled by altering their identifiers to include or exclude them.

The sample application below shows these flags in action:

<pre>
#define DEBUG

#ifdef DEBUG
#define DEBUG_PROC_A
#endif
#ifdef DEBUG
#define DEBUG_PROC_B
#endif

void loop() {

#ifdef DEBUG
Serial.println(“Loop(): Start”);
#endif

proc_A();
proc_B(12, 14);

}

void proc_A() {

#ifdef DEBUG_PROC_A
Serial.println(“proc_A(): Start”);
#endif
}

void proc_B(uint8_t param1, uint8_t param2) {

#ifdef DEBUG_PROC_B
Serial.print(“proc_B(): Start);
#endif

}
</pre>

This technique can be extended to provide granular logging within a procedure itself. The example below shows how the level of logging could be refined in <code>Procedure B<code.

<pre>
#define DEBUG

#ifdef DEBUG
#define DEBUG_PROC_A
#endif

#ifdef DEBUG
#define DEBUG_PROC_B
#endif

#ifdef DEBUG_PROC_B
#define DEBUG_PROC_B_CALL
#endif

#ifdef DEBUG_PROC_B
#define DEBUG_PROC_B_PARAMS
#endif
</pre>

Then, within the procedure itself, the new logging levels are incorporated to provide more information as the logging level is increased.

In the example below, if the <code>DEBUG_ PROC_B_CALL</code> identifier is defined without <code>DEBUG_PROC_B_PARAMS</code> identifier, the call to the procedure will only log the
text <code>proc_B(): Start</code>. Including identifier <code>DEBUG_PROC_B_PARAMS</code> will also log out the parameter values.

<pre>
void proc_B(uint8_t param1, uint8_t param2) {

#ifdef DEBUG_PROC_B_CALL
Serial.println(“proc_B(): Start”);
#endif
#ifdef DEBUG_PROC_B_PARAMS
Serial.print("> param1 = ");
Serial.println(param1);
Serial.println("> param2 = ");
Serial.println(param2);
#endif

}
</pre>

== Almost there .. ==

Previously we defined a number of prototype functions to allow us to conditionally include a <code>Serial.print()</code> or <code>Serial.println()</code> in our code.
These prototypes can be expanded to include additional information, such as the function (procedure) name, file name and line number, as shown below.

<pre>
#define DEBUG

#ifdef DEBUG
#define DEBUG_println(x) Serial.println(x)
#define DEBUG_printDec(x) Serial.println(x, DEC)

#define DEBUG_println(str)
Serial.print(__FILE__);
Serial.print(", ");
Serial.print(__FUNCTION__);
Serial.print(": ");
Serial.print(__LINE__);
Serial.print(" (");
Serial.print(millis());
Serial.print(") ");
Serial.println(str);
#endif

#else
#define DEBUG_print(x)
#define DEBUG_printDec(x)
#define DEBUG_println(x)
#endif
</pre>

Last - but certainly not least – my final tip. When developing and testing logic games, it is often desirable to have the pseudo-random number generator produce the same series of numbers each time thus allowing you to test a sequence of events again and again until your code performs correctly.

I use the <code>DEBUG</code> identifier to condition the seeding of the number sequence – if I am debugging the code, I want the seed to be a constant otherwise I seed the generator with another random number (in this case the value read from an analogue port with a floating pin).

<pre>
#ifdef DEBUG
int seed = 1;
#else
int seed = analogRead(3);
#endif

randomSeed(seed);
</pre>

Debugging Code - Revision history

Filmote: /* But how do I turn sections on and off? */

Filmote: /* But how do I turn sections on and off? */

Filmote: /* Debugging Code is Valuable */

Filmote: /* But how do I turn sections on and off? */