Simple application log library. supporting multiple log levels, custom output & flash memory support.

ArduinoLog logo ArduinoLog - C++ Log library for Arduino devices

Build Status License

An minimalistic Logging framework for Arduino-compatible embedded systems.

ArduinoLog is a minimalistic framework to help the programmer output log statements to an output of choice, fashioned after extensive logging libraries such as log4cpp ,log4j and log4net. In case of problems with an application, it is helpful to enable logging so that the problem can be located. ArduinoLog is designed so that log statements can remain in the code with minimal performance cost. In order to facilitate this the loglevel can be adjusted, and (if your code is completely tested) all logging code can be compiled out.

Features

  • Different log levels (Error, Info, Warn, Debug, Verbose )
  • Supports multiple variables
  • Supports formatted strings
  • Supports formatted strings from flash memory
  • Fixed memory allocation (zero malloc)
  • MIT License

Tested for

  • All Arduino boards (Uno, Due, Mini, Micro, Yun...)
  • ESP8266
  • ESP32

Downloading

This package has been published to the Arduino & PlatformIO package managers, but you can also download it from GitHub.

  • By directly loading fetching the Archive from GitHub:
  1. Go to https://github.com/thijse/Arduino-Log
  2. Click the DOWNLOAD ZIP button in the panel on the
  3. Rename the uncompressed folder Arduino-Log-master to Arduino-Log.
  4. You may need to create the libraries subfolder if its your first library.
  5. Place the Arduino-Log library folder in your /libraries/ folder.
  6. Restart the IDE.
  7. For more information, read this extended manual

Quick start

    Serial.begin(9600);
    
    // Initialize with log level and log output. 
    Log.begin   (LOG_LEVEL_VERBOSE, &Serial);
    
    // Start logging text and formatted values
    Log.errorln (  "Log as Error   with binary values             : %b, %B"    , 23  , 345808);
    Log.warning (F("Log as Warning with integer values from Flash : %d, %d"CR) , 34  , 799870);

See Log-basic.ino example

Usage

Initialisation

The log library needs to be initialized with the log level of messages to show and the log output. The latter will often be the Serial interface. Optionally, you can indicate whether to show the log type (error, debug, etc) for each line.

begin(int level, Print* logOutput, bool showLevel)
begin(int level, Print* logOutput)

The loglevels available are

* 0 - LOG_LEVEL_SILENT     no output 
* 1 - LOG_LEVEL_FATAL      fatal errors 
* 2 - LOG_LEVEL_ERROR      all errors  
* 3 - LOG_LEVEL_WARNING    errors, and warnings 
* 4 - LOG_LEVEL_NOTICE     errors, warnings and notices 
* 5 - LOG_LEVEL_TRACE      errors, warnings, notices & traces 
* 6 - LOG_LEVEL_VERBOSE    all 

example

Log.begin(LOG_LEVEL_ERROR, &Serial, true);

if you want to fully remove all logging code, uncomment #define DISABLE_LOGGING in ArduinoLog.h, this may significantly reduce your sketch/library size.

Log events

The library allows you to log on different levels by the following functions

void fatal   (const char *format, va_list logVariables); 
void error   (const char *format, va_list logVariables);
void warning (const char *format, va_list logVariables);
void notice  (const char *format, va_list logVariables);
void trace   (const char *format, va_list logVariables);
void verbose (const char *format, va_list logVariables);

where the format string can be used to format the log variables

* %s	display as string (char*)
* %S    display as string from flash memory (__FlashStringHelper* or char[] PROGMEM)
* %c	display as single character
* %C    display as single character or as hexadecimal value (prefixed by `0x`) if not a printable character
* %d	display as integer value
* %l	display as long value
* %u	display as unsigned long value
* %x	display as hexadecimal value
* %X	display as hexadecimal value prefixed by `0x` and leading zeros
* %b	display as binary number
* %B	display as binary number, prefixed by `0b`
* %t	display as boolean value "t" or "f"
* %T	display as boolean value "true" or "false"
* %D,%F display as double value
* %p    display a  printable object 

Newlines can be added using the CR keyword or by using the ...ln version of each of the log functions. The difference when using the ...ln is that the newline is placed after suffix, and only a single newline can be added. Some terminals prefer NL (New line).

Examples

Log.fatal     (F("Log as Fatal   with string value from Flash   : %s"CR    ) , "value"     );
Log.errorln   (  "Log as Error   with binary values             : %b, %B"    , 23  , 345808);
Log.warning   (F("Log as Warning with integer values from Flash : %d, %d"CR) , 34  , 799870);
Log.notice    (  "Log as Notice  with hexadecimal values        : %x, %X"CR  , 21  , 348972);
Log.trace     (  "Log as Trace   with Flash string              : %S"CR    ) , F("value")  );
Log.verboseln (F("Log as Verbose with bool value from Flash     : %t, %T"  ) , true, false );

