AsyncTimer

JavaScript-like Async timing functions (setTimeout, setInterval) for Arduino, ESP8266, ESP32 and other compatible boards

Installing

Arduino IDE:

Library Manager:

The easiest way is to install it through Arduino Library manager selecting the menu:

Sketch -> Include Library -> Manage Libraries

Then type AsyncTimer into the search box and install the latest version.

Manual install:

Download the repository as .zip and include it as a new library into the IDE selecting the menu:

 Sketch -> Include Library -> Add .Zip library

PlatformIO:

Go to libraries and type AsyncTimer into the search bar and add it to your project.

Getting Started

Simply include the library into your sketch and make one instance of AsyncTimer and add the setup function to void setup() and the handler to void loop() and then start using it!

Example:

#include <AsyncTimer.h>

AsyncTimer t;

void loop()
{
  t.handle();
}

⚠NOTE⚠: only one instance must be created and it must be outside any function, as shown in the example above.

⚠NOTE⚠: The default timer capacity is 10, if you wish to increase it, you have to use non-default initializer:

AsyncTimer t(22);

API

setTimeout(callbackFunction, delayInMs)

Creates a new timeout.

setTimeout takes two arguments, the first one is the function to call after waiting, the second one is the time in milliseconds to wait before executing the function. It returns an unsigned short id of the timeout. If the timeout creation was unsuccessful, it returns 0. It will run only once unless canceled.

Example:

• Using lambda function:

AsyncTimer t;

t.setTimeout([]() {
  Serial.println("Hello world!");
}, 2000);
// "Hello world!" will be printed to the Serial once after 2 seconds

• Using normal function:

AsyncTimer t;

void functionToCall()
{
  Serial.println("Hello world!");
}

t.setTimeout(functionToCall, 2000);
// "Hello world!" will be printed to the Serial once after 2 seconds

setInterval(callbackFunction, delayInMs)

Creates a new interval.

setInterval takes the same parameters as setTimeout and returns an unsigned short id of the interval, unlike setTimeout, it will keep executing the code forever unless canceled. If the interval creation was unsuccessful, it returns 0.

Example:

• Using lambda function:

AsyncTimer t;

t.setInterval([]() {
  Serial.println("Hello world!");
}, 2000);
// "Hello world!" will be printed to the Serial every 2 seconds

• Using normal function:

AsyncTimer t;

void functionToCall()
{
  Serial.println("Hello world!");
}

t.setInterval(functionToCall, 2000);
// "Hello world!" will be printed to the Serial every 2 seconds

Accessing the interval ID inside its callback

setInterval accepts a callback with an unsigned short parameter. AsyncTimer supplies the same ID returned by the registration call, so the callback can cancel or modify its own timer without capturing an ID variable. Existing interval callbacks that take no arguments continue to work. setTimeout callbacks take no arguments; the ID parameter is only for intervals.

AsyncTimer t;

void setup() {
  Serial.begin(9600);
  unsigned int remaining = 5;
  t.setInterval([remaining](unsigned short id) mutable {
    Serial.println("Tick");
    if (--remaining == 0) {
      t.cancel(id);
      return;
    }
  }, 1000);
}

void loop() { t.handle(); }

This prints five messages and cancels only that interval. The captured counter belongs to the callback, so it remains valid after setup() returns. Functions and callable objects with an ID parameter are also supported. If a callable supports both zero arguments and an ID (for example, through a default argument), the zero-argument call is preserved; omit the default to receive the timer ID.

Do not capture a local ID by value in its own initializer, such as unsigned short id = t.setInterval([id]() { /* ... */ }, 1000): the ID has not been assigned yet. Capturing it by reference is valid only while that variable remains alive. The callback argument avoids both problems.

cancel(id) prevents future invocations; it does not interrupt the callback currently running. Use return to stop executing that callback. One-shot timeouts are already removed before their callback runs, so cancelling their own ID has no effect.

getRemaining(intervalOrTimeoutId)

Gets the number of milliseconds remaining in a timer. Returns 0 if the timer is not found.

getRemaining takes one argument, the id returned from setTimeout or setInterval function, returns unsigned long.

Example:

AsyncTimer t;

unsigned short timeoutId = t.setTimeout([]() {
  Serial.println("Hello world!");
}, 3000);

