refactored

[2bndy5]

I've taken the journey toward cross-platform compatibility... Along the way I made the following changes.

Printf Parser changes

• Our parsing algorithm of imitating printf() is used by all platforms
• added a unique %b specifier to represent integers as binary
• \n chars are automatically triggering a newline+header info (timestamp, log level, vendorId). However the escaping mechanism can be used (as in %\n) to only output a newline (no new header info)
• \t char can be replaced with a number of spaces if RF24LOG_TAB_SIZE macro is defined (with a number as in the number of spaces to use instead of \t)
• data can be padded with spaces (default char) or zeros (by putting a zero in front of the padding quantity). This applies to chars as well, but not strings and not doubles/floats.
• double/floats accept a precision quantity (following a . char). If precision is set to zero (done when parser encounters a . char), then a zero value will not be printed. As of this writing, padding the whole number of a double/float value is not supported.

Lib structure

I have restructured the lib for conceptual reasons.

• all abstract stuff lives in a RF24LogAbtracts folder. I've added
  • an abstract stream class (housing all the function prototypes that child classes need to output data)
  • a parser class (housing all the actual parsing behavior of message input/args)
  • a specifier format class (housing all the data about any supported specifier options)
  • a common file to provide a function that determines the length of a number in chars.
• RF24LogHandler.h is now RF24LogBaseHandler.h (this file still exists in the top level of the src folder)
• Handlers that inherit from a abstract handler class and a abstract stream class are deemed "Loggers". The new RF24Loggers folder holds all currently supported output streams as end-use handlers. These loggers include:
  • ArduinoPrintLogger which was renamed from RF24StreamLogHandler.
  • NativePrintLogger for pico SDK and any platform that has printf() natively available
  • OStreamLogger for using C++'s ostream based objects as the output stream
• RF24LogDualHandler now lives in a handler_ext folder because any class that inherits from the RF24LogBaseHandler class but not from an abstract stream class is likely an extension to the base handler mechanism

CMake integration

Docs on how to use the CMake build system are pending a stable/reliable solution.

• CMake is working to compile the examples for the RP2040-based boards (using the Pico SDK)
• CMake is also currently working to build a SHARED lib and install it for Windows & Linux. The examples will need some more attention as the *.cpp example files should run on both PC and the RP2040-based boards.
• Added new github action workflows:
  • Cross-Compile & package: Demonstrates how to compile and install (or cross-compile) the lib & examples. This also creates installable packages (.deb & .rpm files) for different devices. This can be used as part of release assets to aid in installation.
  • RP2xxx build: compiles and uploads executable artifacts from the examples.
• cross-compiling is possible with the use of what CMake calls toolchain files. I current; have a toolchain_arm.cmake file for cross-compiling the library targeting arm devices. More toolchain files can be added with easy copy-n-paste (for example a file for the aarch64 toolchain).

some code changes

• I removed all relic functions (info(), debug(), error(), warn()) from earlier stages of development
• I renamed the singleton to rf24Logging as a present verb tense seems a better fit for the idea of a singleton. Also I renamed the RF24Logger.h file as RF24Logging.h to avoid confusion with the RF24Loggers folder.
• helper macros are now renamed to RF24Log_*() for some brevity
• removed an example that seemed like a duplicate of BasicSerialLogger.ino
• renamed example BasicSerialLogger.ino to gettingStarted.ino
• duplicated Arduino examples as *.cpp files because the Pico SDK can't find the int main() function in a *.ino
• log level descriptions can be changed with a couple optional macros: RF24LOG_SHORT_DESC and RF24LOG_TERSE_DESC
• Timestamp can be disabled by defining a macro RF24LOG_NO_TIMESTAMP
• the \n character (both in messages we parse ourselves and at the end of logged messages) can be nullified with the macro RF24_NO_EOL
• level numbers are now in octal when describing a non-main level ("Lvl 77" describes level 0x3F)
• All examples now take user input in the form of octal numbers to adjust filtering of messages in realtime.
• logging a message on level 0 skips the timestamp and level description -- the vendorId is still output, although passing an empty string as the vendorId will also skip outputting the vendorId and its corresponding delimiter. This should provide an easy way to dump formatted data to a file stream.
• new macro to reverse the ordering of the log levels. I've mentioned before that this is a matter of perspective, but I wanted to add this feature to please users that have a pre-existing experience with another logging library that doesn't use the same ordering of level verbosity. Defining this macro does not affect the expected operation of message filtering.

There may be more changes I haven't listed here...

[2bndy5]

oops! I didn't mean to merge this quite yet, but we can walk back any objections that arise. I just need to test the release assets here before we merge nRF24/RF24#772 which includes an almost identical CMake implementation.

Release assets will be key in users installing the RF24 libs without needing to build/install from source! maybe down the line we can host our own PPA repo...