Timer

The Timer class provides non-blocking time tracking for the Echo microcontroller. Unlike the delay() function which halts all program execution, Timer allows your robot to perform multiple time-dependent tasks simultaneously without interruption.

Why Use Timer Instead of delay()?

The standard delay() function stops your entire program, which can cause problems in robotics applications:

• delay() blocks everything: Motors, sensors, and communication all freeze

• Timer runs in parallel: Check multiple timers while your robot continues operating

• Better control flow: Implement timeouts, intervals, and scheduled events without stopping other operations

Important: You can still use delay() in setup() for initialization, but avoid it in loop().

---

Key Features

• Non-blocking time measurement

• Start, stop, pause, and resume functionality

• Automatic pause at specified time

• Millisecond and second precision

• Multiple independent timers in one program

• Zero impact on other program operations

---

OverView

The Timer class provides a flexible timing utility for measuring elapsed time with support for pause, resume, and auto-pause functionality.

Method	Description
Timer()	Creates a new timer instance in stopped state
start()	Starts the timer from zero
stop()	Stops the timer and resets accumulated time
pause()	Pauses the timer, preserving current time
reset()	Resets timer to zero and stops it
setPause(ms)	Sets automatic pause when specified milliseconds are reached
resume()	Resumes the timer from paused state
isPaused()	Returns true if timer is currently paused
get()	Returns elapsed time in milliseconds
getSeconds()	Returns elapsed time in seconds as a float

---

Quick Start

#include <EchoLib.h>

Timer timer;

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

void loop() {
    Serial.println("Time: " + String(timer.getSeconds()) + "s");
    // Program continues without blocking
}

---

API Reference

Timer()

Timer()

Creates a new timer instance. Multiple timers can be created for tracking different events.

Example:

Timer motorTimer;
Timer sensorTimer;
Timer statusTimer;

---

start()

void start()

Starts or restarts the timer from zero. Resets any accumulated time and begins counting.

Example:

void setup() {
    Serial.begin(115200);
    timer.start();  // Begin counting
}

---

stop()

void stop()

Stops the timer and resets all accumulated time to zero. Use this to completely halt and clear the timer.

Example:

if (emergencyStop) {
    motorTimer.stop();  // Stop and reset
    digitalWrite(MOTOR_PIN, LOW);
}

---

pause()

void pause()

Pauses the timer while preserving the accumulated time. The timer can be resumed later from where it stopped.

Example:

if (sensorBlocked) {
    actionTimer.pause();  // Pause without losing time
    // Handle the blockage
}

---

resume()

void resume()

Resumes a paused timer, continuing from where it was paused.

Example:

if (sensorClear) {
    actionTimer.resume();  // Continue counting
}

---

reset()

void reset()

Resets the timer to zero without starting it. The timer remains stopped until start() or resume() is called.

Example:

timer.reset();  // Clear time but don't start
// Later...
timer.start();  // Begin from zero

---

setPause(unsigned long ms)

void setPause(unsigned long ms)

Configures the timer to automatically pause when it reaches the specified time in milliseconds.

Parameters:

• ms: Time in milliseconds at which to auto-pause

Example:

timer.start();
timer.setPause(5000);  // Auto-pause at 5 seconds

// In loop
if (timer.isPaused()) {
    Serial.println("Timer reached 5 seconds and paused");
}

---

isPaused()

bool isPaused() const

Returns whether the timer is currently paused.

Returns:

• true: Timer is paused

• false: Timer is running or stopped

Example:

if (timer.isPaused()) {
    Serial.println("Timer is paused");
    timer.resume();
}

---

get()

unsigned long get() const

Returns the elapsed time in milliseconds.

Returns:

• unsigned long: Elapsed time in milliseconds

Example:

unsigned long elapsed = timer.get();
Serial.println("Elapsed: " + String(elapsed) + "ms");

---

getSeconds()

float getSeconds() const

Returns the elapsed time in seconds as a floating-point number.

Returns:

• float: Elapsed time in seconds

Example:

float seconds = timer.getSeconds();
Serial.println("Time: " + String(seconds, 2) + "s");

---

Practical Examples

Example 1: Blinking LED Without delay()

#include <EchoLib.h>

Timer blinkTimer;
const int LED_PIN = 2;
bool ledState = false;

void setup() {
    pinMode(LED_PIN, OUTPUT);
    blinkTimer.start();
}

