Task Scheduler – cooperative multitasking for Arduino microcontrollers

Version 1.6: 2015-09-22

REQUIREMENT:

A lightweight implementation of the task scheduling supporting:

1. execution period (n times per second)

2. number of iterations (n times)

3. execution of tasks in predefined sequence

4. dynamic change of the execution parameters for both tasks and execution schedule

5. power saving via entering IDLE sleep mode if no tasks are scheduled to run

IDEA:

“Task” is a container concept that links together:

1. Execution interval

2. Number of execution iterations

3. A piece of code performing the task activities (callback function)

Tasks are linked into execution chains, which are processed by the “Scheduler” in the order they are linked.

Tasks are responsible for supporting cooperative multitasking by being “good neighbors”, i.e., running their callback functions in a non-blocking way and releasing control as soon as possible.

“Scheduler” is executing Tasks' callback functions in the order the tasks were added to the chain, from first to last. Scheduler stops and exists after processing the chain once in order to allow other statements in the main code of loop() function to run. This a “scheduling pass”.

If compiled with _TASK_SLEEP_ON_IDLE_RUN enabled, the scheduler will place processor into IDLE sleep mode (for approximately 1 ms, as the timer interrupt will wake it up), after what is determined to be an “idle” pass. An Idle Pass is a pass through the chain when no Tasks were scheduled to run their callback functions. This is done to avoid repetitive empty passes through the chain when no tasks need to be executed. If any of the tasks in the chain always requires immediate execution (aInterval = 0), then there will be no end-of-pass delay.

Note: Task Scheduler uses millis() to determine if tasks are ready to be invoked. Therefore, if you put your device to any “deep” sleep mode disabling timer interrupts, the millis() count will be suspended, leading to effective suspension of scheduling. Upon wake up, active tasks need to be re-enabled, which will effectively reset their internal time scheduling variables to the new value of millis(). Time spent in deep sleep mode should be considered “frozen”, i.e., if a task was scheduled to run in 1 second from now, and device was put to sleep for 5 minutes, upon wake up, the task will still be scheduled 1 second from the time of wake up. Executing enable() function on this tasks will make it run as soon as possible. This is a concern only for tasks which are required to run in a truly periodical manner (in absolute time terms).

COMPILE PARAMETERS:

This library could be compiled with several options.

These parameters must be defined before inclusion of the library header file into the sketch.

#define _TASK_TIMECRITICAL

...will compile the library with time critical tracking option enabled.

Time critical option keeps track where next execution time of the task falls, and makes it available via API through Task:: getOverrun() function. If getOverrun returns a negative value, this Task’s next execution time is in the past, and task is behind schedule. This most probably means that either task’s callback function runtime is too long, or the execution interval is too short (then schedule is too aggressive).

A positive value indicates that task is on schedule, and callback functions have enough time to finish before the next scheduled pass.

#define _TASK_SLEEP_ON_IDLE_RUN

...will compile the library with the sleep option enabled (AVR boards only).

When enabled, scheduler will put the microcontroller into SLEEP_MODE_IDLE state if none of the tasks’ callback functions were activated during pass. IDLE state is interrupted by timers once every 1 ms. Helps conserve power. Device in SLEEP_MODE_IDLE wakes up to all hardware and timer interrupts, so scheduling is kept current.

NOTE: above parameters are DISABLED by default, and need to be explicitly enabled.

API DOCUMENTATION:

TASKS:

CREATION:

Task();

Default constructor.

Takes no parameters and creates a task that could be scheduled to run at every scheduling pass indefinitely, but does not have a callback function defined, so no execution will actually take place.

All tasks are created disabled by default.

Task(unsigned long aInterval, long aIterations, void (*aCallback)(), Scheduler* aScheduler, bool aEnable);

Constructor with parameters.

Creates a task that is scheduled to run every <aInterval> milliseconds, <aIterations> times, executing <aCallback> function on every pass.

1. aInterval is in milliseconds

2. aIteration in number of times, -1 for indefinite execution
   Note: Tasks do not remember the number of iteration set initially. After the iterations are done, internal iteration counter is 0. If you need to perform another set of iterations, you need to set the number of iterations again.
   Note: Tasks which performed all their iterations remain active.

3. aCallback is a pointer to a void function without parameters

4. aScheduler – optional reference to existing scheduler. If supplied (not NULL) this task will be appended to the task chain of the current scheduler). Default=NULL

