Arduino library · Data and time

TaskScheduler: cooperative multitasking for Arduino and ESP32

Yes. You can use the TaskScheduler library online in Mokxi with nothing to install, and the sketch runs in your browser. The example below, "Two tasks at two rates", runs on the Arduino Uno R3.

Built in on Mokxi: #include <TaskScheduler.h> and it builds, with nothing to install. Free, and no account needed.

What TaskScheduler does

TaskScheduler by Anatoli Arkhipenko lets a sketch do several things at different rates without delay() and without a real operating system. Each job is a Task with an interval, a number of iterations and a callback; a Scheduler holds the tasks, and calling its execute() from loop() runs every task that is due. Blinking an LED every 250 ms while reporting a sensor every second becomes two lines of setup instead of a tangle of millis() variables.

It is cooperative, not preemptive. A callback runs to the end before the next one starts, so one long callback holds up every other task. The win is that no task can be interrupted halfway through, so there are no shared-variable races to guard against, unlike FreeRTOS threads on an ESP32.

Tasks can run forever (TASK_FOREVER) or a fixed number of times, start later with enableDelayed(), change their own interval, and tell how many times they have run with getRunCounter(). The example on this page blinks pin 13 every 250 ms and prints a report three times, once a second, then that task stops on its own. Optional features such as status requests and timeouts are switched on with #define lines before the include.

Library Manager nameTaskScheduler
AuthorAnatoli Arkhipenko
Include#include <TaskScheduler.h>
#include <TaskSchedulerDeclarations.h>
#include <TScheduler.hpp>
#include <TSchedulerDeclarations.hpp>
Boardsevery board Mokxi compiles for
In the simulatorSimulated: it runs against the part the way it does on the bench.

Install it

It builds on every board Mokxi compiles for.

In Mokxi it is built in: #include <TaskScheduler.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "TaskScheduler" by Anatoli Arkhipenko from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add TaskScheduler to lib_deps in PlatformIO. Mokxi follows the calls of release 4.1.1, so a sketch written here builds there too.

What to know in the simulator: The idle pass of _TASK_SLEEP_ON_IDLE_RUN sleeps with delay(1). _TASK_THREAD_SAFE takes the sketch’s own queue functions, as upstream.

The calls you will use

In the order a sketch meets them.

Task tBlink(250, TASK_FOREVER, &blink)

A task that runs blink() every 250 ms forever. Declare the callback above it, or give a prototype, since the task takes its address.

Scheduler runner

The object that holds the tasks and runs them. A sketch usually has one, declared as a global.

runner.addTask(tBlink)

Puts a task in the scheduler’s chain. Adding does not start it: a task is created disabled unless you pass true as the last constructor argument.

tBlink.enable()

Starts the task; its first run happens on the next execute(). enableDelayed(500) starts it half a second later instead.

runner.execute()

Runs every enabled task that is due, once each. Call it on every pass of loop() and keep loop() free of delay().

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

tReport.getRunCounter()

How many times the task has run since it was enabled, starting at 1 inside its first callback.

tBlink.setInterval(100)

Changes the period while the task runs, for a blink that speeds up on an alarm, say.

tReport.disable()

Stops the task. A task with a set number of iterations disables itself after the last one.

Example: Two tasks at two rates

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3
#include <TaskScheduler.h>

void blink();
void report();

Task tBlink(250, TASK_FOREVER, &blink);
Task tReport(1000, 3, &report);
Scheduler runner;

void setup() {
  Serial.begin(9600);
  pinMode(13, OUTPUT);
  runner.init();
  runner.addTask(tBlink);
  runner.addTask(tReport);
  tBlink.enable();
  tReport.enable();
}

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

void blink() {
  digitalWrite(13, !digitalRead(13));
}

void report() {
  Serial.print("report ");
  Serial.print(tReport.getRunCounter());
  Serial.print(" after ");
  Serial.print(tBlink.getRunCounter());
  Serial.println(" blinks");
}

Open it in the editor, wired and ready to run

Common errors and how to fix them

'blink' was not declared in this scope

The Task is declared above the function it calls. Add a prototype such as void blink(); before the Task line, as the example does, or move the callback above the Task declaration.

A task is added but its callback never runs

Tasks start disabled. Call enable() on each one after addTask(), or construct it with the scheduler and true as the last arguments so it is added and enabled in one step.

Tasks run late or bunch together

Some callback or loop() itself is blocking, usually with delay() or a slow sensor read. Since the scheduler is cooperative, break long work into shorter steps and let execute() come round often.

Questions and answers

Is TaskScheduler the same as FreeRTOS?

No. FreeRTOS switches between threads by itself, each with its own stack. TaskScheduler runs callbacks one after another from loop(), which costs little RAM and works on an Uno.

Can a task run on micros() instead of millis()?

Yes. Put #define _TASK_MICRO_RES before the include and the intervals are counted in microseconds.

Try TaskScheduler without installing anything

Open the example, change the sketch, and keep your version in a free account.