Disable library

(if your code is completely tested) all logging code can be compiled out. Do this by uncommenting

#define DISABLE_LOGGING 

in Logging.h. This may significantly reduce your project size.

Advanced usage

Advanced features are demonstrated in Log-advanced example.

Displaying a printable object

Some Arduino objects are printable. That is, they implement the Printable interface and are able for format their own representation As an example, the IPadress object is printable:

IPAddress   ipAddress(192, 168, 0, 1);
Log.verboseln ("ip address   : %p", ipAddress);

this example shows how to make your own classes printable

Storing messages in Flash memory

Flash strings log variables can be stored and reused at several places to reduce final hex size.

const __FlashStringHelper * logAs = F("Log as");
Log.fatal   (F("%S Fatal with string value from Flash   : %s"CR    ) , logAs, "value"     );
Log.error   (  "%S Error with binary values             : %b, %B"CR  , logAs, 23  , 345808);

If you want to declare that string globally (outside of a function), you will need to use the PROGMEM macro instead.

const char LOG_AS[] PROGMEM = "Log as ";

void logError() {
    Log.error   (  "%S Error with binary values : %b, %B"CR  , PSTRPTR(LOG_AS), 23  , 345808);
}

Custom logging format

You can modify your logging format by defining a custom prefix & suffix for each log line. For example:

void printPrefix(Print* _logOutput, int logLevel) {
    printTimestamp(_logOutput);
    printLogLevel (_logOutput, logLevel);
}

will result in log timestamps very similar to e.g. NLOG:

00:47:51.432 VERBOSE Message to be logged

Credit

Based on library by

Bugfixes & features by

On using and modifying libraries

Copyright

ArduinoLog (Copyright © 2017,2018, 2019, 2021) is provided under MIT License.