// Get the remaining ms on the timer
unsigned long remaining = t.getRemaining(timeoutId);

changeDelay(intervalOrTimeoutId, delayInMs)

Changes the delay value of an active intervalOrTimeout.

changeDelay takes two arguments, the id returned from setTimeout or setInterval function and the new delayValue in ms, returns void.

Example:

• Changing the delay of setInterval:

AsyncTimer t;

unsigned short intervalId = t.setInterval([]() {
  Serial.println("Hello world!");
}, 2000);

t.setTimeout([=]() {
  t.changeDelay(intervalId, 3500);
  // Now the interval runs every 3500ms instead of the old 2000ms
}, 7000);

delay(intervalOrTimeoutId, delayInMs)

Delays the execution of an active intervalOrTimeout.

delay takes two arguments, the id returned from setTimeout or setInterval function and the new delayValue in ms, returns void.

Example:

• Delaying the execution of setInterval:

AsyncTimer t;

unsigned short intervalId = t.setInterval([]() {
  Serial.println("Hello world!");
}, 2000);

t.setTimeout([=]() {
  t.delay(intervalId, 3500);
  // Now the interval will be delayed by an extra 3500ms,
  // afterwords, it will continue executing normally.
}, 7000);

reset(intervalOrTimeoutId)

Resets the wait time of an active intervalOrTimeout.

delay takes one argument, the id returned from setTimeout or setInterval function, returns void.

Example:

• Resetting the wait time of setInterval:

AsyncTimer t;

unsigned short intervalId = t.setInterval([]() {
  Serial.println("Hello world!");
}, 2000);

t.setTimeout([=]() {
  t.reset(intervalId);
  // Now the interval will be reset, this means that it will
  // execute exactly 2000ms after the reset function call.
}, 7000);

cancel(intervalOrTimeoutId)

Cancels the execution of a timeout or an interval.

cancel takes one argument, the id returned from setTimeout or setInterval function and returns void.

Example:

• Cancelling an interval:

AsyncTimer t;

unsigned short intervalId = t.setInterval([]() {
  Serial.println("Hello world!");
}, 2000);

// Cancel the interval after 7 seconds:
t.setTimeout([=]() {
  t.cancel(intervalId);
}, 7000);

• Cancelling a timeout:

AsyncTimer t;

// This timeout will never run
unsigned short timeoutId = t.setTimeout([]() {
  Serial.println("Hello world!");
}, 3000);

// Cancel the timeout before it's executed
t.cancel(timeoutId);

cancelAll(includeIntervals = true)

Cancels the execution of a all timeouts and intervals or just timeouts.

cancelAll takes one optional argument, if you intend to only cancel timeouts, then call the function with false, otherwise it clears both timeouts and intervals be default, returns void.

Example:

• Cancelling all timeouts and intervals:

AsyncTimer t;

t.setInterval([]() {
  Serial.println("foo");
}, 2000);

t.setTimeout([]() {
  Serial.println("bar");
}, 7000);

t.setTimeout([]() {
  Serial.println("baz");
}, 7000);

// After this call, nothing will be running inside AsyncTimer
t.cancelAll();

• Only cancelling timeouts:

AsyncTimer t;

t.setInterval([]() {
  Serial.println("foo");
}, 2000);

t.setTimeout([]() {
  Serial.println("bar");
}, 7000);

t.setTimeout([]() {
  Serial.println("baz");
}, 7000);

// After this call, only intervals will be running inside AsyncTimer
t.cancelAll(false);

Examples

• BlinkUsingInterval - Blink led using setInterval.
• SerialMsgUsingTimeout - Send a message to the serial monitor using setTimeout 10 seconds after booting.
• CancelInterval - Cancel an interval using cancel.
• CancelIntervalFromCallback - Cancel an interval using the ID passed to its callback.
• CancelTimeout - Cancel a timeout using cancel.
• DebounceUsingTimeout - Debounce button using a delay.

Testing on a PC

The host tests run with a C++11 compiler and CMake, without an Arduino or Arduino SDK.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel
ctest --test-dir build -C Release --output-on-failure

See tests/README.md for coverage, individual suites, sanitizers, and 32-bit builds.

License

This library is licensed under MIT.

Copyright

Copyright 2022 - Aasim-A