Skip to content

Reference

Jump to bottom
Vishnu Mohanan edited this page Dec 6, 2020 · 12 revisions

Macro Constants

Here we have all the modes and constants defined.

#define debugSerial   Serial  //for debugging

//task modes
#define PT_MODE_EPO     1   //Equal, Periodic, Oneshot
#define PT_MODE_EIO     2   //Equal, Iterated, Oneshot
#define PT_MODE_UPO     3   //Unequal, Periodic, Oneshot
#define PT_MODE_UIO     4   //Unequal, Iterated, Oneshot
#define PT_MODE_EPS     5   //Equal, Periodic, Spanning
#define PT_MODE_EIS     6   //Equal, Iterated, Spanning
#define PT_MODE_UPS     7   //Unequal, Periodic, Spanning
#define PT_MODE_UIS     8   //Unequal, Iterated, Spanning

//sleep modes
#define PT_SLEEP_DISABLE     1    //self-disable mode
#define PT_SLEEP_SUSPEND     2    //self-suspend mode

Typedefs

typedef uint64_t time_ms_t;  //time in milliseconds

There is only one custom type defined. time_ms_t is for storing millisecond values.

Class

class ptScheduler;

There is only one class that wraps all the functions, state variables and counters for every task.

Member Functions

ptScheduler (time_ms_t interval_1); //sets the initial interval for the task
ptScheduler (uint8_t _mode, time_ms_t interval_1);
ptScheduler (uint8_t _mode, time_ms_t interval_1, time_ms_t interval_2);
ptScheduler (uint8_t _mode, time_ms_t* listPtr, uint8_t listLength);
~ptScheduler();
void reset(); //disable + enable
void enable();  //enabling a task to run at each intervals
void disable();  //block a task from running and reset all state variables and counters
void suspend();  //block a task from running but without resetting anything. interval counter will still run.
void resume();  //resume a suspended task
bool call();  //the task invokation call
bool setInterval (time_ms_t value);  //dynamically set task interval
bool setInterval (time_ms_t value_1, time_ms_t value_2);  //update two interval values. only for tasks instantiated with >= intervals
bool setIteration (int32_t value);  //no. of iterations you want to execute for each activation
bool setSkipInterval (uint32_t value);  //intervals to wait before executing the task
bool setSkipIteration (uint32_t value); //iterations to wait before executing the task
bool setSkipTime (time_ms_t value); //time to wait before executing the task
bool setTaskMode (uint8_t mode);  //set execution mode
bool setSleepMode (uint8_t mode); //set what happens after an iteration is complete
bool isInputError();
void printStats();  //prints all the statuses and counter to debug port

Constructors & Destructor

ptScheduler (time_ms_t interval_1);

This is the simplest method to create a ptScheduler object.

Parameters :

  1. interval_1 : Time in milliseconds. The task mode will be set to PT_MODE_EPO and other values to their defaults. An array will be dynamically allocated to hold the interval value and the pointer intervalList is updated with the address of this location. intervalLength will be set to 1.

Return : Nothing

ptScheduler (uint8_t _mode, time_ms_t interval_1);

This is the same as the previous one but we can explicitly specify the task mode here. For a single interval, only PT_MODE_EPO, PT_MODE_EIO, PT_MODE_EPS and PT_MODE_EIS modes are supported.

Parameters :

  1. _mode : Any of the 8 supported modes.
  2. interval_1 : Time in milliseconds.

Return : Nothing

ptScheduler (uint8_t _mode, time_ms_t interval_1, time_ms_t interval_2);

Create a task with two intervals. The interval values can be same or different. Same as before, a list will be allocated and intervalList will be pointed to that location. intervalCount will be 2 in this case.

Parameters :

  1. _mode : Any of the 8 supported modes.
  2. interval_1 : Time in milliseconds.
  3. interval_2 : Time in milliseconds.

Return : Nothing

