ESPLogger

A lightweight, configurable logging utility for ESP32 projects. ESPLogger combines formatted log APIs, in-RAM batching, and optional background syncing so you can integrate storage or telemetry pipelines without blocking application code.

CI / Release / License

Features

• Familiar debug/info/warn/error helpers with printf formatting semantics.
• Configurable behavior: batching thresholds, FreeRTOS core/stack/priority, and console log level.
• Optional background sync task plus manual sync() for deterministic flushes.
• onSync callback hands over a vector of structured Log entries for custom persistence.
• Helpers to fetch every buffered log or just the most recent entries whenever you need diagnostics.
• Console output automatically routed through the ESP-IDF ESP_LOGx macros.

Examples

Minimal setup:

#include <ESPLogger.h>

static Logger logger;

void setup() {
    Serial.begin(115200);

    LoggerConfig cfg;
    cfg.syncIntervalMS = 5000;
    cfg.maxLogInRam = 100;
    cfg.consoleLogLevel = LogLevel::Info;
    logger.init(cfg);

    logger.onSync([](const std::vector<Log>& logs) {
        for (const auto& entry : logs) {
            // Persist logs to flash, send over Wi-Fi, etc.
        }
    });

    logger.info("INIT", "Logger initialised with %u entries", cfg.maxLogInRam);
}

void loop() {
    logger.debug("LOOP", "Loop iteration at %lu ms", static_cast<unsigned long>(millis()));
    delay(1000);
}

Scope a logger inside your own class:

class SensorModule {
  public:
    explicit SensorModule(Logger& logger) : _logger(logger) {}

    void update() {
        const float reading = analogRead(A0) / 1023.0f;
        _logger.info("SENSOR", "Latest reading: %.2f", reading);
    }

  private:
    Logger& _logger;
};

Example sketches:

• examples/basic_usage – minimal configuration + periodic logging.
• examples/custom_sync – manual syncing with a custom persistence callback.

Gotchas

• Keep Logger instances alive for as long as their sync task may run; destroying the object stops the task.
• When enableSyncTask is false, remember to call logger.sync() yourself or logs will stay buffered forever.
• setLogLevel only affects console output; all logs remain available inside the RAM buffer until purged.
• The onSync callback runs inside the sync task context—avoid blocking operations.

API Reference

• void init(const LoggerConfig& cfg = {}) – configure sync cadence, stack size, priorities, and thresholds.
• void debug/info/warn/error(const char* tag, const char* fmt, ...) – emit formatted logs.
• void setLogLevel(LogLevel level) / LogLevel logLevel() const – adjust console verbosity at runtime.
• void onSync(Logger::SyncCallback cb) – receive batches of Log entries whenever the buffer flushes.
• void sync() – force a flush (useful when the background task is disabled).
• std::vector<Log> getAllLogs() / std::vector<Log> getLastLogs(size_t count) – snapshot buffered entries.
• LoggerConfig currentConfig() const – inspect the live settings.

LoggerConfig knobs:

Field	Default	Description
syncIntervalMS	5000	Period between automatic flushes (ignored when enableSyncTask is false).
stackSize	4096	Stack size (words) for the sync task.
coreId	LoggerConfig::any	CPU core affinity for the sync task.
maxLogInRam	100	Maximum entries retained in RAM; oldest entries are discarded when the buffer is full.
taskPriority	1	FreeRTOS priority for the sync task.
consoleLogLevel	LogLevel::Debug	Minimum level printed to the console.
enableSyncTask	true	Disable to opt out of the background task and call logger.sync() manually.

Restrictions

• Built for ESP32 + FreeRTOS (Arduino or ESP-IDF) with C++17 enabled.
• Uses dynamic allocation for the RAM buffer; size maxLogInRam according to your heap budget.
• Console output routes through ESP-IDF logging, so set CONFIG_LOG_COLORS/levels in menuconfig as needed.

Tests

A host-driven test suite lives under test/ and is wired into CTest. Run it with:

cmake -S . -B build
cmake --build build
ctest --test-dir build

The suite exercises buffering, log level filtering, and sync behavior. Hardware smoke tests reside in examples/.

License

MIT — see LICENSE.md.

ESPToolKit

• Check out other libraries: https://github.com/orgs/ESPToolKit/repositories
• Hang out on Discord: https://discord.gg/WG8sSqAy
• Support the project: https://ko-fi.com/esptoolkit