A cross-platform real-time logging library for embedded systems that provides structured, colorized, and timestamped logging with automatic platform detection. ChronoLog seamlessly adapts to different embedded environments including Arduino, ESP-IDF, nRF Connect SDK (Zephyr), and STM32 HAL with or without RTOS support.

• ✨ Features
• 🎯 Supported Platforms
• 📦 Installation
  • PlatformIO (Arduino & ESP-IDF)
  • ESP-IDF Component
  • nRF Connect SDK (Zephyr)
  • STM32Cube Project
• 🚀 Quick Start
  • Basic Usage
  • Multiple Module Loggers
  • Runtime Log Level Control
• 📋 Log Output Examples
• ⚙️ Configuration
• 🛠️ Platform-Specific Requirements
• 🔧 Troubleshooting
• 📁 Repository Structure
• 🛣️ Roadmap & Upcoming Features
• 💖 Support & Motivation
• 🤝 Contributing
• 📄 License
• 👨‍💻 Author
• ⭐ Show Your Support

• 🎯 Automatic Platform Detection: Detects and adapts to Arduino, ESP-IDF, Zephyr (nRF Connect SDK), STM32 HAL, and desktop environments
• ⏰ Smart Timestamps:
  • Real-time timestamps when system time is synced (Arduino/ESP-IDF with NTP)
  • Uptime-based timestamps for other platforms
  • System time for desktop platforms (Linux, Windows, macOS)
• 🎨 Colorized Output: Color-coded log levels for better readability
• 📋 Structured Logging: Clean tabular format with timestamps, module names, log levels, and thread/task information
• 🧵 Thread-Safe Operation: Safe concurrent logging from multiple threads
• 📊 Multiple Log Levels: DEBUG, INFO, WARN, ERROR, FATAL with runtime level control
• 🎛️ Module-based Logging: Create separate loggers for different modules with individual log levels
• 📈 Progress Bar Support: Built-in progress tracking with visual progress bars (requires CHRONOLOG_PRO_FEATURES)
• � Remote Logging: Stream logs over TCP to remote clients for centralized monitoring (requires CHRONOLOG_REMOTE_ENABLE)
• �🖥️ Desktop Support: Full compatibility with Linux, Windows, and macOS
• 💾 Memory Efficient: Header-only library with minimal memory footprint
• 🚀 Zero Configuration: Works out-of-the-box on supported platforms
• ⚙️ Conditional Compilation: Enable only the features you need to optimize for your platform
• 📦 Official Package Managers: Available on Arduino IDE Library Manager, PlatformIO, and ESP-IDF Component Manager

ChronoLog is officially available on multiple package managers! Choose your preferred installation method:

Option 1: Arduino IDE Library Manager ⭐ (Easiest for Arduino)

• Open Arduino IDE → Sketch → Include Library → Manage Libraries
• Search for "ChronoLog"
• Click Install

Option 2: PlatformIO Library Manager ⭐ (Recommended for ESP32/ESP-IDF)

• Open PlatformIO → Libraries → Search for "ChronoLog" → Install
• Or manually add to lib_deps in platformio.ini

Option 3: ESP-IDF Component Manager ⭐ (For ESP-IDF Projects)

• ESP-IDF 5.0+ automatically finds ChronoLog in the component registry
• Or manually add to your project's dependency manifest

Search for "ChronoLog" in the PlatformIO Library Manager and add it to your project.

Simply add ChronoLog to the lib_deps section in your platformio.ini file:

[env:your_board]
platform = your_platform
board = your_board
framework = arduino  ; or espidf

lib_deps = 
    ChronoLog

Example for ESP32-C6:

[env:esp32-c6-devkitm-1]
platform = https://github.com/tasmota/platform-espressif32.git
board = esp32-c6-devkitm-1
framework = arduino

lib_deps = 
    ChronoLog

