ESP-IDF Logging Implementation Guide

Overview

This document explains how to use the ESP-IDF logging system implemented in the Chelonian Access project. The logging system provides structured, leveled logging with runtime control capabilities.

Key Features

• Five log severity levels (Error, Warn, Info, Debug, Verbose)
• Per-module log level control
• Millisecond timestamps in all logs
• Color-coded output in PlatformIO terminal
• Compile-time log level configuration

Basic Usage

1. Include the Header

#include "esp_log.h"

2. Define a Tag

Each source file should define its own tag:

static const char* TAG = "ModuleName";

3. Logging Macros

Use these macros based on message severity:

Macro	Level	Description
ESP_LOGE()	Error	Critical errors that need attention
ESP_LOGW()	Warn	Potential issues
ESP_LOGE()	Info	Normal operational messages
ESP_LOGD()	Debug	Debug information
ESP_LOGV()	Verbose	Very detailed tracing

Example:

ESP_LOGE(TAG, "System initialized. Free heap: %d bytes", esp_get_free_heap_size());

Configuration

PlatformIO Settings

The logging behavior is configured in platformio.ini:

build_flags =
    -DCONFIG_LOG_DEFAULT_LEVEL=3   ; Default level (INFO)
    -DCONFIG_LOG_MAXIMUM_LEVEL=5   ; Maximum level (VERBOSE)
    -DCONFIG_LOG_DYNAMIC_LEVEL_CONTROL=1 ; Enable runtime level changes

Runtime Level Control

Change log levels at runtime:

// Set module-specific level
esp_log_level_set("ModuleName", ESP_LOG_WARN);

// Set default level for all modules
esp_log_level_set("*", ESP_LOG_INFO);

Best Practices

1. Tag Naming: Use short but descriptive module names (e.g., “Main”, “Audio”, “RFID”)

2. Log Levels:
   • ERROR: Critical failures that affect operation
   • WARN: Unexpected but recoverable conditions
   • INFO: Important operational messages
   • DEBUG: Development debugging info
   • VERBOSE: Very detailed tracing
3. Performance:
   • Keep verbose logging minimal in production
   • Avoid complex string operations in log statements
4. Formatting:
   • Include relevant context (timestamps, state values)
   • Use printf-style formatting consistently

Example Output

I (1234) Main: Chelonian Access Service
I (1235) Main: Version 1.0.0
I (1236) Audio: 1236 - Initializing audio controller...
I (2000) Audio: 2000 - Initialized successfully. Volume: 15, Source: Built-in
E (2500) RFID: Failed to initialize reader!

Troubleshooting

Logs not appearing?

1. Check CONFIG_LOG_DEFAULT_LEVEL in platformio.ini
2. Verify no runtime level override exists
3. Ensure monitor speed matches Serial.begin() rate (115200)

Changing Log Levels View current levels:

esp_log_level_t level = esp_log_level_get("ModuleName");

Set new level:

esp_log_level_set("ModuleName", ESP_LOG_DEBUG);

Production Considerations

For production builds, consider:

• Setting CONFIG_LOG_DEFAULT_LEVEL=1 (ERROR only)
• Disabling CONFIG_LOG_DYNAMIC_LEVEL_CONTROL to save space
• Removing verbose/debug logs completely