DS_CAP_TIMERS - denis-stepanov/esp-ds-system GitHub Wiki

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:

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:

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.

None.

None.

None.

None. See the corresponding timer implementations.

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.

None. See the corresponding timer implementations.

None.

Version 1.1 or later.

• DS_CAP_TIMERS_ABS
• DS_CAP_TIMERS_SOLAR
• DS_CAP_TIMERS_COUNT_ABS
• DS_CAP_TIMERS_COUNT_TICK