5. aEnable – optional. Value of true will create task enabled. Default = false

All tasks are created disabled by default (unless aEnable = true). You have to explicitly enable the task for execution.

Enabled task is scheduled for execution immediately. Enable tasks with delay (standard execution interval or specific execution interval) in order to defer first run of the task.

INFORMATION

The following 3 “getter” functions return task status (enabled/disabled), execution interval in milliseconds, number of remaining iterations.

bool isEnabled()

unsigned long getInterval()

long getIterations()

long getOverrun()

If library is compiled with _TASK_TIMECRITICAL enabled, tasks are monitored for “long running” scenario. A “long running” task is a task that does not finish processing its callback functions quickly, and thus creates a situation for itself and other tasks where they don't run on a scheduled interval, but rather “catch up” and are behind. When task scheduler sets the next execution target time, it adds Task's execution interval to the previously scheduled execution time:

next execution time = previous execution time + task execution interval

If next execution time happens to be already in the past (next execution time < millis()), then task is considered overrun. GetOverrun function returns number of milliseconds between next execution time and current time. If the value is negative, the task is overrun by that many milliseconds.

Positive value indicate number of milliseconds of slack this task has for execution purposes.

bool isFirstIteration()

bool isLastIteration()

For tasks with a defined number of iterations, indicates whether current pass is a first or a last iteration of the task (respectively).

CONTROL:

void enable();

Enables the task, and schedules it for immediate execution (without delay) at this or next scheduling pass depending on when the task was enabled. Scheduler will execute the next pass without any delay because there is a task which was enabled and requires execution.

void delay();

Schedules the task for execution after a delay (aInterval), but does not change the enabled/disabled status of the task.

void enableDelayed();

Enables the task, and schedules it for execution after a delay (aInterval).

void enableDelayed (unsigned long aDelay);

Enables the task, and schedules it for execution after a specific delay (aDelay, which maybe different from aInterval).

void restart();

For tasks with limited number of iterations only, restart function will re-enable the task, set the number of iterations back to when the task was created and and schedule the task for execution as soon as possible.

void restartDelayed (unsigned long aDelay);

Same as restart() function, with the only difference being that Task is scheduled to run first iteration after a delay = aDelay milliseconds.

void disable();

Disables the task. Scheduler will not execute this task any longer, even if it remains in the chain. Task can be later re-enabled for execution.

void set(unsigned long aInterval, long aIterations, void (*aCallback)());

Allows dynamic control of all task execution parameters in one function call.

Next three “setter” functions allow changes of individual task execution control parameters.

void setInterval (unsigned long aInterval)

void setIterations (long aIterations)

void setCallback (void (*aCallback)())

Note: Next execution time calculation takes place after the callback function is called, so new interval will be used immediately by the scheduler. For the situations when one task is changing the interval parameter for the other, setInterval function calls delay explicitly to guarantee schedule change, however it does not enable the task if task is disabled.

Note: Tasks that ran through all their allocated iterations are disabled. SetIterations() method DOES NOT enable the task. Either enable explicitly, or use restart methods.

TASK SCHEDULER:

CREATION:

Scheduler()

Default constructor.

Takes no parameters. Creates task scheduler with default parameters and an empty task queue.

void init()

Initializes the task queue and scheduler parameters, Executed as part of constructor, so don't need to be explicitly called after creation.

Note: be default (if compiled with _TASK_TIMECRITICAL enabled) scheduler is allowed to put processor to IDLE sleep mode. If this behavior was changed via allowSleep() function, inti() will NOT reset allow sleep particular parameter.

void addTask(Task& aTask)

Adds task aTask to the execution queue (or chain) of tasks by appending it to the end of the chain. If two tasks are scheduled for execution, the sequence will match the order tasks are appended to the chain. However, in reality, due to different timing of task execution, the actual order will be different.

Note: Currently, changing the execution dynamically is not supported.

If you need to reorder the queue – initialize the scheduler and re-add the tasks in a different order.

void deleteTask(Task& aTask)

Deletes task aTask from the execution chain. The chain of remaining tasks is linked together (i.e

if original task chain is 1 → 2 → 3 → 4, deleting 3 will result in 1 → 2 → 4).

Note: it is not required to delete a task from the chain. A disabled task will not be executed anyway, but you save a few microseconds per scheduling pass by deleting it, since it is not even considered for execution.

