ustd::Scheduler Class Reference

muwerk Scheduler Class More...

#include <scheduler.h>

Public Member Functions
	Scheduler (int nTaskListSize=2, int queueSize=2, int nSubscriptionListSize=2)
bool	publish (String topic, String msg="", String originator="")
int	subscribe (int taskID, String topic, T_SUBS subs, String originator="")
bool	unsubscribe (int subscriptionHandle)
int	add (T_TASK task, String name, unsigned long minMicroSecs=100000L, T_PRIO prio=PRIO_NORMAL)
bool	remove (int taskID)
bool	reschedule (int taskID, unsigned long minMicroSecs=100000L, T_PRIO prio=PRIO_NORMAL)
unsigned long	getUptime ()
void	singleTaskMode (int _singleTaskID)
void	loop ()

Static Public Member Functions
static bool	mqttmatch (const String pubstr, const String substr)

Detailed Description

muwerk Scheduler Class

Implements a cooperative task scheduler. Tasks are defined as void myTask() type functions and can be added to the scheduler for execution at fixed intervals. Tasks can communicate with each other via pub/sub messages, using MQTT-style topics for subscription and publishing of messages.

The library header-only.

Make sure to provide the required platform define before including ustd headers.

Minimal scheduler:

#define __ATMEGA__ 1   // Platform defines required, see doc, mainpage.
#include <scheduler.h>
 
ustd::Scheduler sched;
void appLoop();
 
void someTask() {
    // This is called every 50ms (50000us)
    // Do things here
}
 
void setup() {
    // Create a task for the main application loop code:
    int tID = sched.add(appLoop, "main");
 
    // Create a second task that is called every 50ms
    sched.add(someTask, "someTask", 50000L);
}
 
void appLoop() {
    // your code you would normally put into Arduino's loop goes here.
    // use async programming to prevent locking the cooperative scheduler.
}
 
// Never add code to this loop, use appLoop() instead.
void loop() {
    sched.loop();
}

Pub/Sub communication between tasks

#define __ESP__ 1   // Platform defines required, see doc, mainpage.
#include "scheduler.h"
 
ustd::Scheduler sched;
void appLoop();
 
void subMsg(String topic, String msg, String originator) {
    if (msg == "on")
        digitalWrite(LED_BUILTIN, LOW);  // Turn the LED on
    if (msg == "off")
        digitalWrite(LED_BUILTIN, HIGH);  // Turn the LED off
}
 
void pubTask() {
    // Publish a "led" "on/off" message every 500ms
    static int s1 = 0;
    static unsigned long t1;
    if (ustd::timeDiff(t1, millis()) > 500L) {
        if (s1 == 0) {
            s1 = 1;
            sched.publish("led", "on");
        } else {
            s1 = 0;
            sched.publish("led", "off");
        }
        t1 = millis();
    }
    if (t1 == 0)
        t1 = millis();
}
 
void setup() {
    pinMode(LED_BUILTIN, OUTPUT);
 
    // Create a task for general use:
    int tID = sched.add(appLoop, "main");
 
    // Subscribe to "led" messages. subMsg will be called on receive of "led"
    // dmessages.
    sched.subscribe(tID, "led", subMsg);
 
    // Create a task that will publish "led" messages
    sched.add(pubTask, "pubTask", 50000L);
}
 
void appLoop() {
    // your code goes here.
}
 
// Never add code to this loop, use appLoop() instead.
void loop() {
    sched.loop();
}

Constructor & Destructor Documentation

Scheduler()

ustd::Scheduler::Scheduler ( int  nTaskListSize = 2, int  queueSize = 2, int  nSubscriptionListSize = 2  )

inline

Instantiate a cooperative scheduler

All list sizes are optional, they will be dynamically incremented, if necessary.

Member Function Documentation

add()

int ustd::Scheduler::add ( T_TASK  task, String  name, unsigned long  minMicroSecs = 100000L, T_PRIO  prio = PRIO_NORMAL  )

inline

Add a task to the schedule

Parameters

task	Task function of type void myTask() that will be called by the scheduler. This can be a member function for ESP and Unixoid platforms (Functional support).
name	Task name (for statistics)
minMicroSecs	Task function is called every minMicroSecs. Note this is not guaranteed, because it's a cooperative scheduler.
prio	Not yet supported.

Returns

taskID is successful, -1 on error.

getUptime()

unsigned long ustd::Scheduler::getUptime ( )

inline

Get uptime in seconds

$

Returns

Returns the number of seconds passed since system start.

loop()

void ustd::Scheduler::loop ( )

inline

Main scheduler loop This loop() function should be called in Arduino's loop() function. Preferably no other code should be in Arduino's loop().

mqttmatch()

static bool ustd::Scheduler::mqttmatch ( const String  pubstr, const String  substr  )

inlinestatic

compare publish and subscribe topics.

subscriptions can contain the MQTT wildcards '#' and '+'.

Parameters

pubstr	Topic that is being published. No wildcards allowed.
substr	Topics that are subscribed, allows MQTT wildcards '#' and '+'.

Returns

true, if pubstr matches substr, false otherwise.

publish()

bool ustd::Scheduler::publish ( String  topic, String  msg = "", String  originator = ""  )

inline

publish a message to a given topic

Parameters

topic	MQTT-style topic of the message (no wildcards allowed)
msg	Message content
originator	Optional name of originator-task

Returns

true on successful publish.

remove()

bool ustd::Scheduler::remove ( int  taskID )

inline

Remove an existing task

Parameters

taskID

Remove the corresponding task from scheduler

Note: a task can't delete itself while being executed.

Returns

true, if task was found and removed, false on error

reschedule()

bool ustd::Scheduler::reschedule ( int  taskID, unsigned long  minMicroSecs = 100000L, T_PRIO  prio = PRIO_NORMAL  )

inline

Reschedule an existing task

Parameters

taskID	Task ID to be rescheduled
minMicroSecs	New schedule: task function is called every minMicroSecs. If minMicrosSecs is set to zero, the task's process-function is not called any more. Note: this is not guaranteed, because it's a cooperative scheduler.
prio	Not yet supported.

Returns

true, if task was found and rescheduled, false on error

singleTaskMode()

void ustd::Scheduler::singleTaskMode ( int  _singleTaskID )

inline

Instruct scheduler to go into single-task mode

Parameters

_singleTaskID

taskID of the task that should be executed exclusively. This is useful for time-critical procedures like OTA firmware updates. If _singleTaskID is -1, normal schedule operation of all existing tasks resumed.

subscribe()

int ustd::Scheduler::subscribe ( int  taskID, String  topic, T_SUBS  subs, String  originator = ""  )

inline

Subscribe to a topic to receive messages published to this topic

Parameters

taskID	taskID of the task that is associated with this subscriptions (only used for statistics)
topic	MQTT-style topic to be subscribed, can contain MQTT wildcards '#' and '*'. (A subscription to '#' receives all pubs)
subs	Callback of type void myCallback(String topic, String msg, String originator) that is called, if a matching message is received. On ESP or Unixoid platforms, this can be a member function.
originator	Optional name of associated task.

Returns

subscriptionHandle on success (needed for unsubscribe), or -1 on error.

unsubscribe()

bool ustd::Scheduler::unsubscribe ( int  subscriptionHandle )

inline

Unsubscribe a subscription

Parameters

subscriptionHandle

Handle to subscription as returned by Subscribe

Returns

true on successful unsubscription, false if no corresponding subscription is found.

---

The documentation for this class was generated from the following file:

• scheduler.h