DS_CAP_TIMERS_COUNT_ABS

DS_CAP_TIMERS_COUNT_ABS — Support for Countdown Timer Using Absolute Time

Description

This capability adds support for countdown timers, that is, timers firing periodically. This flavor of a countdown timer is implemented using an absolute timer, hence, it requires that a notion of time is enabled in controller.

The following methods, complementary to the generic timer methods, are available:

TimerCountdownAbs::TimerCountdownAbs(const String action = "undefined", const float interval = 1,
  const uint32_t offset = 0, const uint8_t dow = TIMER_DOW_ANY, const bool armed = true,
  const bool recurrent = true, const bool transient = false, const int id = -1);   // Constructor
float TimerCountdownAbs::getInterval() const;               // Return timer interval (s)
void TimerCountdownAbs::setInterval(const float interval);  // Set timer interval (s)
uint32_t TimerCountdownAbs::getOffset() const;              // Return timer offset in seconds from midnight
void TimerCountdownAbs::setOffset(const uint32_t offset);   // Set timer offset in seconds from midnight
void TimerCountdownAbs::update(const time_t from_time = 0); // Process timer. 0 == from current time

One can also compare countdown absolute timers among themselves and with a struct tm value containing absolute time.

Methods getInterval() and setInterval() allow setting timer period. Even though the methods accept fractions of seconds, the accuracy of the underlying absolute timer is one second; consequently, timer period could only be a multiple of a second. It cannot exceed 86400 seconds (one day). It can be indirectly extended up to seven days by manipulating the day of week dow field.

Because this timer is aware of absolute time, it is possible to set its firing offset, expressed in seconds from midnight. For example, a timer firing every minute could be set to fire with offset of 30 seconds (that is, at 00:00:30, 00:01:30, ...). Offset should be lesser than the timer period; otherwise it will not be taken into account.

For the timer to work correctly (i.e., count down), its update() method should be called at least once per second. If the timer is registered with the System::timers list and marked active, this will happen automatically. An optional parameter specifies the countdown time base in Unix seconds; by default, current time is assumed. The function is capable of recovering (resyncing) timer from time skews; however, periodicity is not guaranteed in this case (see Bugs).

The rest of the timer methods are the same as for an absolute timer.

Since a countdown absolute timer is an absolute timer, its registration and processing is made in the same way; consult the absolute timer page for more details.

Requires

• DS_CAP_TIMERS
• DS_CAP_TIMERS_ABS
• DS_CAP_SYS_TIME

Cooperates With

• DS_CAP_SYS_LOG — if syslog is enabled, timer firing event will be logged;
• DS_CAP_APP_LOG — if application log is enabled, timer firing event will be logged;
• DS_CAP_WEB_TIMERS — if timer configuration by user is enabled, countdown absolute timers will be offered as an option.

Conflicts With

None.

Usage

MySystem.h:

#define DS_CAP_SYS_TIME          // Enable system time
#define DS_CAP_TIMERS_COUNT_ABS  // Enable countdown timers via absolute time

#define DS_TIMEZONE TZ_Europe_Paris  // My timezone

#include "System.h"         // System global definitions

sketch.ino:

#include "MySystem.h"

using namespace ds;

// Timer handler
void myTimerHandler(const TimerAbsolute* timer) {
    if (timer->getAction() == "lamp on") {

    // Turn the lamp on here ...
    }
}
void (*System::timerHandler)(const TimerAbsolute*) = myTimerHandler;  // Install the handler

void setup() {

  // Set up countdown timer with 10 seconds period and 5 seconds offset
  System::timers.push_front(new TimerCountdownAbs("lamp on", 10, 5));  
}

void loop() {
  System::update();
}

Mandatory Calls

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

Examples

• timers_count_abs

Bugs

• Because this timer relies on absolute time, it may experience gaps or jumps if system clock is skewed. In particular, changes from / to summer / winter time could have some impact. If you need guaranteed period of execution, use countdown ticker timer.

Availability

Version 1.1 or later.

See Also

• DS_CAP_TIMERS
• DS_CAP_TIMERS_ABS
• DS_CAP_TIMERS_SOLAR
• DS_CAP_TIMERS_COUNT_TICK