Timer

Summary

This page is about the intended use, the features of this library and how to integrate it into your Arduino project.

Introduction

Intended use

• encapsulate recurring and non-recurring timed actions with a non-busy wait approach for time spans in a range of one to thousands of milliseconds, such as:
  • polling keypad entries
  • debouncing push-button and switch signals
  • blink some LEDs
  • schedule some sequences where time accuracy is not crucial

Features

• configurable to be either
  • recurring (timer automatically restarts after the interval) or
  • non-recurring (timer stops after timeout period is over)
• timer interval/timeout time configurable ([ms])
• automatically attaches to TimerContext's linked list of Timer objects. As long as the TimerContext::handleTick() will be called (use global functions yield() or scheduleTimers() to do so), this will periodically update the timers' state and thus perform the timers' expire evaluation
• based on millis() function (number of milliseconds since the Arduino board began running the current program), handles unsigned long int overflows correctly (occurring around every 50 hours)
• implements Arduino yield() function in order to keep the timers' scheduling ongoing even while applications and drivers use the Arduino delay() function

Architecture

Timer

This is the API class and encapsulates the main functionality.

• collaborations (holds references to):
  • the callout adapter (if any is attached)
  • the next timer object in the single linked list (if there is at least one more)
• responsibilities:
  • caches the current time on each tick or poll request
  • knows:
    • the timer interval
    • whether the timer has expired
    • the mode of operation (recurring or non-recurring)
    • the trigger time (the moment when the interval time expired)
  • allows to start and stop (cancel) the time interval

TimerAdapter

This is the callout adapter interface for the timer. Client programs shall create an implementation of this and attach this to the timer object.

TimerContext

• is a sigleton
• holds the first Timer object of the single linked list (if there is any)
• allows to attach and detach Timer objects to and from the linked list
• sends tick events to all Timer objects attached to the linked list

UptimeInfo

Encapsulates the Arduino specific millis() function. For other platforms other implementations could easily be provided.

Integration

(shown on the basis of a simple application toggling the Arduino board's built-in LED)

• Include

  #include "Timer.h"

• Timer interval constant definition

  const unsigned long BLINK_TIME_MILLIS = 200;

• specific TimerAdapter implementation, periodically toggling the built-in LED

  class BlinkTimerAdapter : public TimerAdapter
  {
    public:
    void timeExpired()
    {
      digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
    }
  };

• Setup: set LED pin to output; create recurring Timer, inject specific TimerAdapter

  //The setup function is called once at startup of the sketch
  void setup()
  {
    pinMode(LED_BUILTIN, OUTPUT);
    new Timer(new BlinkTimerAdapter(), Timer::IS_RECURRING, BLINK_TIME_MILLIS);
  }

• Loop: call scheduleTimers() function

  // The loop function is called in an endless loop
  void loop()
  {
    scheduleTimers();
  }