Basic Usage

• Periodic timers
• One-Shot timers
• Starting and stopping timers
• Changing the period
• Finding out the maximum timer period

Periodic Timers

The following sketch shows the basic use of the TeensyTimerTool. It picks the next free timer from a pool of available timers and sets it up to call the callback function every 250ms.

#include "TeensyTimerTool.h"
using namespace TeensyTimerTool;

PeriodicTimer t1;

void setup()
{
    pinMode(LED_BUILTIN,OUTPUT);
    t1.begin(callback, 250'000); // 250ms
}

void loop(){/*nothing*/}


void callback() // toggle the LED
{
    digitalWriteFast(LED_BUILTIN, !digitalReadFast(LED_BUILTIN));
}

Instead of passing the timer period as microseconds you can also use the time literals from std::chrono:

t1.begin(callback, 250ms);
t1.begin(callback, 4us + 2ms);
t1.begin(callback, 1h);
t1.begin(callback, 60min);
// etc...

One-Shot Timers

You can also use one-shot timers. Instead of invoking the callback periodically it is called only once after starting the timer with the trigger function.

The example below defines a one-shot timer whose callback simply switches off the board LED. In loop() the LED is switched on every 500ms. Immediately afterwards the timer is triggered with a delay time of 10ms so that the LED flashes briefly every 500ms.

#include "TeensyTimerTool.h"
using namespace TeensyTimerTool;

OneShotTimer t1;

void setup()
{
    pinMode(LED_BUILTIN,OUTPUT);
    t1.begin(callback);
}

void loop()
{
    digitalWriteFast(LED_BUILTIN, HIGH);
    t1.trigger(10'000); // trigger the timer with 10ms delay

    delay(500);
}

void callback() // switch off LED
{
    digitalWriteFast(LED_BUILTIN, LOW);
}

Trigger also accepts the std::chrono time literals. E.g.:

t1.trigger(5ms); // 5ms delay
t1.trigger(8us); // 8µs delay

Starting and stopping timers

All timers can be stopped and restarted with their start()and stop()functions. Here an example how to use this functionality:

#include "TeensyTimerTool.h"
using namespace TeensyTimerTool;

PeriodicTimer t1;

void setup()
{
    pinMode(13, OUTPUT);

    t1.begin([] { digitalToggleFast(13); }, 20Hz); //Blink, using a lambda function (see chapter Callbacks for more info)

    delay(2000);  // stop timer after 2s
    t1.stop();

    delay(2000);  // restart after 2s
    t1.start();
}

void loop()
{
}

Begin Timer in Stopped mode

If you want to initialize a timer without actually starting it you can use the optional bool start parameter of its begin function.

#include "TeensyTimerTool.h"
using namespace TeensyTimerTool;

PeriodicTimer t1;

void setup()
{
    pinMode(13, OUTPUT);

    t1.begin([] { digitalToggleFast(13); }, 50'000, false); // prepare timer but don't start (last parameter = false)

    delay(2000);  // start timer after 2s
    t1.start();
}

void loop()
{
}

Changing the period

setPeriod(35ms);
setNextPeriod(1234); //µs

Explanation to be done....

Finding out the maximum timer period

The maximum possible timer period depends on the frequency the timer is clocked with, possibly applied prescalers and the width of the counter register. All timers provided by the TeensyTimerTool provide a float getMaxPeriod()function which returns this value in seconds.

Here a small T4.x sketch which prints out this information for the timers currently available with the TeensyTimerTool. The sketch was run in standard configuration, i.e., F_CPU=600MHz, GPT & PIT @24MHz, QUAD @150MHz with prescaler: PSC_AUTO. Information about the used timers can be found in the chapter Supported Timers.

#include "TeensyTimerTool.h"
using namespace TeensyTimerTool;

PeriodicTimer t1(TCK);
PeriodicTimer t2(TCK64);
PeriodicTimer t3(GPT1);
PeriodicTimer t4(TMR3);
PeriodicTimer t5(PIT);
PeriodicTimer t6(TCK_RTC);

void empty() {}

void setup()
{
    while (!Serial) {}

    t1.begin(empty, 1'000);
    t2.begin(empty, 1'000);
    t3.begin(empty, 1'000);
    t4.begin(empty, 1'000);
    t5.begin(empty, 1'000);
    t6.begin(empty, 1'000);

    Serial.printf("TCK:           %8.2f seconds\n",     t1.getMaxPeriod());
    Serial.printf("TCK64:         %8.2f years\n",       t2.getMaxPeriod() / 60 / 60 / 24 / 365);
    Serial.printf("TCK_RTC:       %8.2f years\n",       t6.getMaxPeriod() / 60 / 60 / 24 / 365);
    Serial.printf("GPT(@24MHz)    %8.2f seconds\n",     t3.getMaxPeriod());
    Serial.printf("TMR(PSC_AUTO)  %8.2f milliseconds\n",t4.getMaxPeriod()*1000);
    Serial.printf("PIT(@24MHz)    %8.2f seconds\n",     t5.getMaxPeriod());
}

void loop(){
}

And here the output

TCK:               5.00 seconds
TCK64:           634.20 years
TCK_RTC:         634.20 years
GPT(@24MHz)      178.96 seconds
TMR(PSC_AUTO)     55.92 milliseconds
PIT(@24MHz)      178.96 seconds