ptScheduler (uint8_t _mode, time_ms_t* listPtr, uint8_t c);

Create a task with an arbitrary number of intervals. You first have to create an array of interval values something like below,

time_ms_t intervalArray[] = {1000, 1000, 2000, 2500, 3000};

then pass the address to the constructor like below,

ptScheduler uisTask = ptScheduler(PT_MODE_UIS, intervalArray, 2);  //unequal, iterated, spanning

Parameters :

  1. _mode : Any of the 8 supported modes.
  2. listPtr : Address of array of intervals.
  3. listLength : Number of intervals in the array. This value should be less than or equal to the number of values in the array.

Return : Nothing

~ptScheduler();

The destructor does nothing.

Parameters : None

Return : Nothing

reset()

void reset();

This function resets all status variables and counters to their default values. But no user defined values will be reset, such as the intervals, iterations, skip time etc. After resetting, it will also enable the task allowing you to start fresh.

Parameters : None

Return : Nothing

enable()

void enable();

This function enables a task by setting the enabled status variable to true. Only enabled tasks can run.

Parameters : None

Return : Nothing

disable()

void disable();

This function disables a task by setting the enabled status variable to false. Only enabled tasks can run.

Parameters : None

Return : Nothing

suspend()

void suspend();

Suspending a task means it will no longer run, but some of the counter variables will continue to increment. When a task is suspended, it is said to be in sleep. A task remains in sleep mode until we manually activate it again. In sleep mode, intervalCounter will continue to increment for every interval passed. If you have multiple intervals, each of them will cause intervalCounter to increment in a round-robin fashion. sleepIntervalCounter will keep track of how many intervals have passed after entering sleep mode. You can use either of these counters to conditionally activate the task at later point using the resume() function.

Parameters : None

Return : Nothing

resume()

void resume();

Resumes a suspended task.

Parameters : None

Return : Nothing

call()

bool call();

This is the main task invocation function. You should enclose this function inside any conditional statements to run the block of code under it. If it is time to run a task, call() will return true, and otherwise false.

Parameters : None

Return :

  1. true : Run the code block
  2. false : Skip the code block

setInterval()

bool setInterval (time_ms_t value);

Use this function if you need to change the interval after creating the object, or dynamically. If you created the object with more than one intervals, then only the first value will be updated.

Parameters :

  1. value : Time in milliseconds

Return :

  1. true : Setting interval was successful.
  2. false : Setting interval was unsuccessful. It can only fail if the intervalCount was 0.
bool setInterval (time_ms_t value_1, time_ms_t value_2);

This updates the first two interval values in the interval list. If the interval count is less than 2, this operation will fail.

Parameters :

  1. value_1 : Time in milliseconds
  2. value_2 : Time in milliseconds

Return :

  1. true : Setting interval was successful.
  2. false : Setting interval was unsuccessful. It can only fail if the intervalCount was less than 2.

setIteration()

bool setIteration (int32_t value);

This creates an iterated task. After the specified number of iterations has executed, the task will enter to sleep. The sleep mode is determined by what you have set with setSleepMode().

Parameters :

  1. value : Number of iterations (positive integer)

Return :

  1. true : Setting iterations was successful.
  2. false : Setting iteration was unsuccessful. This can only fail if the task mode is invalid.

setSkipInterval()

bool setSkipInterval (uint32_t value);

This calculates the skip time from the interval values. For example, if the interval is 1000 ms, setting setSkipInterval(5) will produce a skip time of 5 * 1000 = 5000 ms. If you have multiple intervals, each of the intervals will be added up to value times. The final value is assigned to skipTime and the flags skipIntervalSet and skipTimeSet are set to true.

Parameters :

  1. value : Number of intervals to skip (positive integer)

Return :

  1. true : Setting skip interval was successful.
  2. false : Setting skip interval was unsuccessful. This can only fail if intervalCount was 0.

setSkipIteration()

bool setSkipIteration (uint32_t value);

