Skip to content

Latest commit

 

History

History
88 lines (64 loc) · 2.55 KB

ESP32_LOGGING.md

File metadata and controls

88 lines (64 loc) · 2.55 KB

ESP32-S3 USB CDC Logging

How to do debug logging on ESP32-S3 with USB CDC Serial.

The Problem

Standard ESP32 logging frameworks don't work with USB CDC Serial:

Framework Issue
esp_log (ESP-IDF) Arduino Core 3.0.1 compiles with CONFIG_LOG_MAXIMUM_LEVEL=1 (Error only), so INFO/DEBUG are removed at compile time
esp32-hal-log (log_i, etc.) Uses ets_write_char_uart which writes to UART0, not USB CDC

The Solution

Custom macros using Serial.printf directly. Defined in log.h:

// Log levels
#define LOG_LEVEL_NONE    0
#define LOG_LEVEL_ERROR   1
#define LOG_LEVEL_WARN    2
#define LOG_LEVEL_INFO    3
#define LOG_LEVEL_DEBUG   4

#ifndef LOG_LEVEL
#define LOG_LEVEL LOG_LEVEL_INFO
#endif

// Color-coded log macros
#define ESP_LOGE(tag, format, ...) do { if (LOG_LEVEL >= LOG_LEVEL_ERROR) Serial.printf("\033[31mE (%lu) %s: " format "\033[0m\n", millis(), tag, ##__VA_ARGS__); } while(0)
#define ESP_LOGW(tag, format, ...) do { if (LOG_LEVEL >= LOG_LEVEL_WARN)  Serial.printf("\033[33mW (%lu) %s: " format "\033[0m\n", millis(), tag, ##__VA_ARGS__); } while(0)
#define ESP_LOGI(tag, format, ...) do { if (LOG_LEVEL >= LOG_LEVEL_INFO)  Serial.printf("\033[32mI (%lu) %s: " format "\033[0m\n", millis(), tag, ##__VA_ARGS__); } while(0)
#define ESP_LOGD(tag, format, ...) do { if (LOG_LEVEL >= LOG_LEVEL_DEBUG) Serial.printf("\033[36mD (%lu) %s: " format "\033[0m\n", millis(), tag, ##__VA_ARGS__); } while(0)

// Predefined tags
constexpr const char* TAG_MAIN    = "Main";
constexpr const char* TAG_DISPLAY = "Display";
constexpr const char* TAG_TOUCH   = "Touch";
constexpr const char* TAG_WIFI    = "WiFi";
constexpr const char* TAG_SPOTIFY = "Spotify";

Usage

#include "log.h"

static const char *TAG = "MyModule";

ESP_LOGI(TAG, "Info message");
ESP_LOGW(TAG, "Warning: %s", warningText);
ESP_LOGE(TAG, "Error code: %d", errorCode);
ESP_LOGD(TAG, "Debug value: %d", debugValue);

Output Format

I (12345) Main: Info message
W (12400) WiFi: Warning: connection slow
E (12500) Spotify: Error code: 401
D (12600) Display: Debug value: 42
  • Timestamp in milliseconds since boot
  • Color-coded by level (requires ANSI-capable terminal)
  • Tag for filtering

Changing Log Level

Define LOG_LEVEL before including log.h:

#define LOG_LEVEL LOG_LEVEL_DEBUG
#include "log.h"

Or set it in a build flag.

Filtering Logs

Use arduwrap for regex filtering:

./tools/arduwrap log -f "error|fail" -i   # Case-insensitive filter
./tools/arduwrap log -f "Spotify"         # Filter by tag