Understanding Arduino Core Debug Level And Its Practical Applications

Arduino Core Debug Levels: Definition, Structure, and Implementation

The implementation of debug levels follows a severity-based hierarchy, where each level corresponds to a specific type of message. These levels are designed to prioritize critical errors while allowing granular visibility into system behavior for debugging purposes. Below is a structured breakdown of the levels, their intended use cases, and practical implementation methods.

Hierarchy and Severity of Debug Levels

- ERROR: Indicates critical failures that halt normal operation or require immediate attention.

Each level builds upon the previous one, ensuring that enabling a higher-level output automatically includes all lower-level messages. For example, enabling DEBUG will also display ERROR, WARN, and INFO messages.

Typical Output Content by Debug Level

Enabling Debug Output via Preprocessor Directives

// Enable INFO-level and above (ERROR, WARN, INFO)
#define ARDUINO_DEBUG_LEVEL 2 // Numeric equivalent of INFO

// Enable DEBUG-level and above (ERROR, WARN, INFO, DEBUG)
#define ARDUINO_DEBUG_LEVEL 3 // Numeric equivalent of DEBUG

Key Notes:

Example Implementation:

// In platformio.ini or sketch pre-processing section
build_flags =
-DARDUINO_DEBUG_LEVEL=3 // Compile-time definition

// In Arduino sketch
#include

void setup() {
Serial.begin(115200);
#if ARDUINO_DEBUG_LEVEL >= 2 // Check if INFO is enabled
Serial.println("System initialized at " + String(millis()) + "ms");
#endif
}

void loop() {
#if ARDUINO_DEBUG_LEVEL >= 3 // Check if DEBUG is enabled
Serial.printf("Loop iteration %d\n", iterationCount);
#endif
delay(1000);
}

Conditional Compilation Best Practices:

Dynamic Debug Level Adjustment

- Serial Command Interface: Send commands like `DEBUG_LEVEL 3` to adjust the threshold dynamically.

Example

Configuring Debug Levels in Arduino Core

The Arduino Core framework employs a hierarchical debug level system, where messages are categorized by severity (e.g., `ERROR`, `WARNING`, `INFO`, `DEBUG`, `VERBOSE`). These levels are mapped to numeric values, with higher values indicating more granular output. Configuration is board-specific and often tied to the underlying hardware’s capabilities, such as UART baud rates or memory constraints. Below are the structured methods for adjusting these settings, including file-based overrides and conditional compilation techniques.

Adjusting Debug Levels in Build System Files

PlatformIO Configuration (`platformio.ini`)
To set debug levels globally or per-board, use the `build_flags` or `board_build.flags` directives in `platformio.ini`. The following example demonstrates how to enforce a `VERBOSE` level for the Arduino Uno while keeping defaults for other boards:

[env:uno]
platform = atmelavr
board = uno
framework = arduino
build_flags =
-DDEBUG_LEVEL=VERBOSE
-DDBG_OUTPUT_PORT=Serial

Arduino IDE’s `platform.txt` Overrides
For custom board definitions, modify the `platform.txt` file in the Arduino Core repository or a local fork. Locate the `build.core` or `build.variant` sections and append debug-related compiler flags:

uno.build.core =
-DDEBUG_LEVEL=DEBUG
-DDBG_OUTPUT_PORT=Serial1

Key Directives

Overriding Default Debug Settings via Compiler Flags

Common Compiler Flag Formats
The following flags are widely supported across Arduino-compatible toolchains (e.g., AVR-GCC, ARM-GCC):

Example: Disabling Debug Output for Production
To minimize binary size in release builds, disable debug output entirely:

avr-g++ -DDEBUG_LEVEL=NONE -mmcu=atmega328p -o firmware.hex main.cpp

PlatformIO CLI Usage
In PlatformIO, pass flags via the `pio run` command:

pio run -e uno -DDEBUG_LEVEL=INFO

Common Debug-Related Macros and Their Customization

Dynamic Debug Level Switching via Conditional Compilation

// Define debug level at compile time (override via compiler flag)
// Example: -DDEBUG_LEVEL=VERBOSE
#ifndef DEBUG_LEVEL
#define DEBUG_LEVEL INFO // Default to INFO if not specified
#endif

// Numeric equivalents for comparison
#define DEBUG_LEVEL_NONE 0
#define DEBUG_LEVEL_ERROR 1
#define DEBUG_LEVEL_WARNING 2
#define DEBUG_LEVEL_INFO 3
#define DEBUG_LEVEL_DEBUG 4
#define DEBUG_LEVEL_VERBOSE 5

// Convert DEBUG_LEVEL to numeric value
#define DEBUG_LEVEL_VALUE \
(DEBUG_LEVEL == VERBOSE ? 5 : \
DEBUG_LEVEL == DEBUG ? 4 : \
DEBUG_LEVEL == INFO ? 3 : \
DEBUG_LEVEL == WARNING ? 2 : \
DEBUG_LEVEL == ERROR ? 1 : \
0)

