SerialDebug Library for Arduino

Improved serial debugging to Arduino, with with debug levels and simple software debugger, to see/change global variables, to add watch for these variables, or call a function, in runtime, using serial monitor or SerialDebugApp.

Note: This image is from the tutorial for this library at randomnerdtutorials.com - Image by Sara Santos

About
News
Beta version
Github
Benefits
SerialDebugApp
How it looks
Commands
Install
Usage
Options
Watches
Install
Converter
Khow issues
Releases
Links
Thanks

About

Generally debugs messages in Arduino is done by Serial.print*, and show in this monitor serial, or another serial tool, as screen, pyserial, coolterm, etc.

The Arduino official IDE, not have debugger. Only way, until now, is using a another IDE, that can be paid, and a hardware debugger, as JTAG.

SerialDebug is a library to Improved serial debugging and simple software debugger to Arduino.

Yes, now we can use one debugger, simple but functional, and not need a extra hardware to do it.

News

2018-11-16

Now the SerialDebug print macros support the second argument of Serial.print. Thanks to @wjwieland to open a issue about this. E.g.: printlnA(10, HEX);

2018-10-26

Now the SerialDebugApp show debugger elements on screen, please update to 0.9.2 to see it in action
In library version >= 0.9.75, have a new minimum mode, to limit to only output debugs, no debugger, no printf, no extra functions or processing on library. And by default, low memory boards, as Uno, is in minimum mode.

Beta version

This is a beta version. Not yet fully tested, optimized, and documented.

This is a previous documentation. It will be better documented before first RC version.

Github

Contribute to this library development by creating an account on GitHub.

Please give a star, if you find this library usefull, this help a another people, discover it too.

Please add a issue for problems or suggestion.

And please join in the Gitter chat room (SerialDebug on Gitter).

Benefits

SerialDebug is bether than Arduino default serial debugging:

This is optimized for features that it have

The initial status of SerialDebug is inactive, where no normal debug outputs, and no CPU waste time for debugs. Well, there may not be anyone seeing it. It is good for not always USB connected project, as one powered by battery or external power supply.

Only messages that are processed and displayed, are of type Error or Always (important ones).

After first command received, SerialDebug will become active

All routines to show debug is a C/C++ precompiler macros, so no extra functions calls, only Serial.print*

Except when use printf formatter (debug* macros), for boards that no have it native.

For simple software debugger, have memory optimizations:
- No fixed arrays, is used C++ Vector to dynamic arrays
- Is used void* pointer to store values, when it is need. Is more complicate, but it dramatically reduces use of memory, compared to store 17 variables for support 17 kinds of this.
Note: due a extra overhead in processing simple software debugger, it starts disabled. You can enable when you need (dbg command)

Now (>= 0.9.5) SerialDebug have a new performance, compared with standard print, no difference for print* macros and about slower only 1% with debug* macros (due printf processing). Boards tested: Uno, Mega, Due, Esp8266 and Esp32.

To reproduce it, just upload the advanced example, and call function 8 (just command: f 8) to run all benchmarks of serial.

Now (>= 0.9.74) SerialDebug have a mode mininum, for boards with low memory to program, as Arduino UNO, if this mode is set, SerialDebug only show messages, no extra functions or processing

In future versions, the SerialDebug will more otimized, for CPU and memory
It is good for any Arduino

Is good for new boards, that have good CPU and memory, like Espressif (ESP8266 and ESP32) and ARM arch (Due, Teensy, etc.).

But it runs in older Arduino, as UNO, Leonardo, Mega, ...

In UNO or similar (e.g. Leonardo), some features as Watches in debugger is not implemented, due full library is huge for it (more than 5k lines of code, without comments).

For the Mega, some features are reduced, but have watches.

If debugger is disabled in code, or in mode mininum (default for low memory boards), SerialDebug in Uno, consumes only about 50 bytes of memory. And it not fully otimized yet.

The default speed of serial is 250000, for Espressif, ARM or Mega boards and 115200 for UNO, Leonardo, etc.

Only exception is boards with Tiny* AVR MCU, due it not have CPU and memory to this library.
Have debug levels

During the development, we can put a lot of debug messages...

But with SerialDebug, we can put a level in each one.

For all messages (except any (debug*A) or error (debug*E)), the message only is processed and showed, if debug level is equal or higher than it level

SerialDebug have 7 debug levels, in order of priority:
- Alway showed:
  - Error: Critical errors
  - Always: Important messages
- No debug:
  - None: No debug output
- Another levels (showed if level is equal or higher that actual one):
  - Warning: Error conditions but not critical
  - Info: Information messages
  - Debug: Extra information
  - Verbose: More information than the usual
So We can change the level to Verbose, to see all messages. Or to Debug to see only debug or higher level, etc.

Is very good to reduce a quantity of messages that a project can generate, in serial monitor.

It is easy to migrate

From the 0.9.5 version, SerialDebug have a new macros to help migrate more easy

For example: the code extracted from www.ladyada.net:

Serial.println("Here is some math: ");

Serial.print("a = ");
Serial.println(a);
Serial.print("b = ");
Serial.println(b);
Serial.print("c = ");
Serial.println(c);

Serial.print("a + b = ");       // add
Serial.println(a + b);

Serial.print("a * c = ");       // multiply
Serial.println(a * c);

Serial.print("c / b = ");       // divide
Serial.println(c / b);

Serial.print("b - c = ");       // subtract
Serial.println(b - c);

Only replace Serial.println to printlnD and replace Serial.print to printD Note: this order of replaces is important. Note: D is to debug level, can be another, as V to verbose

printlnD("Here is some math: ");

printD("a = ");
printlnD(a);
printD("b = ");
printlnD(b);
printD("c = ");
printlnD(c);

printD("a + b = ");       // add
printlnD(a + b);

printD("a * c = ");       // multiply
printlnD(a * c);

printD("c / b = ");       // divide
printlnD(c / b);

printD("b - c = ");       // subtract
printlnD(b - c);

SerialDebug has a converter to help migrate your Arduino codes, from Serial.prints to this library.

SerialDebugConverter

Have printf support to serial

Regardless of whether the board has it native or not. That I know, only Espressif boards have it native

For example:


  Serial.print("*** Example - varA = ");
  Serial.print(varA);
  Serial.print(" varB =  ");
  Serial.print(varB);
  Serial.print(" varC =  ");
  Serial.print(varC);
  Serial.println();

Can be converted to a single command:

debugD("*** Example - varA = %d varB = %d varC = %d", varA, varB, varC);

Improving the example of previous topic, w/ debug with printf formatter:

debugD("Here is some math: ");

debugD("a = %d", a);
debugD("b = %d", b);
debugD("c = %d", c);

debugD("a + b = %d", (a + b)); // add
debugD("a * c = %d", (a * c)); // multiply
debugD("c / b = %d", (c / b)); // divide
debugD("b - c = %d", (b - c)); // subtract

Note: 50% less code

SerialDebug

Install / Use

README