Comments
  • Make ArduinoLog work on  native (x86_64) environments for testing

    Make ArduinoLog work on native (x86_64) environments for testing

    When compiling on a native (x86-64) platform for unit tests under PlatformIO, the compilation fails because of problems with va_list/array. This addresses that compilation problem based on the answers given here: https://stackoverflow.com/questions/8047362/is-gcc-mishandling-a-pointer-to-a-va-list-passed-to-a-function

  • Fixed inconsistent styling and added ability to modify level/showLevel after init

    Fixed inconsistent styling and added ability to modify level/showLevel after init

    I have the use case that I want to change the loglevel on the fly when running a program. This pull request adds getters and setters to be able to change the loglevel and showLog after init.

    I also noticed that the styling was very inconsistent with different comment styles mixed, function parameters were spaces where placed differently and tabs/spaces where mixed. So I brought it together into a single style.

  • Added a S format specifier for flash stored string

    Added a S format specifier for flash stored string

    Using this format specifier, you can format a string using flash stored arguments.

    const __FlashStringHelper * anArgument = F("Something");
    Log.verbose("%S happened !", anArgument);
    

    I'm using it for a while now in a project to output formatted AT commands to a SIM808 chip while keeping the memory footprint as small as possible.

  • Remove unsupported `ln` methods from documentation

    Remove unsupported `ln` methods from documentation

    First of all thank you for maintaining this library! Was looking for something exactly like this. 👌

    It's probably me doing something stupid, but it seems like the noticeln etc methods aren't yet supported?

    error: 'class Logging' has no member named 'noticeln'
    

    The doc additions in

    • https://github.com/thijse/Arduino-Log/commit/c5bc8d9b86f7505dc01d9329cfd440b58e5a1122
    • https://github.com/thijse/Arduino-Log/commit/2cdacbbab14901c03057a3bcdcdeca544c564a41

    suggest differently however, and having these methods would be super useful! 😅

    So again, it's probably me misunderstanding something 🙇, but just in case not, seems like it would be better to leave them out of the docs for now to avoid confusion?

  • Add prefix and suffix possibility

    Add prefix and suffix possibility

    My use case for prefix is to print a timestamp at start of each log line. The suffix function can be used to avoid having to add "CR" at the end of each log message.

    The varadic template used to clean up the code requires C++11. The Arduino IDE supports C++11 since Jul 16, 2015 (version 1.6.6 it seems) so I don'think it will cause problems, but feedback is welcome.

  • Make ArduinoLog usable in native Tests

    Make ArduinoLog usable in native Tests

    When writing unit tests for Arduino classes with ArduinoLog, these classes should be testable in an native environment (on the CI System). So it is useful, that ArduinoLog can be compiled and linked in a native test system.

    The changes will add

    • includes if UNIT_TEST is defined
    • PGM resources, which are needed for compilation, if PGM is undefined.
  • Create a PlatformIO example and unit test

    Create a PlatformIO example and unit test

    $ pio test -e native
    Verbose mode can be enabled via `-v, --verbose` option
    Collected 1 items
    
    Processing * in native environment
    --------------------------------------------------------------------------------------------------------------------------------------------------------------------
    Building...
    Testing...
    test/test_native.cpp:313:test_int_values        [PASSED]
    test/test_native.cpp:314:test_int_hex_values    [PASSED]
    test/test_native.cpp:315:test_int_binary_values [PASSED]
    test/test_native.cpp:316:test_long_values       [PASSED]
    test/test_native.cpp:317:test_bool_values       [PASSED]
    test/test_native.cpp:318:test_char_string_values        [PASSED]
    test/test_native.cpp:319:test_flash_string_values       [PASSED]
    test/test_native.cpp:320:test_string_values     [PASSED]
    test/test_native.cpp:321:test_float_values      [PASSED]
    test/test_native.cpp:322:test_double_values     [PASSED]
    test/test_native.cpp:323:test_mixed_values      [PASSED]
    test/test_native.cpp:324:test_log_levels        [PASSED]
    test/test_native.cpp:325:test_prefix_and_suffix [PASSED]
    
    -----------------------
    13 Tests 0 Failures 0 Ignored
    OK
    ==================================================================== [PASSED] Took 5.54 seconds ====================================================================
    
    Test    Environment    Status    Duration
    ------  -------------  --------  ------------
    *       native         PASSED    00:00:05.542
    =================================================================== 1 succeeded in 00:00:05.542 ===================================================================
  • Remove incorrect exclude

    Remove incorrect exclude

    PlatformIO can't pick up the source code correctly due to the incorrect exclude definition (folder doesn't exist) and the broken JSON (trailing array comma). Removing the definition and the comma fixes that.

  • Fix ArduinoLog not compiling with #define DISABLE_LOGGING

    Fix ArduinoLog not compiling with #define DISABLE_LOGGING

    Before i got this error:

    In file included from src/main.h:3:0,                                                                                                                                 
                     from src/main.cpp:1:                                                                                                                                 
    .pio/libdeps/uno/ArduinoLog/ArduinoLog.h: In member function 'void Logging::print(const Printable&, va_list)':                                                        
    .pio/libdeps/uno/ArduinoLog/ArduinoLog.h:329:3: error: '_logOutput' was not declared in this scope                                                                    
       _logOutput->print(obj);                                                                                                                                            
       ^                                                                                                                                                                  
    In file included from src/main.h:7:0,                                                                                                                                 
                     from src/main.cpp:1: 
    
  • Make Arduino-Log usable in native Tests.

    Make Arduino-Log usable in native Tests.

    Native Tests are much faster, but need to be abstracted from the arduino framework. So building wrappers around builtins such as "Serial" is appreciated. This can also be done with a logging framework. So it should compile with the native target.

  • Remove invalid reference link from keywords.txt

    Remove invalid reference link from keywords.txt

    The third field of keywords.txt is used to provide Arduino Language/Libraries Reference links, which are accessed from the Arduino IDE by highlighting the keyword and then selecting "Find in Reference" from the Help or right click menu. Adding values to this field that do not match any existing reference pages results in a "Could not open the URL" error.

    Reference: https://github.com/arduino/Arduino/wiki/Arduino-IDE-1.5:-Library-specification#keywordstxt-format

  • Namespace Log Level Defines

    Namespace Log Level Defines

    I'm using Arduino Log in a project with other libraries that already have defines set up for LOG_LEVEL_ERROR amongst other things. This causes a number of warnings at compile time (and some strange behavior in the logs).

    This PR renames the #defines to prepend ARDUINO_LOG_ thereby effectively namespacing them.

  • Switch to official platformio library and fix broken tests

    Switch to official platformio library and fix broken tests

    • The C Preprocessor treats undefined as 0, so WProgram.h was being selected for unit tests.
    • The functions used for Suffix and Prefix in the platformio example were made using a previous version so the typedef was incorrect.
    • Log.notice prefixes with an I and not an N (ff0edc9).
Arduino library providing SPIFFS for the W25Q16DV flash on the MKR MEM shield.

Arduino_MKRMEM This library provides a driver for the Arduino MKR MEM Shield W25Q16DV SPI flash (with a capacity of 2 MByte) complete with integration

Mar 9, 2022
Arduino Library and code to flash CC2510, CC1110 or other Texas Instruments CCxxx Microcontroller
Arduino Library and code to flash CC2510, CC1110 or other Texas Instruments CCxxx Microcontroller

ESP CC flasher This software brings you the possibility to Read and Write the internal Flash of the Texas Instruments CC 8051 series with an ESP32 usi

Nov 11, 2022
Mnemosyne: efficient learning with powerful digital flash-cards.