An example of proper use of this function would be running some sort of initialize task in the chain, and then deleting it from the chain since it only needs to run once.

void allowSleep(bool aState)

Available in API only if compiled with _TASK_TIMECRITICAL enabled. Controls whether scheduler is allowed (aState =true), or not (aState =false) to put processor into IDLE sleep mode in case not tasks are scheduled to run.

The default behavior of scheduler upon creation is to allow sleep mode.

void enableAll()

void disableAll()

enables and disables (respectively) all tasks in the chain. Convenient if your need to enable/disable majority of the tasks (i.e. disable all and then enable one).

Task& currentTask()

Returns reference to the task, currently executing via execute() loop. Could be used by callback functions to identify which of the

void execute()

Executes one scheduling pass, including end-of-pass sleep. This function typically placed inside the loop() function of the sketch. Since execute exits after every pass, you can put additional statements after execute inside the loop()

IMPLEMENTATION SCENARIOS AND IDEAS:

1. EVENT DRIVEN PROGRAMMING

Each of the processes of your application becomes a separate and distinct programming area, which may or may not interact and control each other.

Example:

In a plant watering system you need to measure soil humidity, control pump and display the results

Each of the areas becomes a task:

Task tMeasure (TMEASURE_INTERVAL*SECOND, -1, &measureCallback);
Task tWater (TWATER_INTERVAL*SECOND, RETRIES, &waterCallback);
Task tDisplay (TDISPLAY_INTERVAL*SECOND, -1, &displayCallback);

Scheduler taskManager;

Further, once you turn on the pump, you keep it running for TWATER_INTERVAL interval and then turn it off. Turning off a pump is also a task which only needs to run once for every time the pump is turned on:

Task tWaterOff (WATERTIME*SECOND, 1, &waterOffCallback);

Example of the callback function:

void waterOffCallback() {
motorOff();
tWater.enableDelayed();
}

or

void waterCallback() {
if (tWater.getIterations()) {

// If this is not the last iteration = turn the pump on
motorOn();
tWaterOff.set(parameters.watertime * SECOND, 1, &waterOffCallback);
tWaterOff.enableDelayed();
return;
}

// We could not reach target humidity – something is wrong
motorOff;
taskManager.disableAll();
tError.enable();
}

Your sample setup() and loop() (partially) are as follows.

Note: please note that tWater is not activated during setup(). It is activated by tMeasure callback once the watering conditions are met.

setup()

...

tWater.setIterations(parameters.retries);
tWaterOff.setInterval(parameters.watertime * SECOND);


taskManager.init();
taskManager.addTask(tMeasure);
taskManager.addTask(tDisplay);
taskManager.addTask(tWater);
taskManager.addTask(tWaterOff);

tMeasure.enable();
tDisplay.enable();

currentHumidity = measureHumidity();
}


void loop ()
{
taskManager.execute();
}

2. “NATIVE” SUPPORT FOR FINITE STATE MACHINE

Define “states” as callback function or functions. Each callback function executes activities specific to a “state” and then “transitions” to the next state by assigning next callback function to the task.

Transition from one state to the next is achieved by setting next callback function at the end of preceding one.

Note: do not call the next callback function. Let the schedule take care of that during the next pass. (Thus letting other tasks run).

Example: Blinking LED 2 times a second could be achieved this way

Task tLedBlinker (500, -1, &ledOnCallback);

Scheduler taskManager;

void ledOnCallback() {

turnLedOn();

tLedBlinker.setCallback(&ledOffCallback);

}

void ledOffCallback() {

turnLedOff();

tLedBlinker.setCallback(&ledOnCallback);

}

setup() {

taskManager.init();
taskManager.addTask(tLedBlinker);

tLedBlinker.enable();

}

loop () {

taskManager.execute();

}

Obviously the example is simple, but gives the idea of how the tasks could be used to go through states.

3. MULTIPLE POSSIBLE CALLBACKS FOR TASK

There may be a need to select an option for callback function based on certain criteria, or randomly.

You can achieve that by defining an array of callback function pointers and selecting one based on the criteria you need.

Example: when a robot detects an obstacle, it may go left, right backwards, etc. Each of the “directions” or “behaviors” are represented by a different callback function.

Another example of using multiple callbacks:

