Chrona

Chrona is a lightweight PlatformIO library for high-precision elapsed time measurement on the ESP32 using the native esp_timer API.

The name Chrona is derived from chronos (time), reflecting its role as a small, deterministic timing helper. The library provides a minimal and explicit API for stopwatch-style timing in games, benchmarks, reaction tests, and system measurements.

Overview

Chrona is designed to simplify accurate time tracking on ESP32 projects by providing:

• A clean abstraction over ESP32’s native microsecond timer
• Explicit start / stop / reset control
• Deterministic elapsed time accumulation
• Simple formatted output for display use cases

The library intentionally remains minimal and does not attempt to be a full scheduler, profiler, or task timer framework.

Features

• Microsecond-resolution timing via esp_timer_get_time()
• Explicit start / stop / resume semantics
• Accumulated elapsed time tracking
• Fixed-format time string output (MM:SS:CS)
• No background tasks or interrupts
• Zero dynamic memory allocation
• Minimal API surface
• Designed for ESP32 + Arduino framework

Platform Support

• ESP32 only

This library relies on ESP32-specific esp_timer functions and is not portable to AVR or other MCUs without modification.

Dependencies

• Arduino framework for ESP32

No external libraries are required.

Installation

PlatformIO (GitHub source)

Add the following to your platformio.ini:

lib_deps =
  https://github.com/tabah-mly/chrona.git

Local Library

Alternatively, place the library in your project’s lib directory:

lib/
└── chrona/
    ├── include/
    │   └── Chrona.h
    └── src/
        └── Chrona.cpp

Basic Usage

Include and Initialize

#include <Chrona.h>

Chrona timer;

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

Chrona requires no explicit initialization. The timer starts in a stopped state with zero elapsed time.

API Reference

start

Starts the timer if it is not already running.

timer.start();

If the timer was previously stopped, calling start() resumes accumulation from the last elapsed value.

stop

Stops the timer and accumulates elapsed time since the last start().

timer.stop();

reset

Clears the elapsed time and stops the timer.

timer.reset();

isRunning

Returns whether the timer is currently running.

bool running = timer.isRunning();

getTimeUs

Returns the total elapsed time in microseconds.

int64_t t = timer.getTimeUs();

If the timer is running, the returned value includes the active interval.

format

Formats the elapsed time into a fixed-width string.

char buf[16];
timer.format(buf, sizeof(buf));

Output format

MM:SS:CS

Where:

• MM — minutes (00–99)
• SS — seconds (00–59)
• CS — centiseconds (1/100 second)

The caller is responsible for providing a sufficiently large buffer.

Design Considerations

• Uses esp_timer_get_time() as a monotonic time source
• No background execution or hidden state
• Elapsed time is accumulated explicitly
• Safe to query at any time
• Formatting is intentionally fixed for display-oriented use cases
• Designed for game logic, UI feedback, and measurement tasks

Project Status

Chrona is currently in beta. The core timing API is stable, with future changes focused on optional extensions rather than behavioral changes.

Roadmap

Planned enhancements include:

• Split / lap time support
• Helper accessors for milliseconds and seconds
• Optional compile-time removal of formatting code
• Custom formatting hooks
• Namespace alignment with related libraries

License

This project is licensed under the MIT License.

Author

Tabah Mulya

GitHub: https://github.com/tabah-mly