gbj_serial_debug

Library defines preprocessor macro functions for serial debugging and writing to the serial port.

Constants

• SERIAL_NODEBUG: Defining this macro determines, that serial debugging should not be used.
• SERIAL_PREFIX: Macro defines a string, that is prefixed to logging outputs with internally defined modul separator, which is ::.
• SERIAL_SEPAR_V: Macro defines a string, that suffixes a key in key-value constructs with internally defined value separator, which is : .
  • The macro is useful for debugging output in application libraries.
  • It is useful to define default prefix main within project macros, e.g., in case of PlatformIO in the project file .platformio.
  • In order to avoid compilation warnings about redefining this macro, it is usefull to undefine it right before defining it again for the desired prefix.

The debugging macros should be defined after inclusion of the library header file in a sketch in order to take them into effect.

#include "gbj_serial_debug.h"
...
#undef SERIAL_PREFIX
#define SERIAL_PREFIX "mylib"

Interface

• All macro functions can be called without trailing semicolon. However, to omit problems with formatters, it is recommended to use them.
• Macro functions with parameters are called as ordinary C functions with braces.
• Macro functions without parameters are called without braces like macro constants.

System macros

• SERIAL_BEGIN(b): Starts serial port with baud speed as a parameter, e.g., SERIAL_BEGIN(9600).
• SERIAL_F(s): Places string to the flash memory if the platform allows it, e.g., send(SERIAL_F("Text"));.

Output macros

• SERIAL_PRINTLN(p): Wrapper for system Serial.println.

Login macros

• SERIAL_LOG1(p1): Prints one parameter on the separate line with EOL (end of line), e.g., SERIAL_LOG1(123).
• SERIAL_LOG2(p1, p2): Prints both parameters on one separate line with EOL after the very last parameter, e.g., SERIAL_LOG2("T=", 123).
• SERIAL_LOG3(p1, p2, p3): ditto
• SERIAL_LOG4(p1, p2, p3, p4): ditto
• SERIAL_LOG4(p1, p2, p3, p4, p5): ditto
• SERIAL_LOG6(p1, p2, p3, p4, p5, p6): ditto

Chain macros

• SERIAL_CHAIN1(p1): Prints one parameter on current line without EOL, e.g., SERIAL_CHAIN1(123), which enables chaining multiple strings with macro. After chaining all strings it is useful to use some of login macros.
• SERIAL_CHAIN2(p1, p2): Prints both parameters on current line without EOL, e.g., SERIAL_CHAIN2("T=", 123).
• SERIAL_CHAIN3(p1, p2, p3): ditto
• SERIAL_CHAIN4(p1, p2, p3, p4): ditto
• SERIAL_CHAIN4(p1, p2, p3, p4, p5): ditto
• SERIAL_CHAIN6(p1, p2, p3, p4, p5, p6): ditto

Debug macros

• SERIAL_TITLE(s): Flashes input string and prints it on the separate line with EOL, e.g., SERIAL_TITLE("Start").
• SERIAL_ACTION(s): Flashes input string and prints it on the separate line without EOL. It is useful when another printing on the same line is expected, e.g., by waiting on connection and signaling it by dots.
• SERIAL_ACTION_VALUE(s): Flashes input string and prints it on the separate line without EOL but with value separator. It is useful when another printing on the same line is expected.
• SERIAL_ACTION_END(s): Continues by flashing input string to the recent line without prefixing the string but with new line. It finishes an action.
• SERIAL_ACTION_END_CHAIN(s): Continues by flashing input string to the recent line without prefixing the string as well as new line. It finishes an action with possibility to continue in chaining.
• SERIAL_KEYVAL(k, v): Both arguments, key as well as value are variables, e.g., SERIAL_KEYVAL(varName, varValue). The macro adds colon and space after the first parameter and forms key-value pair output.
• SERIAL_VALUE(k, v): Flashes and prints the first string parameter (key) and follows it with second parameter (value) with EOL, e.g., SERIAL_VALUE("Value", 85). The macro adds colon and space after the first parameter and forms key-value pair output.
• SERIAL_VALUE_VALUE(k1, v1, k2, v2): Prints two key-value pairs in consecutive form in one line, e.g., SERIAL_VALUE_VALUE("Value1", 11, "Value2, 22).
• SERIAL_VALUE_HEX(k, v): Flashes and prints the first string parameter (key) and follows it with second parameter (value) in hexadecimal form prefixed with "0x", and finished with EOL, e.g., SERIAL_VALUE("Address", 85). The macro adds colon and space after the first parameter and forms key-value pair output. This macro is useful for displaying hexadecimal addresses.
• SERIAL_VALUE_TELEPLOT(k, v): Output for Teleplot extension in Microsoft Visual Source Code. Flashes and prints the first string parameter (key) prefixed with character ">", suffixed with character ":" without space, and follows it with second parameter (value) with EOL, e.g., SERIAL_VALUE_TELEPLOT("Value", 85), which outputs as ">Value:85".
• SERIAL_VALUE_UNIT(k, v, u): Flashes and prints the first string parameter (key), follows it with second parameter (value), and appends the third string parameter (unit) with EOL, e.g., SERIAL_VALUE_UNIT("Value", 85, "°C"). The macro adds colon and space after the first parameter, space before the last parameter, and forms key-value-unit output.

Decoration macros

• SERIAL_LINE: Prints empty line with EOL separating printing sections.
• SERIAL_DELIM: Flashes and prints three dashes as a delimiter line and EOL for visual separating printing sections.
• SERIAL_DOT: Flashes and prints dot without EOL for mimicking waiting for long lasting actions.

Formatting macros

!!! Following macros are available only for ESP32 platform !!!

• SERIAL_PRINTLN_FMT(p, f): Wrapper for system Serial.println with format as in the standard function sprintf() or strptime.
• SERIAL_LOG1_FMT(p1, f): Prints one formated parameter on the separate line with EOL (end of line) with format as in the standard function sprintf() or strptime, e.g., SERIAL_LOG1(123, "%X").
• SERIAL_VALUE_FMT(k, v, f): Flashes and prints the first string parameter (key) and follows it with second parameter (value) with EOL formatted as in the standard function sprintf() or strptime, e.g., SERIAL_VALUE("Value", 85, "%X"). The macro adds colon and space after the first parameter and forms key-value pair output.