To maintain a consistent and clean codebase, follow the style guide. This document provides detailed instructions on naming conventions, code structure, and commenting practices.

Please read the style_guide.md carefully before making contributions.

Editor Configuration

To help you adhere to the style guide, use the provided configuration files for the code formatters in your code editor. You can choose from the following options:

.clang-format:
- For Visual Studio Code and CLion users
- Or use the clang-format tool directly
eclipse_format.xml:
- For Eclipse-based editors, including STM32CubeIDE.
- You can import it within eclipse settings, Preferences -> LANGUAGE -> Code Style -> Formatter tab.

Logging and Debugging Messages

The logging system is designed to make log messages clearer and improve their uniformity across the project. It makes it easier to see where a log message comes from and what its verbosity is.

To use the logging system, include log.h in your source file, and use the following macros to print log messages:

LOG_DEBUG(TAG, fmt, ...)
LOG_INFO(TAG, fmt, ...)
LOG_WARN(TAG, fmt, ...)
LOG_ERROR(TAG, fmt, ...)

The same format specifiers as in printf can be used.

The TAG parameter is a string that identifies the source of the log message. It is recommended to use one tag for each source file / module, and to name the tag after the source file / module. See the example below.

Global Log Level

You can control the verbosity of the logging output by setting a global log level in log.h. This log level filters out messages with a lower priority.

Custom Log Levels

Additionally, you have the flexibility to override the log level for individual tags (but not lower than the global log level). This can be archived by calling the following function:

logger_set_level(LOG_TAG, LOG_LEVEL);

If the log level for a tag is not set, the global log level is used.

Colorful Log Messages

For improved readability, log messages can be printed in color by configuring LOGGER_USE_COLOR to 1 in log.h.

Log Output Format

Each log entry is formatted to include the following information:

Log level (D for Debug, I for Info, W for Warning, E for Error)
Timestamp (in milliseconds since boot)
Tag
The log message

For instance, a log entry may look like this:

I (2009) LTDC: This is a log message

Example

#include "log.h"

// Don't use a define for the tag, as the pointer to the tag is used
static const char *TAG = "main";

int main(void) {
    // Set log level for tag "main" to LOG_INFO
    logger_set_level(TAG, LOG_INFO);
    
    LOG_DEBUG(TAG, "This message will not be printed");
    LOG_INFO(TAG, "This message will be printed");
    LOG_WARN(TAG, "This message will be printed");
    LOG_ERROR(TAG, "This message will be printed");
    
    for (int i = 0; i < 3; i++) {
        LOG_INFO(TAG, "Iteration %d of %d", i, 3);
    }
    
    return 0;
}

Result:

I (2009) main: This message will be printed
W (2026) main: This message will be printed
E (2033) main: This message will be printed
I (2040) main: Iteration 0 of 3
I (2047) main: Iteration 1 of 3
I (2054) main: Iteration 2 of 3