HITI Timer

Modified on Wed, 4 Jan, 2023 at 7:33 PM

A HITI Timer is a variable which allows you to control the duration of a task using non-blocking functions and to trigger events accordingly.

How does it work ?

A Timer variable works the same way as a real timer. It is started, run, and updated by calling its functions run() or delay(). Once time is over, the Timer stops and must be reset to be reused. By default, the Timer automatically resets (auto-reset mode). However, you can disable auto-reset by setting the Timer to manual-reset mode. You then have to explicitly call reset() to reset it.

A Timer is typically used in auto-reset to control the duration of a repeated task and in manual-mode to control the duration of a punctual task.

Reset mode

To set the reset mode:

manualReset()
autoReset()

Timer monitoring

A Timer can have 3 different states:

Ready => ready to start
Running => counting
Over => time is over. Must be reset to be reused

Time indicators

To monitor the above states, use the following functions which return true if the Timer is in the corresponding state:

isReady()
isRunning()
isOver()

You can use these functions as time indicators to control the timing of your tasks. Simply test these functions in IF statement to trigger events or tasks at different times. In addition to the above functions which are ideal to trigger continuous tasks, the following functions are ideal for triggering punctual tasks as they punctually return true when the Timer starts or ends:

isStarting()
isEnding() => (reading this time indicator also resets it)

Timer Control

Both functions run() and delay() perform the same thing : they start, run, and update the Timer. They can also be used to set the Timer duration (unsigned long) in milliseconds. Moreover, they return a time indication, and this is where they differ in use :

run() => returns the same as isRunning()
run(duration) => returns the same as isRunning()
delay(duration) => returns the same as isEnding()

Timer creation

The following code creates a Timer variable called timer.

HC_Timer timer => set default duration 1000ms
HC_Timer timer(duration) => set duration (unsigned long) in milliseconds

Parameters setting

setDuration(duration) => set duration (unsigned long) in milliseconds. Works only if Timer is Ready.

Data reading

getStartTime() => return start time (unsigned long). Reference value = program start time.
getElapsedTime() => return elapsed time (unsigned long)

Frequency generation

frequencyGeneratorMode() => set to frequency generator mode
normalMode() => revert to normal mode

When the timer is set to frequency generator mode:

the timer is usually run every cycle
it is internally set to auto-reset, so that it automatically restarts when it ends
in order to get precise restart times, restart times are calculated based on the initial start time and the duration.

Example 1 : auto reset

This example shows how to trigger a punctual task every 0.5s. The Timer is automatically restarted every 0.5s and the task is triggered when the timer ends.

#include <HITIComm.h>

// create Timer
HC_Timer timer;

void setup()
{
    // initialize library
    HC_begin();
}

Option 1 for the loop() : Refer to this example : Auto reset

void loop()
{
    // communicate with HITIPanel
    HC_communicate();

    // run Timer 
    if (timer.delay(500))
    {
        // when Timer ends (every 0.5s) 
        // => do something
    }
}

Option 2 for the loop(), with explicit use of time indicators :

void loop()
{
    // communicate with HITIPanel
    HC_communicate();

    // run Timer
    timer.run(500);

    if (timer.isEnding())
    {
        // when Timer ends (every 0.5s) 
        // => do something
    }
}

Example 2 : manual reset

In this example, the Timer is set to manual-reset mode. When the Timer ends, it is reset using a Virtual Switch.

#include <HITIComm.h>

// Digital Data assignment
const byte dd_ResetSwitch = 0;

// create Timer
HC_Timer timer;

void setup()
{
    // initialize library
    HC_begin();

    // set Timer to manual reset mode
    timer.manualReset();
}

Option 1 for the loop() : Refer to this example : Manual reset

void loop()
{
    // communicate with HITIPanel
    HC_communicate();


    // run Timer
    if (timer.delay(2000))
    {
        // when Timer ends
        // => do something
    }


    // reset Timer using the Virtual Switch 
    if (HC_digitalDataRead(dd_ResetSwitch) == HIGH)
    {
        // reset Timer
        timer.reset();

        // deactivate Virtual Switch
        HC_digitalDataWrite(dd_ResetSwitch, LOW);
    }
}

Option 2 for the loop(), with use of additional time indicators :

void loop()
{
    // communicate with HITIPanel
    HC_communicate();


    // run Timer
    timer.run(2000);

    // when Timer starts
    if (timer.isStarting())
    {
        // do something punctually
    }

    // when Timer is Running
    if (timer.isRunning())
    {
        // do something continuously
    }

    // when Timer ends
    if (timer.isEnding())
    {
        // do something punctually
    }


    // reset Timer using the Virtual Switch 
    if (HC_digitalDataRead(dd_ResetSwitch) == HIGH)
    {
        // reset Timer
        timer.reset();

        // deactivate Virtual Switch
        HC_digitalDataWrite(dd_ResetSwitch, LOW);
    }
}

Example 3 : frequency generator

This example is similar to example 1. The Timer is automatically restarted every 0.5s and the task is triggered when the timer ends. The problem with example 1 is that restart times lacks precision, and a drift may build up. In order to avoid that, the timer can be set to frequency generator mode so that restart times are calculated.

#include <HITIComm.h>


// create Timer
HC_Timer timer;


void setup()
{
    // initialize library
    HC_begin();

    // set timer to frequency generator mode
    timer.frequencyGeneratorMode();
}


void loop()
{
    // communicate with HITIPanel
    HC_communicate();

    // run Timer 
    if (timer.delay(500))
    {
        // when Timer ends (every 0.5s) 
        // => do something
    }
}