// Debug output macro with conditional compilation
#define DBG_PRINT(level, ...) \
do { \
if (DEBUG_LEVEL_VALUE >= level) { \
#if (DEBUG_LEVEL_VALUE >= DEBUG_LEVEL_DEBUG) \
Serial.print("[DEBUG] "); \
#elif (DEBUG_LEVEL_VALUE >= DEBUG_LEVEL_INFO) \
Serial.print("[INFO] "); \
#elif (DEBUG_LEVEL_VALUE >= DEBUG_LEVEL_WARNING) \
Serial.print("[WARNING] "); \
#else \
Serial.print("[ERROR] "); \
#endif \
Serial.println(__VA_ARGS__); \
} \
} while (0)

// Example usage
void setup() {
Serial.begin(115200);
DBG_PRINT(DEBUG_LEVEL_INFO, "System initialized");
DBG_PRINT(DEBUG_LEVEL_DEBUG, "Debug message (visible if DEBUG_LEVEL >= DEBUG)");
}

void loop() {
DBG_PRINT(DEBUG_LEVEL_VERBOSE, "Loop iteration");
delay(1000);
}

Key Features of the Template
1. Compile-Time Override: The `DEBUG_LEVEL` macro can be set via compiler

Debugging Techniques Using Arduino Core Debug Levels

Effective debugging relies on selective logging to avoid overwhelming output while ensuring critical information is captured. The Arduino Core’s debug levels allow granular control over message visibility, enabling developers to focus on WARN or INFO logs when diagnosing specific issues. Additionally, redirecting debug messages to Serial, USB, or external storage (SD card) extends flexibility, while third-party libraries like ArduinoJson can parse and format logs for better interpretability. Proper log management ensures maintainable and scalable debugging processes, particularly in embedded systems with limited resources.

Filtering Debug Output for Issue Isolation

- ERROR: Critical failures requiring immediate attention.

To filter output, developers can use conditional checks within the `Serial` or logging framework. For example, enabling only WARN and ERROR logs in production reduces overhead while retaining essential alerts. Below is a structured approach to implementing selective logging:

Best Practice for Filtering:
Use preprocessor directives (`#define DEBUG_LEVEL`) to dynamically adjust log verbosity across development, testing, and production stages. Avoid hardcoding debug levels in production firmware to prevent unintended log exposure.

void setup() {
Serial.begin(9600);
while (!Serial); // Wait for Serial Monitor (for USB-based boards)

// Conditional logging based on DEBUG_LEVEL
#if DEBUG_LEVEL >= ERROR
Serial.println("Initializing system...");
#endif

#if DEBUG_LEVEL >= WARN
Serial.println("Warning: Low battery detected.");
#endif
}
```

Redirecting Debug Messages to Serial, USB, or External Storage

Serial and USB Output:
Arduino’s `Serial` class supports both hardware serial (e.g., `Serial` for USB on most boards) and software serial (e.g., `SoftwareSerial` for additional UART interfaces). USB-based debugging (via `SerialUSB` on boards like the Arduino Due or ESP32) ensures compatibility with tools like PlatformIO or Arduino IDE’s Serial Monitor.

SD Card Logging:
For long-term or field-deployed systems, logging to an SD card is preferable. Libraries like SPI or SDFat enable file-based logging with timestamps. Below is a basic implementation using the SD.h library:

```cpp
#include File logFile;

void setup() {
Serial.begin(9600);
if (!SD.begin(4)) { // Initialize SD card (CS pin 4)
Serial.println("SD Card initialization failed!");
return;
}
logFile = SD.open("debug.log", FILE_WRITE);
if (!logFile) {
Serial.println("Failed to open log file!");
return;
}
logFile.println("System initialized at " + String(millis()));
logFile.close();
}

void loop() {
#if DEBUG_LEVEL >= INFO
logFile = SD.open("debug.log", FILE_WRITE);
logFile.println("Loop iteration: " + String(millis()));
logFile.close();
#endif
delay(1000);
}
```

Key Considerations for Redirection:

Integrating Third-Party Libraries for Log Parsing and Formatting

Example: Structured Logging with ArduinoJson
```cpp
#include

