Logging

Simple console logging macros with config level control. More...

Macros
#define	EIF_TAG_WITH_UNUSED   static const char* const TAG __attribute__((unused)) =
	Helper to define a local logging 'TAG' identifier. More...
#define	EIF_PRINT(m_macro, m_format, ...)   m_macro(TAG, "%s:%d (%s) " m_format, __FILE__, __LINE__, __func__, ##__VA_ARGS__)
	Low-level macro to format and output messages to the ESP log system. More...
#define	EIF_SHOW_ESP_ERR_T(m_result, m_expr, m_format, ...)
	Unconditionally executes an expression and logs warning details on failure. More...

Logging Severity Levels
#define	EIF_LOG_LEVEL_E   1
	Error log level severity.
#define	EIF_LOG_LEVEL_W   2
	Warning log level severity.
#define	EIF_LOG_LEVEL_I   3
	Informational log level severity.
#define	EIF_LOG_LEVEL_D   4
	Debug log level severity.

Application Logging Interface
Main logging macros with global compile-time filtering. Use these macros to print logs to the console. Which logs actually get compiled into the firmware depends on the CONFIG_EIF_LOG_LEVEL value. A logging macro works only if CONFIG_EIF_LOG_LEVEL is equal to or higher than its corresponding severity level constant (from 1 to 4). For example: if CONFIG_EIF_LOG_LEVEL is set to EIF_LOG_LEVEL_W (2), then EIF_LOG_E and EIF_LOG_W will print logs normally. However, EIF_LOG_I and EIF_LOG_D will be completely ignored. When a log level is ignored, its macro turns into an empty ((void)0U). The compiler completely deletes these lines and their text strings. Note All macros in this interface implicitly rely on a TAG identifier being defined and accessible within the current execution scope. Parameters [in] ... Format string compliant with standard printf specifiers, followed by matching variadic arguments. Example of use: #include <esp_log.h> #include <esp_iot_framework_core_macros.h> void check_system_health(float voltage, bool is_connected) { EIF_TAG_WITH_UNUSED "HEALTH"; // Required for EIF_LOG_x if (voltage < 3.2f) { EIF_LOG_E("Voltage critical: %.2fV", voltage); } else if (!is_connected) { EIF_LOG_W("Node offline, but voltage is OK (%.2fV)", voltage); } else { EIF_LOG_I("System healthy"); } }
#define	EIF_LOG_E(...)   EIF_PRINT(ESP_LOGE, __VA_ARGS__)
	Logs an error message using the ESP_LOGE severity.
#define	EIF_LOG_W(...)   EIF_PRINT(ESP_LOGW, __VA_ARGS__)
	Logs a warning message using the ESP_LOGW severity.
#define	EIF_LOG_I(...)   EIF_PRINT(ESP_LOGI, __VA_ARGS__)
	Logs an informational message using the ESP_LOGI severity.
#define	EIF_LOG_D(...)   EIF_PRINT(ESP_LOGD, __VA_ARGS__)
	Logs a debug message using the ESP_LOGD severity.

Detailed Description

This group contains macros for printing formatted messages to the console output. The output style and threshold level are configured via Kconfig.

Macro Definition Documentation

EIF_TAG_WITH_UNUSED

#define EIF_TAG_WITH_UNUSED   static const char* const TAG __attribute__((unused)) =

This macro declares a string named TAG. It automatically adds an unused attribute ([[maybe_unused]] for C++, __attribute__((unused)) for C or nothing if the compiler does not support it) to suppress compiler warnings and satisfy MISRA C requirements when all logging macros in the scope are stripped out by the preprocessor.

Note

This macro is intended for use inside functions (within local scopes). It allows defining a local logging context within a specific scope, fully complying with the MISRA C rule that strictly forbids the use of #undef.

Example of use:

#include <esp_log.h>
#include <esp_iot_framework_core_macros.h>
 
void process_sensor_event(void) {
    EIF_TAG_WITH_UNUSED "SHT3X_DRV";
 
    // Logic here...
 
    EIF_LOG_D("Data processed");
}