Mnemosyne: Optimized Flashcards and Research Project Mnemosyne is: a free, open-source, spaced-repetition flashcard program that helps you learn as ef

Dec 24, 2022
Arduino library for making an IHC in or output module using an Arduino

Introduction This is an Arduino library for making an IHC in or output module using an Arduino. (IHC controller is a home automation controller made b

Mar 26, 2020
ESPHome custom component for Linptech G6L-WIFI

ESPHome custom component for Linptech G6L-WIFI (linp-doorbell-g04) Background The Linptech G6L-WIFI is a wifi doorbell with a self-powered button. It'

Dec 16, 2022
Arduino library for MQTT support

Adafruit MQTT Library Arduino library for MQTT support, including access to Adafruit IO. Works with the Adafruit FONA, Arduino Yun, ESP8266 Arduino pl

Jan 6, 2023
Frontend web application to control an arduino

Arduino Smart Blinds Frontend web application to control an arduino This project aims at created a frontent web page that communicates with an arduino

Jan 23, 2022
Arduino support for TinyUSB stack

Adafruit TinyUSB Library for Arduino This library is a Arduino-friendly version of TinyUSB stack. It is designed with structure and APIs that are easi

Jan 5, 2023
Arduino library with basic ANSI display codes for simple terminal apps

ANSI Arduino library with basic ANSI display codes for terminal applications. Description ANSI codes are special codes that are send to a terminal e.g

Aug 14, 2022
A simple C++ API client for the Ark Blockchain.
A simple C++ API client for the Ark Blockchain.

Ark C++ - Client A simple C++ API client for the Ark Blockchain. Lead Maintainer: Simon Downey Documentation You can find installation instructions an

Jan 21, 2022
ESP32IGate Simple Project
ESP32IGate Simple Project

ESP32IGate Simple Project ESP32IGate is a Internet Gateway + TNC Built in that is implemented for Espressif ESP32 processor. The development of ESP32I

Dec 19, 2022
A simple two-axis gimbal built using two servo motors, an mpu6050 gyro and accelerometer sensor, and an Arduino (Uno)
A simple two-axis gimbal built using two servo motors, an mpu6050 gyro and accelerometer sensor, and an Arduino (Uno)

Makeshift Gimbal Project A simple two-axis gimbal built using two servo motors, an mpu6050 gyro and accelerometer sensor, and an Arduino (Uno). A shor

Jun 17, 2022
Simple web interface builder for esp8266 and ESP32
Simple web interface builder for esp8266 and ESP32

GyverPortal Простой конструктор веб интерфейса для esp8266 и ESP32 Простой конструктор - делаем страницы без знаний HTML и CSS Библиотека является обё

Jan 8, 2023
This is a simple Arduino build that is capable of shiny hunting legendaries in 4th generation pokemon games through soft resetting.
This is a simple Arduino build that is capable of shiny hunting legendaries in 4th generation pokemon games through soft resetting.

This is a simple Arduino build that is capable of shiny hunting legendaries in 4th generation pokemon games through soft resetting.

May 6, 2022
The Approximate Library is a WiFi Arduino library for building proximate interactions between your Internet of Things and the ESP8266 or ESP32
The Approximate Library is a WiFi Arduino library for building proximate interactions between your Internet of Things and the ESP8266 or ESP32

The Approximate Library The Approximate library is a WiFi Arduino Library for building proximate interactions between your Internet of Things and the

Dec 7, 2022
Arduino Arduino library for the CloudStorage server project. The library provides easy access to server-stored values and operations.

Arduino-CloudStorage Arduino/ESP8266 library that allows you to easly store and retreive data from a remote (cloud) storage in a key/value fashion. Cl

Jan 30, 2022
Arduino library for controlling the MCP2515 in order to receive/transmit CAN frames.
Arduino library for controlling the MCP2515 in order to receive/transmit CAN frames.

107-Arduino-MCP2515 Arduino library for controlling the MCP2515 in order to receive/transmit CAN frames. This library is prepared to interface easily

Nov 16, 2022
Arduino library for interfacing with any GPS, GLONASS, Galileo or GNSS module and interpreting its NMEA messages.
Arduino library for interfacing with any GPS, GLONASS, Galileo or GNSS module and interpreting its NMEA messages.

107-Arduino-NMEA-Parser Arduino library for interfacing with any GPS, GLONASS, Galileo or GNSS module and interpreting its NMEA messages. This library

Jan 1, 2023
Arduino library for providing a convenient C++ interface for accessing UAVCAN.
Arduino library for providing a convenient C++ interface for accessing UAVCAN.

107-Arduino-UAVCAN Arduino library for providing a convenient C++ interface for accessing UAVCAN (v1.0-beta) utilizing libcanard. This library works f

Jan 2, 2023