void logEvent(const String& event, const String& details) {
StaticJsonDocument<200> doc;
doc["timestamp"] = millis();
doc["event"] = event;
doc["details"] = details;

String jsonOutput;
serializeJson(doc, jsonOutput);

#if DEBUG_LEVEL >= DEBUG
Serial.println(jsonOutput);
#endif

// Optionally log to SD card
File logFile = SD.open("debug.json", FILE_WRITE);
if (logFile) {
logFile.println(jsonOutput);
logFile.close();
}
}
```

Output Example:
```json
{"timestamp":123456789,"event":"sensor_error","details":"Temperature out of range"}
```

Benefits of Structured Logging:

Recommended Libraries:

Best Practices for Debug Logging in Arduino Projects

Debug Logging Best Practices:
1. Avoid Excessive Output in Production: Disable `DEBUG`/`VERBOSE` logs in release builds using `#ifdef` guards.
2. Use Consistent Formatting: Standardize log structures (e.g., timestamps, severity levels) for easier analysis.
3. Prioritize Critical Paths: Focus logging on initialization, error handling, and state transitions.
4. Minimize Blocking Operations: Avoid long `Serial.print()` calls in time-sensitive loops; use buffering where possible.
5. Secure Sensitive Data: Never log passwords, API keys, or user-specific data to external storage.
6. Document Log Levels: Clearly define the purpose of each debug level in project documentation.
7. Leverage Third-Party Tools: Use libraries like ArduinoJson or Log4duino to reduce boilerplate code.
8. Test Log Redirection Early: Verify SD card/USB logging works in hardware prototypes to avoid late-stage debugging.

// Production build (minimal logs)
#define DEBUG_LEVEL ERROR
```

By adhering to these practices, developers can create debug systems that are scalable, maintainable, and production-ready.

Advanced Debugging: Custom Debug Levels and Logging

Defining Custom Debug Levels Beyond Defaults

1. Extending the Log Level Enum
Modify the existing debug header (e.g., `ArduinoLog.h`) to include new levels such as `DEBUG_PERFORMANCE`, `DEBUG_STATE_MACHINE`, or `DEBUG_NETWORK`. Example:

typedef enum {
DEBUG_NONE = 0,
DEBUG_ERROR,
DEBUG_WARNING,
DEBUG_INFO,
DEBUG_VERBOSE, // Default levels
DEBUG_PERFORMANCE, // Custom: Timing metrics
DEBUG_STATE_MACHINE, // Custom: FSM transitions
DEBUG_RAW_DATA // Custom: Unprocessed sensor data
} ArduinoLogLevel;

2. Conditional Compilation for Flexibility
Use preprocessor directives to enable/disable custom levels based on build configurations:

#ifdef ENABLE_CUSTOM_DEBUG
#define DEBUG_PERFORMANCE_ENABLED
#endif

This ensures custom levels are only compiled when explicitly required, reducing binary size.

3. Runtime Configuration via Serial Commands
Implement a dynamic log level adjustment mechanism using serial commands (e.g., `LOG_LEVEL=PERFORMANCE`). This allows runtime reconfiguration without recompilation:

void setLogLevel(const String &level) {
if (level == "PERFORMANCE") {
currentLogLevel = DEBUG_PERFORMANCE;
}
// Additional levels...
}

Circular Buffer Implementation for Memory-Constrained Devices

1. Circular Buffer Structure
Define a fixed-size buffer with head/tail pointers to manage write/read operations:

struct CircularBuffer {
uint8_t buffer[LOG_BUFFER_SIZE]; // Adjust size (e.g., 256–1024 bytes)
volatile uint16_t head = 0;
volatile uint16_t tail = 0;
bool full = false;
};

Key Operations:

2. Size Optimization Techniques

3. Example: Atomic Write with Interrupts
Disable interrupts during critical sections to prevent race conditions:

void logToBuffer(const char *message, ArduinoLogLevel level) {
noInterrupts();
uint16_t nextHead = (head + strlen(message) + 1) % LOG_BUFFER_SIZE;
if (nextHead == tail) {
tail = (tail + 1) % LOG_BUFFER_SIZE; // Drop oldest entry
}
strcpy((char*)&buffer[head], message);
head = nextHead;
interrupts();
}

Structured Logging with JSON for Tool Integration

1. JSON Schema Design
Define a consistent schema for log entries to ensure compatibility:

{
"timestamp": "ISO8601",
"level": "DEBUG_ERROR|WARNING|INFO|...",
"module": "String",
"message": "String",
"data": {
"key1": "value1",
"key2": 123
}
}

Example: A sensor reading log:

{
"timestamp": "2023-11-15T14:30:00Z",
"level": "DEBUG_VERBOSE",
"module": "Temperature",
"message": "New reading",
"data": { "value": 23.5, "unit": "C" }
}

2. Dynamic JSON Generation
Use lightweight libraries like ArduinoJson (v6+) to construct JSON strings:

#include void logStructured(const char module, const char message, JsonObject data) {
DynamicJsonDocument doc(256);
doc["timestamp"] = getISO8601Time();
doc["level"] = currentLogLevel;
doc["module"] = module;
doc["message"] = message;
if (data) {
doc["data"] = data;
}
serializeJson(doc, Serial);
}

3. Performance Considerations

jq '. | select(.level == "DEBUG_ERROR")' logs.json

Advanced Debug Techniques Table