You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This class provides functionality useful for debugging sketches via `printf`-style statements.
8
+
This class provides functionality useful for debugging sketches via `printf`-style statements with enhanced features including module-based debug levels and runtime configuration.
9
9
10
10
# How-To-Use Basic
11
11
Arduino_DebugUtils has 6 different debug levels (described descending from highest to lowest priority):
@@ -16,7 +16,7 @@ Arduino_DebugUtils has 6 different debug levels (described descending from highe
16
16
*`DBG_DEBUG` - more information
17
17
*`DBG_VERBOSE` - most information
18
18
19
-
The desired debug level can be set in code via `setDebugLevel(DBG_WARNING)` or while the code is running using the Serial Monitor.
19
+
The desired debug level can be set via `setDebugLevel(DBG_WARNING)`.
20
20
21
21
Debug messages are written via `print` which supports `printf`-style formatted output.
22
22
@@ -30,41 +30,74 @@ DEBUG_VERBOSE("i = %d, pi = %f", i, pi);
30
30
31
31
If desired, timestamps can be prefixed to the debug message. Timestamp output can be enabled and disabled via `timestampOn` and `timestampOff`.
32
32
33
-
# How-To-Use Advanced
34
-
Normally all debug output is redirected to the primary serial output of each board (`Serial`). In case you want to redirect the output to another output stream you can make use of `setDebugOutputStream(&Serial2)`.
35
-
36
-
# Documentation
37
-
## Code setup
33
+
# New Features
38
34
39
-
### Include the Library
35
+
## Module-Based Debug Levels
36
+
This enhanced version supports up to 20 separate modules, each with its own debug level. This allows for more granular control over debugging output in complex applications.
By default, the Output Stream and input port for printing debug messages and receiving config commands is `Serial`.
52
+
## Runtime Configuration via Serial
53
+
You can now change debug settings at runtime through the same serial port used for debug output:
50
54
51
-
For minimal setup, just create the Serial object with a specified baud rate.
52
-
```C++
53
-
Serial.begin(9600); // Set baud rate here. Make sure you match the same baud rate in your terminal or monitor
54
55
```
55
-
In advanced cases you can use other serial ports (if available), or a Software Serial object. You can also (optionally) set a different Debug Level, turn on timestamps and debug labels.
56
+
// Send these commands through serial monitor to change settings
57
+
VERBOSE // or V - Sets global debug level to VERBOSE
58
+
DEBUG // or D - Sets global debug level to DEBUG
59
+
INFO // or I - Sets global debug level to INFO
60
+
WARNING // or W - Sets global debug level to WARNING
61
+
ERROR // or E - Sets global debug level to ERROR
62
+
NONE // or N - Turns off global debug output
63
+
64
+
// Change debug level for a specific module
65
+
3V // Sets module 3's debug level to VERBOSE
66
+
5D // Sets module 5's debug level to DEBUG
67
+
7I // Sets module 7's debug level to INFO
68
+
10W // Sets module 10's debug level to WARNING
69
+
15E // Sets module 15's debug level to ERROR
70
+
20N // Sets module 20's debug level to NONE
71
+
72
+
// Toggle configuration settings
73
+
LABEL // or L - Toggle debug level labels
74
+
TIMESTAMP // or T - Toggle timestamps
75
+
NEWLINE // or C - Toggle newlines
76
+
77
+
// Display current debug status
78
+
STATUS // or S - Display current debug configuration
79
+
```
80
+
81
+
## Enhanced Timestamp Formatting
82
+
Timestamps can now be displayed in a more readable format:
56
83
57
84
```C++
58
-
mySerial.begin(9600); // Set baud rate here. Make sure you match the same baud rate in your terminal or monitor
59
-
Debug.setDebugOutputStream(&mySerial);
60
-
Debug.setDebugLevel(DBG_VERBOSE);
61
-
Debug.timestampOn();
85
+
// Format timestamps as [HH:MM:SS.mmm] instead of milliseconds
86
+
Debug.formatTimestampOn();
62
87
```
63
88
64
-
### Debug: object
65
-
Arduino_DebugUtils Object that will be used for calling member functions is automatically instantiated when you include the library.
89
+
# How-To-Use Advanced
90
+
Normally all debug output is redirected to the primary serial output of each board (`Serial`). In case you want to redirect the output to another output stream you can make use of `setDebugOutputStream(&Serial2)`.
91
+
92
+
# Documentation
93
+
### Debug :
94
+
Arduino_DebugUtils Object that will be used for calling member functions.
95
+
96
+
## Basic Functions
66
97
67
98
### Debug.setDebugLevel(int const debug_level) :
99
+
Sets the global debug level (module 0).
100
+
68
101
Parameter debug_level in order of lowest to highest priority are : `DBG_NONE`, `DBG_ERROR`, `DBG_WARNING`, `DBG_INFO` (default), `DBG_DEBUG`, and `DBG_VERBOSE`.
69
102
70
103
Return type: void.
@@ -73,6 +106,17 @@ Example:
73
106
```C++
74
107
Debug.setDebugLevel(DBG_VERBOSE);
75
108
```
109
+
110
+
### Debug.getDebugLevel() :
111
+
Returns the current global debug level.
112
+
113
+
Return type: int.
114
+
115
+
Example:
116
+
```C++
117
+
int currentLevel = Debug.getDebugLevel();
118
+
```
119
+
76
120
### Debug.setDebugOutputStream(Stream * stream) :
77
121
By default, Output Stream is Serial. In advanced cases other objects could be other serial ports (if available), or can be a Software Serial object.
78
122
@@ -83,6 +127,17 @@ Example:
83
127
SoftwareSerial mySerial(10, 11); // RX, TX
84
128
Debug.setDebugOutputStream(&mySerial);
85
129
```
130
+
131
+
### Debug.setDebugIOStream(Stream * stream) :
132
+
Sets both the input and output stream for debug messages. This allows receiving configuration commands on the same stream used for debug output.
133
+
134
+
Return type: void.
135
+
136
+
Example:
137
+
```C++
138
+
Debug.setDebugIOStream(&Serial);
139
+
```
140
+
86
141
### Debug.timestampOn() :
87
142
Calling this function switches on the timestamp in the `Debug.print()` function call;
88
143
By default, printing timestamp is off, unless turned on using this function call.
@@ -106,26 +161,25 @@ Debug.timestampOff();
106
161
DEBUG_VERBOSE("i = %d", i); //Output looks like : i = 21
107
162
```
108
163
109
-
### Debug.debugLabelOn() :
110
-
Calling this function switches on the Debug Label in the `Debug.print()` function call;
111
-
By default, printing the debug label is off, unless turned on using this function call.
164
+
### Debug.formatTimestampOn() :
165
+
Calling this function enables formatted timestamps in the format [HH:MM:SS.mmm] instead of milliseconds.
112
166
113
167
Return type: void.
114
168
115
169
Example:
116
170
```C++
117
-
Debug.debugLabelOn();
171
+
Debug.formatTimestampOn();
172
+
DEBUG_VERBOSE("i = %d", i); //Output looks like : [ 00:01:35.421 ] i = 21
118
173
```
119
174
120
-
### Debug.debugLabelOff() :
121
-
Calling this function switches off the Debug Label in the `Debug.print()` function call;
122
-
By default, printing the debug label is off, unless turned on using this function call.
175
+
### Debug.formatTimestampOff() :
176
+
Calling this function disables formatted timestamps, reverting to milliseconds display.
123
177
124
178
Return type: void.
125
179
126
180
Example:
127
181
```C++
128
-
Debug.debugLabelOff();
182
+
Debug.formatTimestampOff();
129
183
```
130
184
131
185
### Debug.newlineOn() :
@@ -148,6 +202,26 @@ Example:
148
202
Debug.newlineOff();
149
203
```
150
204
205
+
### Debug.debugLabelOn() :
206
+
Calling this function enables display of debug level labels (ERROR, WARNING, etc.) in the output.
207
+
208
+
Return type: void.
209
+
210
+
Example:
211
+
```C++
212
+
Debug.debugLabelOn();
213
+
```
214
+
215
+
### Debug.debugLabelOff() :
216
+
Calling this function disables display of debug level labels in the output.
This function prints the message if parameter `debug_level` in the `Debug.print(debug_level, ...)` function call belongs to the range: DBG_ERROR <= debug_level <= (<DBG_LEVEL> that has been set using `setDebugLevel()` function).
Prints a debug message for a specific module if the module's debug level is high enough.
329
+
330
+
Parameters:
331
+
- module_id: The ID of the module (1-20)
332
+
- debug_level: The debug level of this message
333
+
- fmt: Printf-style format string
334
+
- ...: Variable arguments for the format string
335
+
336
+
Return type: void.
337
+
338
+
Example:
339
+
```C++
340
+
Debug.print(1, DBG_INFO, "Connected to SSID: %s", ssid);
341
+
```
342
+
343
+
## Runtime Configuration
344
+
345
+
### Debug.processDebugConfigCommand() :
346
+
Checks for and processes any pending debug configuration commands from the input stream.
347
+
348
+
This function should be called regularly in your loop() function to enable runtime configuration. It allows you to change debug settings at runtime by sending commands through the serial monitor, including:
349
+
350
+
- Change global debug level with commands like `VERBOSE`, `DEBUG`, etc.
351
+
- Change module-specific debug levels with commands like `3V` (set module 3 to VERBOSE)
352
+
- Toggle configuration settings with commands like `LABEL`, `TIMESTAMP`, etc.
353
+
- Display current debug status with the `STATUS` command
354
+
355
+
Return type: void.
356
+
357
+
Example:
358
+
```C++
178
359
voidloop() {
179
-
DEBUG_VERBOSE("i = %d", i);
180
-
i++;
360
+
// Process any debug configuration commands
181
361
Debug.processDebugConfigCommand();
182
-
delay(1000); // See note on timing below
362
+
363
+
// Rest of your code
364
+
// ...
183
365
}
184
366
```
185
367
186
-
### Timing
187
-
- If you have a delay in your `loop()` (as is the case with the example code) this will also delay action on any entered commands, so for faster response call `processDebugConfigCommand()` more often.
368
+
### Debug.printDebugStatus() :
369
+
Displays the current debug configuration status, including module labels, debug levels, and toggle settings.
370
+
371
+
Return type: void.
188
372
189
-
### Trouble-shooting
190
-
Check your monitor or terminal is configured:
191
-
- to send a LF or CRLF Line Ending at the end of a message sent via the serial port.
192
-
- to use the same baud rate specified when setting up the Serial object (9600 in the examples)
0 commit comments