This calculates the skip time from the iteration values. Each iteration is a set of one or more interval values. The skip time is calculated as value * (sum of intervals in the interval list). The final value is assigned to skipTime and the flags skipIterationSet and skipTimeSet are set to true.

Parameters :

  1. value : Number of iterations to skip (positive integer)

Return :

  1. true : Setting skip iteration was successful.
  2. false : Setting skip iteration was unsuccessful. This can only fail if intervalCount was 0.

setSkipTime()

bool setSkipTime (time_ms_t value);

This directly sets the skipTime and the skipTimeSet flag.

Parameters :

  1. value : Time in milliseconds

Return :

  1. true : Setting skip time was successful.
  2. false : Setting skip time was unsuccessful. This can only fail if intervalCount was 0.

setTaskMode()

bool setTaskMode (uint8_t mode);

Sets the task mode.

Parameters :

  1. mode : One of the 8 supported modes.

Return :

  1. true : Setting task mode was successful.
  2. false : Setting task mode was unsuccessful. This can only fail if the input value was invalid.

setSleepMode()

bool setSleepMode (uint8_t mode);

Sets the sleep mode. A task enters into sleep mode after the specified number of iterations has completed. That means, sleep mode only applies to iterated tasks. The values can be, PT_SLEEP_DISABLE for disabling the task (reset all states and counters) or PT_SLEEP_SUSPEND for suspending the task.

Parameters :

  1. mode : One of the 2 supported modes - PT_SLEEP_DISABLE, PT_SLEEP_SUSPEND

Return :

  1. true : Setting sleep mode was successful.
  2. false : Setting sleep mode was unsuccessful. This can only fail if the input value was invalid.

isInputError()

bool isInputError();

If any of the user inputs were invalid, the inputError flag is set. This function will return the value of inputError and also reset it.

Parameters : None

Return :

  1. true : inputError is true.
  2. false : No input error.

printStats()

void printStats();

Prints all the status variables, flags and counters to the serial port. Useful for debugging.

Parameters : None

Return : Nothing

Member Variables

I think these are self-explanatory.

time_ms_t entryTime = 0;  //the entry point of a task, returned by millis()
time_ms_t exitTime = 0; //the exit point of a task, returned by millis()
time_ms_t elapsedTime = 0;  //elapsed time since the last task execution
uint64_t intervalCounter = 0; //how many intervals have been passed
uint64_t sleepIntervalCounter = 0; //how many intervals have been passed after disabling/suspending the task
uint64_t executionCounter = 0; //how many times the task has been executed
uint64_t iterationCounter = 0; //how many times the iteration set has been executed

uint32_t iterations = 0;  //how many times a task has to be executed, for each activation
uint32_t iterationsExtended = 0;  //how many times a task has to be executed, for each activation
uint8_t taskMode = PT_MODE_EPO;  //the execution mode of a task
uint8_t sleepMode = PT_SLEEP_DISABLE; //default is disable
uint8_t intervalCount;  //how many intervals have been passed
time_ms_t* intervalList;  //a pointer to array of intervals
uint8_t intervalIndex = 0;  //the position in the interval list
uint32_t skipInterval = 0;  //number of intervals to skip
uint32_t skipIteration = 0; //number of iterations to skip
time_ms_t skipTime = 0; //time to skip before running a task

bool enabled = true;  //a task is allowed to run or not
bool taskStarted = false; //a task has started an execution cycle
bool cycleStarted = false; //a task has started an interval cycle
bool suspended = false; //a task is prevented from running until further activation
bool iterationEnded = false;  //end of an iteration set
bool running = false; //a task is running
bool runState;  //the current execution state of a task

bool inputError = false;  //if any user input parameters are wrong
bool skipIntervalSet = false; //if skip interval was set
bool skipIterationSet = false;  //if skip iteration was set
bool skipTimeSet = false; //if skip time was set
Clone this wiki locally