EIF_PRINT

#define EIF_PRINT	(		m_macro,
			m_format,
			...
	)		m_macro(TAG, "%s:%d (%s) " m_format, __FILE__, __LINE__, __func__, ##__VA_ARGS__)

This macro forwards messages directly to the ESP logging system. It implicitly uses the local TAG variable, which must be defined in the current scope.

Note

This macro implicitly relies on a TAG identifier being defined and accessible within the current scope. Behavior depends on the CONFIG_EIF_LOG_SHOW_METADATA configuration:

• Enabled: Automatically injects source metadata (file name, line number, and function name) at the beginning of the log message. Example of output to the console:

  I (8536) HTTPS server: src/network.c:79 (mdns_initialize) mDNS started. Link: https://device-aabbcc.local

• Disabled: Outputs the pure log message without any metadata. Example of output to the console:

  I (8536) HTTPS server: mDNS started. Link: https://device-aabbcc.local

Parameters

[in]	m_macro	Target ESP-IDF logging macro (e.g., ESP_LOGI, ESP_LOGW, ESP_LOGE).
[in]	m_format	Format string compatible with printf.
[in]	...	Optional variadic arguments for the format string.

Example of use:

#include <esp_log.h>
#include <esp_system.h>
#include <esp_iot_framework_core_macros.h>
 
#define TAG "SYS_MON"
 
void monitor_heap_usage(void) {
    uint32_t free_heap = esp_get_free_heap_size();
    if (free_heap < 10 * 1024) {
        EIF_PRINT(ESP_LOGW, "Critical memory level: %u bytes remaining!", free_heap);
    }
}

EIF_SHOW_ESP_ERR_T

#define EIF_SHOW_ESP_ERR_T	(		m_result,
			m_expr,
			m_format,
			...
	)

Value:

do { \
    (m_result) = (m_expr); \
    if ((m_result) != (ESP_OK)) { \
        const char* l_err_name = esp_err_to_name((m_result)); \
        EIF_LOG_W("%s: " m_format, \
            ((l_err_name != NULL) ? l_err_name : "UNKNOWN_ERROR") \
            /* @deviation [Rule 20.10] The '##' token pasting operator is
             * utilized strictly for the compiler-specific comma deletion
             * extension. The expansion is completely deterministic and
             * guaranteed to yield valid, predictable syntax without risk of
             * expression corruption. */ \
            , ##__VA_ARGS__); \
    } \
} while (false)

This macro executes the expression m_expr regardless of any previous status. If the resulting execution status is not ESP_OK, it fetches the error name via esp_err_to_name() and outputs a warning-level log containing the failure context. The execution status is always written to m_result. It is ideal for cleanup blocks or logging forced actions, such as closing sockets before restarting.

Warning

This macro runs unconditionally and will overwrite the previous value of m_result. Do not use it inside sequential checking chains (EIF_IF_OK_*) as it can mask earlier initialization failures.

Parameters

[out]	m_result	Status variable (esp_err_t) to store the execution result. The previous value is overwritten unconditionally.
[in]	m_expr	The function call or expression returning esp_err_t.
[in]	m_format	Printf-compliant format string for warning details.
[in]	...	Optional variadic arguments matching the format string.

Example of use:

#include <esp_log.h>
#include <esp_wifi.h>
#include <nvs_flash.h>
#include <esp_iot_framework_core_macros.h>
 
void system_reboot_prepare(void) {
    EIF_TAG_WITH_UNUSED "REBOOT";
    esp_err_t res = ESP_OK;
 
    // We attempt to stop services regardless of 'res' value.
    // If a step fails, we get a warning, but the sequence continues.
    EIF_SHOW_ESP_ERR_T(res, esp_wifi_stop(), "Wi-Fi stop failed");
    EIF_SHOW_ESP_ERR_T(res, nvs_flash_deinit(), "NVS deinit failed");
 
    esp_restart();
}