-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
b87f34d
commit 0294aa1
Showing
2 changed files
with
67 additions
and
253 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,186 +1,97 @@ | ||
| # Overview | ||
|
|
||
| Yet another cooperative multitasking scheduler for Arduino processors. I was unable to make the | ||
| current crop of schedulers work correctly, so I decided to write my own. | ||
| This version is a simpler implementation of the flavor of TaskScheduler | ||
| (<https://github.com/arkhipenko/TaskScheduler>). | ||
|
|
||
| TaskSched has been tested on ESP32 and ESP8266 processors. I see no reason that it shouldn't work | ||
| on other boards, unless it takes too much memory. I'll eventually test it on some Arduino and Teensy boards. | ||
|
|
||
| ## Main Features | ||
|
|
||
| 1. Periodic task execution. The interval is specified in the task | ||
| creation but can be changed. The times are in milliseconds only. | ||
| Unlike TaskScheduler, the timing isn't necessarily exact if the | ||
| program takes too much time in a task. It's scheduled on a best | ||
| effort basis. If the code is tight enough it'll work if your time | ||
| constraints aren't critical. There is no "catchup" support. | ||
|
|
||
| 2. Support for task enable/disable. | ||
|
|
||
| 3. Support for number of iterations the task can make. The task will be | ||
| disabled when the iteration count is exhausted. Unlimited iterations | ||
| are also supported. | ||
|
|
||
| 4. Task can be scheduled to run immediately when enabled if necessary | ||
| or wait for the interval to expire. | ||
|
|
||
| 5. A task can be restarted as it was defined or restarted with new | ||
| parameters, such as different interval, different callback function, | ||
| etc. | ||
|
|
||
| 6. Timing control of the scheduler can be governed by a Ticker | ||
| (TickTwo) class object or by a call to the Scheduler running in the | ||
| loop. | ||
|
|
||
| 7. Unlike TaskScheduler the processor does not sleep during idle time. | ||
| # TaskSched | ||
|
|
||
| ## Installation | ||
|
|
||
| *** | ||
| git clone https://github.com/AverageGuy/tasksched.git | ||
| *** | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Task Creation | ||
|
|
||
| - *Task(const voidFuncType &callBack, unsigned long interval=5000, bool enabled=false, unsigned long iterations=0, String name="Unk", bool runImmediate=false)* | ||
| ## Overview | ||
|
|
||
| - *callBack* is a function that will be called when the task has been enabled, the iteration count is still greater than zero and the interval has expired. | ||
|
|
||
| - *interval* is an unsigned long integer specifying the number of milliseconds between executions passes. | ||
|
|
||
| - *enabled* is a flag indicating the task should be placed in the run queue, if set to true. | ||
|
|
||
| - *iterations* is a long integer asking that the task should be run for only the passed value of iterations. If the value is zero then task should be run without a limit of iterations. | ||
|
|
||
| - *name* is a String value of a name of the task. | ||
|
|
||
| - *runImmediate* is a boolean flag that directs the scheduler to run the callback immediately rather than wait for the interval to expire. False says to wait for the interval to run the task. | ||
|
|
||
| - *Task(const voidFuncTypeWith &callBack, unsigned long interval=5000, bool enabled=false, unsigned long iterations=0, String name="Unk", bool runImmediate=false)* | ||
| TaskSched is a cooperative multitasking scheduler for Arduino processors, designed as a simpler alternative to existing schedulers like TaskScheduler. It provides a flexible and efficient way to manage multiple tasks in Arduino projects, particularly tested on ESP32 and ESP8266 processors. | ||
|
|
||
| - *callBack* is a function that will be called when the task has been enabled, the iteration count is still greater than zero and the interval has expired. It will be passed a reference to this Task object as the first parameter. | ||
|
|
||
| - *interval*, *enabled*, *iterations*, *name*, and *runImmediate* same as above. | ||
|
|
||
| There are two variations on the basic constructor, one that passes a reference to the object as the first parameter of the callback function and one that doesn't. | ||
| ## Contents | ||
|
|
||
| Note there are 6 other similar constructors that allow you to pass the interval | ||
| as one of *int*, *long*, or *double*. E.g. | ||
| - [Main Features](#main-features) | ||
| - [Installation](#installation) | ||
| - [Usage](#usage) | ||
| - [Creating Tasks](#creating-tasks) | ||
| - [Task Methods](#task-methods) | ||
| - [Scheduler](#scheduler) | ||
| - [Examples](#examples) | ||
| - [API Reference](#api-reference) | ||
| - [Issues](#issues) | ||
| - [Contributing](#contributing) | ||
|
|
||
| - *Task(const voidFuncType &callBack, int interval=5000, bool enabled=false, unsigned long iterations=0, String name="Unk", bool runImmediate=false)* | ||
| ## Main Features | ||
|
|
||
| ### Task Public Methods | ||
| 1. **Periodic task execution**: Tasks can be set to run at specified intervals, with times specified in milliseconds or seconds. | ||
| 2. **Task enable/disable support**: Tasks can be dynamically enabled or disabled. | ||
| 3. **Iteration control**: Tasks can be set to run for a specific number of iterations or indefinitely. | ||
| 4. **Immediate or delayed execution**: Tasks can be scheduled to run immediately when enabled or wait for the interval to expire. | ||
| 5. **Task restart and parameter modification**: Tasks can be restarted with original or new parameters (interval, callback function, etc.). | ||
| 6. **Flexible timing control**: The scheduler can be run periodically in the main loop. | ||
| 7. **Safe pointer implementation**: Uses `SafePtr` for improved memory management and safety. | ||
|
|
||
| - *bool isFirstIteration()* | ||
|
|
||
| - Returns true if this is the first iteration | ||
|
|
||
| - *bool isLastIteration()* | ||
|
|
||
| - Returns true if this is the last iteration | ||
|
|
||
| - *bool fRunImmediate(bool)* | ||
|
|
||
| - If passed a true value then the task will be run immediately as soon as the scheduler processes the task. It is intended to be run after a restart function call. | ||
|
|
||
| - *void restart()* | ||
| ## Installation | ||
|
|
||
| - Calling restart uses the values saved at task instantiation, but leaves the task disabled. If you wish to schedule the task you must call enable after the restart. If you need to change parameters such as iterations and interval, use the functions provided. The original saved parameters are not modified. | ||
|
|
||
| - *void enable()* | ||
| To install TaskSched, clone the repository: | ||
|
|
||
| - Enable the task. It will be run during the next iteration of the scheduler or after the interval is completed if fRunImmediate was not called with a true value. | ||
| - *void disable()* | ||
| ``` | ||
| git clone https://github.com/AverageGuy/tasksched.git | ||
| ``` | ||
|
|
||
| - Disable the task. If you disable a task while running and then enable it later, the iteration count is retained. That is, if the iteration count was originally 10 and it has completed 6 iterations when disable was called, then if you enable it at a later time, the task will complete 4 more iterations. | ||
|
|
||
| - *bool isEnabled()* | ||
| ## Usage | ||
|
|
||
| - Test to see if the task is enabled. Returns true if enabled. | ||
|
|
||
| - *void setCallback(const voidFuncType &)* | ||
| ### Creating Tasks | ||
|
|
||
| - Set a new function for the callback. This is best used after a reset but will work on an enabled task. The next iteration of the task will use the new callback. | ||
| Tasks are created using the `Task` constructor: | ||
|
|
||
| - *void runIt()* | ||
| ```cpp | ||
| SafePtr<Task> task = SafePtr<Task>(new Task(callback, interval, enabled, iterations, name, runImmediately)); | ||
| ``` | ||
|
|
||
| - This is the function the scheduler uses to schedule the task, if needed. It shouldn't be called by the user's program. | ||
|
|
||
| - *String getName()* | ||
| - `callback`: Function to be called (must accept a `Task*` parameter) | ||
| - `interval`: Time between calls (milliseconds if integer, seconds if float) | ||
| - `enabled`: Whether the task starts enabled | ||
| - `iterations`: Number of times to run (0 for infinite) | ||
| - `name`: Descriptive name for the task | ||
| - `runImmediately`: Whether to run immediately when enabled | ||
|
|
||
| - Return the name of the task in a String. | ||
|
|
||
| - *void showInit()* | ||
|
|
||
| - Prints the task name, interval, enabled flag, iterations. Probably only good for debugging. The name implies it would show the initial settings but it is actually showing the | ||
| current settings. | ||
|
|
||
| - *String formatMS(unsigned long milliseconds)* | ||
| ### Task Methods | ||
|
|
||
| - Returns a string with the time expressed in millisconds as MM:SS.ms e.g. 5:59.124 | ||
|
|
||
| - *void setInterval(unsigned long newInterval)* | ||
|
|
||
| - Sets the interval for this task to a new value. It takes effect when ever the scheduler runs again. | ||
|
|
||
| - *void setIterations(unsigned long newIterations)* | ||
| Key methods for managing tasks: | ||
|
|
||
| - Sets a new iteration count for this task. It takes effect when ever the scheduler runs again. If you use | ||
| this function to set iterations for a task that had exhausted its iteration count you need to | ||
| enable the task again. | ||
| - `enable()`: Enable the task | ||
| - `disable()`: Disable the task | ||
| - `restart()`: Restart the task with original parameters | ||
| - `setInterval(newInterval)`: Set a new interval | ||
| - `setIterations(newIterations)`: Set a new iteration count | ||
| - `isEnabled()`: Check if the task is enabled | ||
| - `isFirstIteration()`: Check if it's the first iteration | ||
| - `isLastIteration()`: Check if it's the last iteration | ||
|
|
||
| ### Scheduler | ||
|
|
||
| ### Sched Creation | ||
| The `Sched` class manages multiple tasks: | ||
|
|
||
| - *Sched()* | ||
| ```cpp | ||
| Sched scheduler; | ||
| scheduler.addTask(task); | ||
| scheduler.begin(); | ||
|
|
||
| ### Sched Public Methods | ||
| void loop() { | ||
| scheduler.run(); | ||
| } | ||
| ``` | ||
|
|
||
| - *unsigned long getSize()* | ||
| ## Examples | ||
|
|
||
| - Returns the length of the list of tasks, or how many tasks are being managed | ||
|
|
||
| - *String displayStatus(bool all=0, String taskName="")* | ||
|
|
||
| - Returns a String variable with statistics about scheduled tasks. If the first parameter is true then | ||
| the method returns all of the tasks in the schedule's list. If false then the method looks for a | ||
| task named in the second parameter. If not found it returns an empty string. | ||
|
|
||
| - Be very careful using this method if you have a large number of tasks or you are running this on | ||
| a device with limited memory. It utilizes a fixed length buffer of 1000 characters to collect the | ||
| report. Just be warned. It may not display all of the tasks since it senses a potential overrun | ||
| of the 1000 character buffer. | ||
|
|
||
| - *void begin()* | ||
| See the `examples/SkedBlink1/SkedBlink1.ino` file for a basic example of blinking an LED using TaskSched. | ||
|
|
||
| - This method must be called for the scheduler to run. It's usually run from a setup function. | ||
|
|
||
| - *void addTask(Task *task)* | ||
| ## API Reference | ||
|
|
||
| - This is used to add a task to the task list. | ||
|
|
||
| - *void enable()* | ||
| For detailed API documentation, please refer to the Doxygen-generated documentation in the `docs` folder. | ||
|
|
||
| - Used to enable the scheduler. Not normally needed unless the scheduler was disabled. | ||
|
|
||
| - *void disable()* | ||
| ## Issues | ||
|
|
||
| - Used to disable the scheduler. No tasks will be run while the scheduler is disabled. | ||
|
|
||
| - *int isEnabled()* | ||
| If you encounter any issues or have feature requests, please open an issue on the GitHub repository. | ||
|
|
||
| - Returns false if the scheduler has been disabled, else returns true. | ||
|
|
||
| - *void run()* | ||
| ## Contributing | ||
|
|
||
| - This method does the scheduling. It normally should be run periodically and is commonly placed | ||
| in the loop function. | ||
|
|
||
| - *const list<Task *>& getTasks() const* | ||
| Contributions to TaskSched are welcome. Please feel free to submit pull requests or open issues to discuss potential improvements. | ||
|
|
||
| - This method simply returns a pointer to the list of tasks being scheduled. |