void loop() {
    // Blink every 500ms without blocking
    if (blinkTimer.get() >= 500) {
        ledState = !ledState;
        digitalWrite(LED_PIN, ledState);
        blinkTimer.reset();
        blinkTimer.start();
    }
    
    // Other code runs continuously
    // Read sensors, check buttons, etc.
}

Example 2: Multiple Timed Events

#include <EchoLib.h>

Timer sensorTimer;
Timer reportTimer;
Timer ledTimer;

const int LED_PIN = 2;

void setup() {
    Serial.begin(115200);
    pinMode(LED_PIN, OUTPUT);
    
    sensorTimer.start();
    reportTimer.start();
    ledTimer.start();
}

void loop() {
    // Read sensor every 100ms
    if (sensorTimer.get() >= 100) {
        int value = analogRead(A0);
        Serial.println("Sensor: " + String(value));
        sensorTimer.reset();
        sensorTimer.start();
    }
    
    // Send status report every 5 seconds
    if (reportTimer.get() >= 5000) {
        Serial.println("Status: OK");
        reportTimer.reset();
        reportTimer.start();
    }
    
    // Blink LED every 250ms
    if (ledTimer.get() >= 250) {
        digitalWrite(LED_PIN, !digitalRead(LED_PIN));
        ledTimer.reset();
        ledTimer.start();
    }
}

Example 3: Timeout Detection

#include <EchoLib.h>

Timer connectionTimer;
bool connected = false;

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

void loop() {
    // Check for timeout (10 seconds)
    if (!connected && connectionTimer.get() >= 10000) {
        Serial.println("Connection timeout!");
        // Attempt reconnection
        connectionTimer.reset();
        connectionTimer.start();
    }
    
    // Simulate connection check
    // In real code, this would be actual connection logic
}

---

Best Practices

Comparing Times

Use >= instead of == when comparing timer values to avoid missing the exact moment:

// Good
if (timer.get() >= 1000) {
    // Do something
}

// Avoid
if (timer.get() == 1000) {
    // Might miss this exact millisecond
}

Resetting Timers

After triggering an event based on time, remember to reset and restart:

if (timer.get() >= 5000) {
    performAction();
    timer.reset();
    timer.start();  // Start counting again
}

Multiple Independent Timers

Create separate timer instances for different tasks:

Timer timer1;  // For task A
Timer timer2;  // For task B
Timer timer3;  // For task C

// Each timer operates independently

---

Common Patterns

Interval Timing

Execute code at regular intervals:

if (timer.get() >= interval) {
    // Execute periodic task
    timer.reset();
    timer.start();
}

One-Shot Timer

Execute code once after a delay:

if (!timer.isPaused() && timer.get() >= delay) {
    // Execute once
    timer.pause();  // Prevent re-execution
}

Accumulative Timing

Track total active time with pause support:

// Timer automatically accumulates time
// Pause when needed
timer.pause();
// Resume later - accumulated time is preserved
timer.resume();

---

Technical Details

Time Resolution

• Precision: 1 millisecond (based on Arduino millis())

• Range: Up to 49.7 days (limited by unsigned long overflow)

• Accuracy: Dependent on system clock (typically very accurate)

Memory Usage

Each Timer instance uses minimal memory:

• Approximately 20 bytes per timer

• No heap allocation

• Suitable for creating many timers

Performance

Timer operations are extremely fast:

• get() and getSeconds(): ~1-2 microseconds

• start(), stop(), pause(), resume(): ~0.5 microseconds

• Negligible impact on loop performance

---

Troubleshooting

Timer Doesn't Start

Problem: Timer shows zero time.

Solution: Ensure start() is called before checking time:

timer.start();  // Must call this first

Time Seems Frozen

Problem: Timer value doesn't change.

Solution: Check if timer is paused:

if (timer.isPaused()) {
    timer.resume();
}

Events Fire Multiple Times

Problem: Timed event executes repeatedly.

Solution: Reset timer after triggering:

if (timer.get() >= 1000) {
    doSomething();
    timer.reset();
    timer.start();
}

Auto-Pause Not Working

Problem: setPause() doesn't stop timer.

Solution: Check the timer with isPaused() in your loop:

timer.setPause(5000);
// In loop:
if (timer.isPaused()) {
    // Timer reached threshold
}