StensTimer Library for Arduino
Author: Arjen Stens
Contact: me@arjenstens.com
License: GNU GPLv3
Navigation
Information
Description
StensTimer is a library that allows you to create easy-to-use timers giving you the freedom to use timed events without using the (blocking) delay() function
The library does not use interrupts or any hardware timers, which is a good thing.
Benefits
The main idea behind writing this library was that a lot of the existing timer libraries require you to basically make a function for every timer you set.
Because this can get cluttered really fast I thought of a different approach using only one (callback) function and timers with "Action id's".
These id's allow you to bind an action to each timer as is demonstrated in Usage.
Another, more advanced benefit of this library is that it can be used in more complex programs.
I'm talking about the kind of programs where you are working with Objects that need to use a timer for each instance of that object.
An example of that would be having a cooker alarm Object of which you want to have multiple instances. You can read more about this implementation here.
Download and Installation
You can download and install the library in 3 ways which I described here.
Step-by-step Guide
On my blog I wrote a step-by-step guide to walk you through the process of setting up the library.
You can find the step-by-step guide here.
Usage
Important Note
Because the variable of StensTimer is a pointer rather than the object itself we have to use the functions using an "->" instead of a dot.
#include <StensTimer.h>
/* StensTimer variable to be used later in the code. */
StensTimer* stensTimer;
/* define some custom Action codes */
#define DO_THING_ONE 1
#define DO_THING_TWO 2
#define DO_THING_THREE 3
/* This function will be called whenever a timer is due,
the set timer is passed as a parameter so you can read any property you need. */
void timerCallback(Timer* timer){
if(timer->getAction() == DO_THING_ONE){
Serial.print("Let's do thing one!");
}
else if(timer->getAction() == DO_THING_TWO){
Serial.print("Alright, let's do thing two!");
}
else if(timer->getAction() == DO_THING_THREE){
Serial.print("We're doing the third thing...");
}
}
void setup() {
Serial.begin(9600);
/* Save instance of StensTimer to the tensTimer variable*/
stensTimer = StensTimer::getInstance();
/* We are telling StensTimer which callback function to use here. */
stensTimer->setStaticCallback(timerCallback);
/* Perform thing_one after 2 seconds. */
stensTimer->setTimer(DO_THING_ONE, 2000);
/* Perform thing_two two times with 4 seconds in between. */
stensTimer->setTimer(DO_THING_TWO, 4000, 2);
/* Perform thing_three every 6 seconds indefiniteley,
the timer creation functions return the timer's instance so you can save it */
Timer* timerThree = stensTimer->setInterval(DO_THING_THREE, 6000);
/* You can delete a timer whenever you want to, uncomment to test */
// stensTimer->deleteTimers(); // deletes all _timers
// stensTimer->deleteTimer(timerThree); // deletes timerThree
Serial.println("Setup completed...");
}
void loop() {
/* Let StensTimer do it's magic every time loop() is executed. */
stensTimer->run();
}
Functions
Constructor
StensTimer is a singleton. This means that the Construction of StensTimer is being handled by the library itself.
This way there is always just one instance of StensTimer that you can use from anywhere in your program.
The only thing you as a programmer have to do is retrieve that class. using:
StensTimer::getInstance();
This function returns the StensTimer object. You can either use it's functions directly or save it to a variable first:
StensTimer* stensTimer = StensTimer::getInstance();
void setStaticCallback(function myFunctuion)
This function is used to tell StensTimer what function it needs to call when a timer is due.
You pass it the name of the function in which you will handle the timers that are due.
Parameters:
- myFunction: The function that you made in which you will handle each timer that is due.
void timerCallback(Timer* timer){
Serial.print("The action of the timer that is due is: ");
Serial.println(timer->getAction());
}
stensTimer->setStaticCallback(timerCallback);
Timer* setInterval(int actionId, long interval)
Sets a timer that will repeat indefinitely unless you stop it manually.
Parameters:
- actionId: The id you can use in the callback function to identify what you want to do when the timer is due.
- interval: The amount of milliseconds in between this timer's callback
#define DO_THING_THREE 3
Timer* timerThree = stensTimer->setInterval(DO_THING_THREE, 6000);
Timer* setTimer(int actionId, long delay, long repetitions)
This will create a timer that runs a specified amount of times. After the last callback is completed it will automatically be deleted.
The repetitions variable is actually optional and it's default value is 1, meaning it will execute only once.
Parameters:
- actionId: The id you can use in the callback function to identify what you want to do when the timer is due.
- interval: The amount of milliseconds in between this timer's callback.
- repetitions: The amount of times the timer will go off.
/* This executes only once after 1000ms (1sec). */
Timer* oneSecondTimer = stensTimer->setInterval(DO_THING_TWO, 1000);
/* This executes 60 times with an interval of 1000ms (1sec). */
Timer* oneMinuteTimer = stensTimer->setInterval(DO_THING_ONE, 1000, 60);
void deleteTimer(Timer* timer);
Simply deletes a timer.
Parameters:
- timer: The timer you want to delete.
stensTimer->deleteTimer(timerThree);
void deleteTimers();
Simply deletes all existing timers.
stensTimer->deleteTimers();
void timer->setAction(int actionId);
This function sets the actionId of a particular timer.
Parameters:
- actionId: The id you can use in the callback function to identify what you want to do when the timer is due.
timerThree->setAction(1234);
int timer->getAction();
This function returns the actionId of a timer which is typically set on creation of the timer. However, it can be changed after creation.
timerThree->getAction(); // Will return 1234 if the above function was called first.
void timer->setDelay(long interval);
This function sets the interval of a particular timer.
Parameters:
- interval: The amount of milliseconds in between this timer's callback.
timerThree->setDelay(3000);
long timer->getDelay();
This function returns the interval of a timer which is typically set on creation of the timer. However, it can be changed after creation.
timerThree->getDelay(); // Will return 3000 if the above function was called first.
void timer->setRepetitions(int repetitions);
This function sets the amount of times the timer will go off before deleting itself.
Parameters:
- repetitions: The amount of times the timer will go off.
timerThree->setRepetitions(60);
int timer->getRepetitions();
This function returns the amount of times the timer will go off before deleting itself.
timerThree->getRepetitions(); // Will return 60 if the above function was called first.
Contributing
The project is open-source. So if you see an opportunity for improvement, feel free to propose changes or fork the project.
You can find the project in this GitLab repository.