You may need to “initialize” variables for a particular task.

In this case, define a tasks with two callbacks:

Task tWork (T_INTERVAL, -1, &workCallbackInit);

…

void workCallbackInit() {

// do your initializationstuff here

// finally assigne the main callback function

tWork.setCallback(&workCallback);

}

void workCallback() {

// main callback function

…

}

The task will initialize during first execution pass and switch to “regular” callback execution starting with second pass. There is a delay between first and second passes of the task (scheduling period, if defined). In order to execute the second pass immediately after initialization first pass, change the above code like this:

void workCallbackInit() {

// do your initializationstuff here

// finally assigne the main callback function

tWork.setCallback(&workCallback);

tWork.enable();

}

The task will run initialization first, then immediately second pass, and then switch to processing at regular intervals starting with a third pass.

3. INTERRUP-DRIVEN EXECUTION SUPPORT

In case of interrupt-driven program flow, tasks could be scheduled to run once to request asynchronous execution (request), and then re-enabled (restarted) again with a different callback function to process the results.

Example: event driven distance calculation for ultrasonic pulses. EchoPin #6 triggers pin change interrupts on rising and falling edges to determine the length of ultrasonic pulse.

#include <DirectIO.h>
#include <TaskScheduler.h>
#include <PinChangeInt.h>


#define TRIGGERPIN 5
#define ECHOPIN 6

Output<TRIGGERPIN> pTrigger;
Input<ECHOPIN> pEcho;

Scheduler r;

Task tMeasure(1000, -1, &measureCallback);
Task tDisplay(1000, -1, &displayCallback);
Task tPing(0, 1, &pingCalcCallback);


volatile bool pulseBusy = false;
volatile bool pulseTimeout = false;
volatile unsigned long pulseStart = 0;
volatile unsigned long pulseStop = 0;
volatile unsigned long pingDistance = 0;


void pingTrigger(unsigned long aTimeout) {
if (pulseBusy) return; // do not trigger if in the middle of a pulse
if (pEcho == HIGH) return; // do not trigger if ECHO pin is high

pulseBusy = true;
pulseTimeout = false;

pTrigger = LOW;
delayMicroseconds(4);
pTrigger = HIGH;

tPing.setInterval (aTimeout);

delayMicroseconds(10);
pTrigger = LOW;

tPing.restartDelayed(); // timeout countdown starts now

// will start the pulse clock on the rising edge of ECHO pin

PCintPort::attachInterrupt(ECHOPIN, &pingStartClock, RISING);
}

// Start clock on the rising edge of the ultrasonic pulse
void pingStartClock() {
pulseStart = micros();
PCintPort::detachInterrupt(ECHOPIN); // not sure this is necessary
PCintPort::attachInterrupt(ECHOPIN, &pingStopClock, FALLING);
tPing.restartDelayed();
}

// Stop clock on the falling edge of the ultrasonic pulse
void pingStopClock() {
pulseStop = micros();
PcintPort::detachInterrupt(ECHOPIN);

pingDistance = pulseStop - pulseStart;
pulseBusy = false;
tPing.disable(); // disable timeout
}

// Stop clock because of the timeout – the wave did not return
void pingCalcCallback() {
if (pulseBusy) {
pingStopClock();
}
pulseTimeout = true;
}



// Initial measure callback sets the trigger
void measureCallback() {
if (pulseBusy) { // already measuring, try again
tMeasure.enable();
return;
}
pingTrigger(30); // 30 milliseconds or max range of ~5.1 meters
tMeasure.setCallback(&measureCallbackWait);
}

// Wait for the measurement to
void measureCallbackWait() {
if (pulseBusy) return;
tMeasure.setCallback(&measureCallback);
}


bool state = true;

void displayCallback() {
char d[256];

unsigned long cm = pingDistance * 17 / 100; // cm

snprintf(d, 256, "pulseStart = %8lu\tpulseStop=%8lu\tdistance, cm=%8lu", pulseStart, pulseStop, cm);
Serial.println(d);

}

void setup() {
// put your setup code here, to run once:

Serial.begin(115200);


pTrigger = LOW;
pEcho = LOW;

r.init();
r.addTask(tDisplay);
r.addTask(tMeasure);
r.addTask(tPing);

r.enableAll();
tPing.disable();
}

void loop() {
// put your main code here, to run repeatedly:
r.execute();
}