DS_CAP_TIMERS

DS_CAP_TIMERS — Timer Support

Description

This capability adds support for timers, used to execute certain actions in future. The library focuses on periodic user-visible actions, such as turning a lamp on or off, or sending some temperature readout to cloud. Supported time periods vary from one second to one week, which is the most interesting time range for humans. The library is not well suited to support timers ticking much faster or much slower than these rates.

Note that simple timing is built into time capability itself. For example, newHour() function would allow calling some code once an hour. See time capability description for more details. The timers described here allow for more advanced timing mechanisms.

The way to define future event is determined by the timer type. Grossly, there are two ways of designating future time: absolute — when system has notion of system time and can be programmed for a future timestamp — and relative — when system does not have notion of time but can be programmed for some point in future using some time counting technique relative to the original time point. The library supports several classes of timers:

• Absolute timer — fires at a given time in future;
• Solar timer — fires on sun-related event (sunrise or sunset);
• Countdown timer — fires after some time period from now.

Timer actions are specified using a string called "action". When a timer event fires, the library calls a user-defined callback function, which can check the timer "action" property in order to decide which code to execute.

This capability defines an abstract timer interface (ds::Timer class); in order to actually use a timer, a programmer has to select one of the timer implementations listed below. ds::Timer class has the following fields implemented:

Field	Description	Default Value
int id	Timer identifier (optional)	-1
ds::timer_type_t type	Timer type	(none)
String action	Timer action	"undefined"
bool armed	True if timer is armed (will fire); false if ignored with no action	true
bool recurrent	True if timer should be auto-rearmed after firing; false otherwise	true
bool transient	True if timer should be disposed of after firing	false

Timer ID is not required for correct functioning of the library, but it could be useful to store some external identifier (e.g., order of display on a web page).

Timer type could be one of the following constants:

Timer Type	Description
TIMER_ABSOLUTE	Timer fires at a given absolute time
TIMER_SUNRISE	Timer fires at sunrise
TIMER_SUNSET	Timer fires at sunset
TIMER_COUNTDOWN_ABS	Timer fires at some moment from now, counted via absolute time increment
TIMER_COUNTDOWN_TICK	Timer fires at some moment from now, counted via Ticker function
TIMER_INVALID	Unsupported timer type or misconfigured timer

Timers are declared invalid if incorrect or contradictory information is passed to a timer constructor. Invalid timers are ignored during processing and may be suppressed if they are found inside a timer collection.

Marking timer as transient will render it unusable (destroy) after firing once. This normally only has meaning in the context of collection of timers, in which case the timer will be excluded from collection.

To operate these fields, the following methods are implemented:

int Timer::getID() const;                      // Return timer identifier
void Timer::setID(const int new_id);           // Set timer identifier
timer_type_t Timer::getType() const;           // Get timer type
const String& Timer::getAction() const;        // Return timer action
void Timer::setAction(const String& new_action); // Set timer action
bool Timer::isArmed() const;                   // Return true if timer is armed
void Timer::arm();                             // Arm the timer (default)
void Timer::disarm();                          // Disarm the timer
bool Timer::isRecurrent() const;               // Return true if timer is recurrent
void Timer::repeatForever();                   // Make timer repetitive (default)
void Timer::repeatOnce();                      // Make timer a one-time shot
bool Timer::isTransient() const;               // Return true if timer is transient (i.e., will be dead after firing)
void Timer::keep();                            // Keep the timer around (default)
void Timer::forget();                          // Mark the timer for disposal

There is no public method to set timer type. Normally, timer type should be known by the time of timer construction.

One can compare abstract timers. Two abstract timers are considered equal when their types, IDs and actions match.

Requires

None.

Cooperates With

None.

Conflicts With

None.

Usage

None. See the corresponding timer implementations.

Mandatory Calls

System::begin()	Not required
System::update()	Not required

Note that while this capability per se does not require these calls, the underlying implementations, like absolute timer, most likely would need them to work correctly. Check their respective pages for details.

Examples

None. See the corresponding timer implementations.

Bugs

None.

Availability

Version 1.1 or later.

See Also

• DS_CAP_TIMERS_ABS
• DS_CAP_TIMERS_SOLAR
• DS_CAP_TIMERS_COUNT_ABS
• DS_CAP_TIMERS_COUNT_TICK