1. Create a components folder in your project root (if it doesn't exist)
2. Navigate to the components folder and clone the repository:

   cd components
   git clone https://github.com/Hamas888/ChronoLog.git

3. Add the requirement to your main CMakeLists.txt:

   idf_component_register(
       SRCS "main.cpp"
       INCLUDE_DIRS "."
       REQUIRES ChronoLog  # Add this line
   )

1. Create a modules folder in your project root
2. Navigate to the modules folder and clone the repository:

   cd modules
   git clone https://github.com/Hamas888/ChronoLog.git

3. Add the subdirectory to your root CMakeLists.txt:

   add_subdirectory(modules/ChronoLog)
   target_link_libraries(app PRIVATE ChronoLog)

1. Clone the repository in your project root:

   git clone https://github.com/Hamas888/ChronoLog.git

2. Add to your root CMakeLists.txt after add_executable():

   add_executable(${PROJECT_NAME} ${SOURCES} ${LINKER_SCRIPT})
   
   # Add ChronoLog
   add_subdirectory(ChronoLog)
   target_link_libraries(${PROJECT_NAME} ChronoLog)

For native desktop applications, simply include the library in your CMake project:

1. Clone or download ChronoLog to your project:

   git clone https://github.com/Hamas888/ChronoLog.git

2. Add to your CMakeLists.txt:

   add_subdirectory(ChronoLog)
   target_link_libraries(your_target_name ChronoLog)

Note: Desktop builds automatically detect the platform and provide full thread safety and system time support.

#include "ChronoLog.h"

// Create a logger for your module
ChronoLogger logger("MyModule", CHRONOLOG_LEVEL_DEBUG);

void setup() {  // or main() for non-Arduino platforms
    // For STM32, set UART handler (REQUIRED for STM32 platforms)
    #if defined(CHRONOLOG_PLATFORM_STM32_HAL)
        logger.setUartHandler(&huart2);  // Your UART handle (e.g., huart1, huart2)
    #endif
    
    logger.info("System initialized");
    logger.debug("Debug information");
    logger.warn("This is a warning");
    logger.error("An error occurred");
    logger.fatal("Critical system error");
}

#include "ChronoLog.h"

ChronoLogger sensorLogger("Sensors", CHRONOLOG_LEVEL_INFO);
ChronoLogger networkLogger("Network", CHRONOLOG_LEVEL_DEBUG);  
ChronoLogger systemLogger("System", CHRONOLOG_LEVEL_WARN);

void initLoggers() {
    // Required for STM32 platforms
    #if defined(CHRONOLOG_PLATFORM_STM32_HAL)
        sensorLogger.setUartHandler(&huart2);
        networkLogger.setUartHandler(&huart2);
        systemLogger.setUartHandler(&huart2);
    #endif
}

void sensorTask() {
    sensorLogger.info("Reading temperature: %.2f°C", 25.6f);
    sensorLogger.debug("Sensor calibration complete");
}

void networkTask() {
    networkLogger.info("WiFi connected to %s", "MyNetwork");
    networkLogger.error("Failed to connect to server");
}

ChronoLogger logger("MyModule", CHRONOLOG_LEVEL_INFO);

void updateLogLevel(int level) {
    logger.setLevel(static_cast<ChronoLogLevel>(level));
    logger.info("Log level updated to %d", level);
}

#include "ChronoLog.h"

#if defined(CHRONOLOG_PLATFORM_DESKTOP)
    #include <thread>
    #include <chrono>
#endif

ChronoLogger appLogger("DesktopApp", CHRONOLOG_LEVEL_DEBUG);

void workerThread(int threadId) {
    for (int i = 0; i < 5; i++) {
        appLogger.info("Worker %d processing item %d", threadId, i);
        
        #if defined(CHRONOLOG_PLATFORM_DESKTOP)
            std::this_thread::sleep_for(std::chrono::milliseconds(100));
        #endif
    }
}

int main() {
    appLogger.info("Desktop application started");
    
    #if defined(CHRONOLOG_PLATFORM_DESKTOP)
        // Create multiple threads for testing thread safety
        std::thread t1(workerThread, 1);
        std::thread t2(workerThread, 2);
        
        t1.join();
        t2.join();
    #else
        // For embedded platforms, run sequentially
        workerThread(1);
        workerThread(2);
    #endif
    
    appLogger.info("All workers completed");
    return 0;
}

#include "ChronoLog.h"

// Enable pro features in your build configuration
// #define CHRONOLOG_PRO_FEATURES 1

ChronoLogger logger("Progress", CHRONOLOG_LEVEL_PRO_FEATURES);

void processWithProgress() {
    uint32_t total = 100;
    
    for (uint32_t i = 0; i <= total; i++) {
        // Update progress bar (parameter order: current, total, title)
        logger.progress(i, total, "Processing data");
        
        // Simulate work
        #if defined(CHRONOLOG_PLATFORM_DESKTOP)
            std::this_thread::sleep_for(std::chrono::milliseconds(50));
        #elif defined(CHRONOLOG_PLATFORM_ARDUINO)
            delay(50);
        #elif defined(CHRONOLOG_PLATFORM_ESP_IDF)
            vTaskDelay(pdMS_TO_TICKS(50));
        #endif
    }
    
    logger.info("Processing completed!");
}

#include "ChronoLog.h"

// Enable remote logging in your build configuration
// #define CHRONOLOG_REMOTE_ENABLE 1

ChronoLogger logger("RemoteApp", CHRONOLOG_LEVEL_INFO);

void setupRemoteLogging() {
    #if CHRONOLOG_REMOTE_ENABLE
        // Start the remote logging server on port 9999
        ChronoLogRemote* remoteLogger = ChronoLogRemote::getInstance();
        bool started = remoteLogger->start(9999);
        
        if (started) {
            logger.info("Remote logging started on port 9999");
        } else {
            logger.error("Failed to start remote logging server");
        }
    #else
        logger.warn("Remote logging is disabled. Enable with CHRONOLOG_REMOTE_ENABLE=1");
    #endif
}

void applicationLoop() {
    logger.info("Application started - logs are streamed to connected clients");
    logger.debug("This message is sent to all connected remote clients");
    logger.error("Error logs are also transmitted to remote monitors");
}

14:32:15 | Sensors         | INFO     | WiFiTask         | Temperature reading: 25.6°C
14:32:15 | Network         | DEBUG    | NetworkTask      | Attempting connection to server
14:32:16 | Network         | WARN     | NetworkTask      | Connection timeout, retrying...
14:32:17 | System          | ERROR    | MainTask         | Memory allocation failed
14:32:17 | System          | FATAL    | ErrorHandler     | System halt required

00:05:23 | Sensors         | INFO     | SensorTask       | Accelerometer initialized
00:05:23 | Sensors         | DEBUG    | SensorTask       | Calibration data: X=1.02, Y=0.98, Z=9.81
00:05:24 | BLE             | INFO     | BLETask          | Advertisement started
00:05:25 | System          | WARN     | MainTask         | Low battery warning: 15%

14:32:15 | DesktopApp      | INFO     | Thread-123       | Worker 1 processing item 0
14:32:15 | DesktopApp      | INFO     | Thread-456       | Worker 2 processing item 0
14:32:15 | FileHandler     | DEBUG    | Thread-789       | Opening configuration file
14:32:16 | Database        | ERROR    | Thread-234       | Connection timeout after 5s
14:32:16 | Progress        | PROGRESS | Thread-567       | Processing data: 100% (100/100) [====================]

Note: Progress bars require CHRONOLOG_PRO_FEATURES to be enabled and logger level set to CHRONOLOG_LEVEL_PRO_FEATURES or higher.

Progress bars use conditional coloring based on completion status:

• 🟠 Orange: In-progress (0-99% complete)
• 🔵 Cyan: Completed (100% complete)

The library automatically applies color coding to different log levels:

• 🔵 DEBUG: Blue (Italic)
• 🟢 INFO: Green (Italic)
• 🟡 WARN: Yellow (Italic)
• 🔴 ERROR: Red (Italic)
• 🟣 FATAL: Magenta (Italic)
• 🟠 PROGRESS (In-progress): Orange (Italic)
• 🔵 PROGRESS (Complete): Cyan (Italic)

ChronoLog allows you to enable or disable features at compile time to optimize for your specific use case:

// === Core Logging Configuration ===
#define CHRONOLOG_MODE 1                    // Set to 0 to disable all logging
#define CHRONOLOG_BUFFER_LEN 100            // Buffer size for log messages (default: 100)
#define CHRONOLOG_DEFAULT_LEVEL CHRONOLOG_LEVEL_DEBUG  // Default log level

// === Feature Control ===
#define CHRONOLOG_COLOR_ENABLE 1            // Enable colored output (1 = enabled, 0 = disabled)
#define CHRONOLOG_THREAD_SAFE 1             // Enable thread-safe operations (1 = enabled, 0 = disabled)
#define CHRONOLOG_PRO_FEATURES 1            // Enable Pro features like progress bars (1 = enabled, 0 = disabled)
#define CHRONOLOG_REMOTE_ENABLE 0           // Enable remote logging via TCP (1 = enabled, 0 = disabled)

// Note: The following features are automatically detected based on platform:
// - Timestamps are always enabled and use platform-appropriate time sources
// - Thread/task information is automatically detected on RTOS platforms
// - Desktop support is automatic when compiling for Linux/Windows/macOS
// - RTOS support is automatic when FreeRTOS/Zephyr/CMSIS-OS is detected

// Minimal configuration for resource-limited embedded systems
#define CHRONOLOG_MODE 1
#define CHRONOLOG_BUFFER_LEN 64             // Smaller buffer to save memory
#define CHRONOLOG_COLOR_ENABLE 0            // Disable colors to save memory
#define CHRONOLOG_THREAD_SAFE 0             // Disable if not using RTOS
#define CHRONOLOG_PRO_FEATURES 0            // Disable progress bars
#define CHRONOLOG_REMOTE_ENABLE 0           // Disable remote logging
#define CHRONOLOG_DEFAULT_LEVEL CHRONOLOG_LEVEL_ERROR  // Only show errors

// Full-featured configuration for desktop applications
#define CHRONOLOG_MODE 1
#define CHRONOLOG_BUFFER_LEN 512            // Larger buffer for detailed messages
#define CHRONOLOG_COLOR_ENABLE 1            // Enable colors for better readability
#define CHRONOLOG_THREAD_SAFE 1             // Essential for multi-threaded desktop apps
#define CHRONOLOG_PRO_FEATURES 1            // Enable progress bars and advanced features
#define CHRONOLOG_DEFAULT_LEVEL CHRONOLOG_LEVEL_DEBUG  // Show all messages during development

// Production configuration with essential features only
#define CHRONOLOG_MODE 1
#define CHRONOLOG_BUFFER_LEN 200            // Moderate buffer size
#define CHRONOLOG_COLOR_ENABLE 0            // Disable colors for production
#define CHRONOLOG_THREAD_SAFE 1             // Keep thread safety for RTOS
#define CHRONOLOG_PRO_FEATURES 0            // Disable progress bars in production
#define CHRONOLOG_DEFAULT_LEVEL CHRONOLOG_LEVEL_INFO   // Info level for production

enum ChronoLogLevel {
    CHRONOLOG_LEVEL_NONE,   // No logging
    CHRONOLOG_LEVEL_FATAL,  // Only fatal errors
    CHRONOLOG_LEVEL_ERROR,  // Errors and above
    CHRONOLOG_LEVEL_WARN,   // Warnings and above  
    CHRONOLOG_LEVEL_INFO,   // Info and above (recommended)
    CHRONOLOG_LEVEL_DEBUG,  // All messages (development)
    CHRONOLOG_LEVEL_PRO_FEATURES  // Includes progress bars (only when CHRONOLOG_PRO_FEATURES is enabled)
};

Note: CHRONOLOG_LEVEL_PRO_FEATURES is only available when CHRONOLOG_PRO_FEATURES is defined as 1. This conditional level enables advanced features like progress bars while maintaining backward compatibility.

ChronoLogger logger("MyModule", CHRONOLOG_LEVEL_INFO);

// Change log level at runtime
logger.setLevel(CHRONOLOG_LEVEL_DEBUG);

// For STM32 platforms, set UART handler
#if defined(CHRONOLOG_PLATFORM_STM32_HAL)
    logger.setUartHandler(&huart2);
#endif

// Note: Color and timestamp settings are compile-time only
// Use the #define directives shown above to control these features

• No additional setup required
• Serial output at configured baud rate
• For real timestamps, sync system time with NTP

• No additional setup required
• Output to stdout/console
• For real timestamps, configure SNTP

• Required: Set UART handler using logger.setUartHandler(&huartX)
• Works with or without FreeRTOS/CMSIS-OS
• Output via specified UART peripheral

STM32 Complete Setup Example:

#include "ChronoLog.h"

ChronoLogger logger("STM32App", CHRONOLOG_LEVEL_DEBUG);

int main(void) {
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_USART2_UART_Init();  // Initialize your UART
    
    // REQUIRED: Set UART handler for ChronoLog
    logger.setUartHandler(&huart2);
    
    logger.info("STM32 application started");
    
    while (1) {
        logger.debug("Main loop iteration");
        HAL_Delay(1000);
    }
}

• No additional setup required
• Uses Zephyr's printk for output
• Automatic thread name detection

• Thread Safety: Automatic mutex-based synchronization for multi-threaded applications
• Progress Bars: Full support for visual progress tracking
• System Time: Uses system clock for real-time timestamps
• File Logging: Optional file output support (coming in future releases)
• Colors: Full ANSI color support in compatible terminals

STM32: No log output visible

• Ensure logger.setUartHandler(&huartX) is called before logging
• Verify UART is properly initialized and connected
• Check baud rate settings match your serial monitor

Progress bars not working

• Verify #define CHRONOLOG_PRO_FEATURES 1 is set
• Ensure logger level is CHRONOLOG_LEVEL_PRO_FEATURES or higher
• Progress bars are only available when Pro features are enabled

Compilation errors on platform detection

• Platform detection is automatic; avoid manually defining platform macros
• For custom platforms, check the header file for supported detection patterns

Thread safety issues

• Thread safety is enabled by default (CHRONOLOG_THREAD_SAFE 1)
• On custom RTOS implementations, mutex initialization may need adjustment

ChronoLog/
├── include/
│   └── ChronoLog.h                 # Main header file
├── examples/
│   ├── PlatformIO/
│   │   ├── Arduino/                # Arduino framework examples
│   │   └── ESP-IDF/                # ESP-IDF framework examples  
│   ├── ESP-IDF/                    # Native ESP-IDF examples
│   ├── STM32Cube/                  # STM32CubeIDE examples
│   ├── NRF Connect SDK/            # nRF Connect SDK examples
│   ├── Pro Features/               # Advanced features examples
│   │   ├── ESP32-S3 Progress Bar/  # Progress bar implementation
│   │   └── Remote Logging/         # Remote logging implementation (TCP streaming)
│   ├── ThreadSafe/                 # Thread safety examples
│   │   └── ESP32-S3 Thread Safety/ # Multi-threading examples
│   └── Desktop/                    # Desktop application examples
├── CMakeLists.txt                  # Multi-platform CMake configuration
├── library.json                    # PlatformIO library manifest
├── library.properties              # Arduino library properties
├── idf_component.yml               # ESP-IDF component configuration
└── README.md

ChronoLog is actively developed with exciting features planned for future releases:

• 📡 Remote Logging: TCP-based log streaming to remote clients (v1.1.0+)
• 📈 Progress Bar Support: Visual progress tracking with color indicators (v1.0+)
• 🧵 Thread-Safe Operation: Safe concurrent logging from multiple threads (v1.0+)

• 💾 Flash File Logging: Log directly to flash memory with retrieval capabilities
• ⚡ Memory & Speed Optimization: Enhanced performance for resource-constrained systems
• 🔧 Robust 8-bit AVR Support: Full compatibility with Arduino Uno, Nano, and other 8-bit platforms

• 📝 Log Filtering: Built-in filtering and pattern matching for logs
• 📊 Log Analytics: Built-in log filtering and analysis tools
• 🔒 Encrypted Logging: Secure log transmission and storage
• 📱 Mobile App Integration: Real-time log monitoring via smartphone apps

• 🚀 Zero-copy Logging: Minimize memory allocations for high-frequency logging
• ⚙️ Compile-time Optimization: Further reduction in code size and RAM usage
• 🔄 Circular Buffer Support: Efficient log rotation for continuous operation

Want to influence the roadmap? Share your ideas through GitHub Issues or reach out via Patreon for direct feature discussions!

ChronoLog is developed in my spare time with passion for the embedded community. Your support helps motivate continued development of this and other upcoming sensor libraries and embedded tools.

• ⭐ Star this repository - It means a lot and helps others discover ChronoLog
• 🔄 Patreon - Monthly support for ongoing development

• 🐛 Issues: Create a GitHub Issue for bugs or feature requests
• 💭 Direct Help: Reach out on Patreon for direct support and discussions
• 📧 Email: Contact me at hamasaeed@gmail.com for collaboration or questions

Your support enables me to:

• 🔧 Maintain and improve ChronoLog
• 📡 Develop upcoming sensor libraries
• 🚀 Create more embedded development tools
• 📚 Provide community support and documentation

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

This project is licensed under the MIT License - see the LICENSE file for details.

This permissive license allows for both commercial and non-commercial use, making ChronoLog suitable for any embedded project.

Hamas Saeed

• GitHub: @Hamas888
• Email: hamasaeed@gmail.com

If this project helped you, please give it a ⭐️ on GitHub!