|
1 | 1 | # Task |
2 | 2 |
|
| 3 | +[](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=6AA97KE54UJR4) |
| 4 | + |
3 | 5 | Arduino Nonpreemptive multitasking library |
4 | 6 |
|
5 | | -For the latest Arduino IDE, use the library manager to find and install "Task by Makuna" library. |
| 7 | +NOTE: Avoid the use of Delay in all high level code as the tasks timing should be used to replace it. |
6 | 8 |
|
7 | | -For older versions, you can just clone this into your Arduino\Library folder. |
| 9 | +For bugs, make sure there isn't an active issue and then create one. |
8 | 10 |
|
9 | | -For a good starting point at understanding the direction of this library, please read https://learn.adafruit.com/multi-tasking-the-arduino-part-1?view=all. |
10 | | -This library was not based on that work though, but they share common goals. |
| 11 | +For quick questions jump on Gitter and ask away. |
| 12 | +[](https://gitter.im/Makuna/Task?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) |
11 | 13 |
|
12 | | -NOTE: Avoid the use of Delay in all high level code as the tasks timing should be used to replace it. |
| 14 | +## Documentation |
| 15 | +[See Wiki](https://github.com/Makuna/Task/wiki) |
13 | 16 |
|
14 | | -## Installing This Library |
| 17 | +## Installing This Library (you just want to use it) |
15 | 18 | Open the Library Manager and search for "Task by Makuna" and install |
16 | 19 |
|
17 | | -## Installing This Library From GitHub |
| 20 | +## Installing This Library From GitHub (you want to contribute) |
18 | 21 | Create a directory in your Arduino\Library folder named "Task" |
19 | 22 | Clone (Git) this project into that folder. |
20 | 23 | It should now show up in the import list. |
21 | 24 |
|
22 | | -## TaskTime |
23 | | -### Conversion macros |
24 | | -The resolution of the task interval is based on millis() or micros(). The default is millis(). To allow the code to easily switch, callers should use the macros to wrap constants. |
25 | | - |
26 | | -``` |
27 | | -uint32_t taskTime = MsToTaskTime(400); // 400 ms |
28 | | -uint32_t timeMilliseconds = TaskTimeToMs(taskTime); |
29 | | -uint32_t timeMicroseconds = TaskTimeToUs(taskTime); |
30 | | -taskTime = UsToTaskTime(400000) // 4000000us, 400ms also |
31 | | -``` |
32 | | -This is important for passing in time interval when the task is created, and when handling the deltaTime parameter in the Update method. |
33 | | - |
34 | | -``` |
35 | | -FunctionTask taskTurnLedOn(OnUpdateTaskLedOn, MsToTaskTime(400)); 400ms |
36 | | -
|
37 | | -void OnUpdateTaskLedOn(uint32_t deltaTime) |
38 | | -{ |
39 | | - uint32_t deltaTimeMs = TaskTimeToMs(deltaTime); |
40 | | -} |
41 | | -``` |
42 | | -### Getting the current Update Time |
43 | | -If you call millis() or micros(), you will get the time as it is right then. If you want relative time from update to update, you can get this from the TaskManager. This value will change only on the update interval, and should only be used within an update call. |
44 | | -``` |
45 | | - uint32_t updateTaskTime = taskManager.CurrentTaskTime(); |
46 | | -``` |
47 | | - |
48 | | -### Using higher resolution time |
49 | | -To switch the library to use a higher resolution interval (microseconds), you need to edit the Task.h file in the library/Task folder and uncomment the following line. |
50 | | - |
51 | | -``` |
52 | | -//#define TASK_MICRO_RESOLUTION |
53 | | -``` |
54 | | -If you have used the macros mentioned above, your project should compile and run, but now at a higher resoltion. |
55 | | -By doing this, the longest time a task interval can be is just over 70 minutes. |
56 | | -TaskTime values will now be microseconds, but the time interval may still be larger as some Arduinos will give values that increment by 2, 4, or even 8. |
57 | | - |
58 | | -## Samples |
59 | | -### BlinkUsingTaskFunctions |
60 | | -This demonstrates the use of the FunctionTask feature of Task library. It will use two FunctionTasks to to blink a LED repeatedly, by alternating which task is active and flpping the state of the LED pin. |
61 | | -In this example, tasks are declared at the top and are associated with a function that will be run when the task gets called to update. |
62 | | - |
63 | | -``` |
64 | | -FunctionTask taskTurnLedOn(OnUpdateTaskLedOn, MsToTaskTime(400)); // turn on the led in 400ms |
65 | | -FunctionTask taskTurnLedOff(OnUpdateTaskLedOff, MsToTaskTime(600)); // turn off the led in 600ms |
66 | | -
|
67 | | -... |
68 | | -
|
69 | | -void OnUpdateTaskLedOn(uint32_t deltaTime) |
70 | | -{ |
71 | | - digitalWrite(ledPin, HIGH); // turn the LED on (HIGH is the voltage level) |
72 | | - taskManager.StopTask(&taskTurnLedOn); // stop trying to turn the LED On |
73 | | - taskManager.StartTask(&taskTurnLedOff); // start the task to turn the LED off |
74 | | -} |
75 | | -
|
76 | | -
|
77 | | -void OnUpdateTaskLedOff(uint32_t deltaTime) |
78 | | -{ |
79 | | - digitalWrite(ledPin, LOW); // turn the LED off by making the voltage LOW |
80 | | - taskManager.StopTask(&taskTurnLedOff); // stop trying to turn the LED Off |
81 | | - taskManager.StartTask(&taskTurnLedOn); // start the task to turn the LED On |
82 | | -} |
83 | | -``` |
84 | | -Then one of the tasks is started in the setup function. |
85 | | - |
86 | | -``` |
87 | | -void setup() |
88 | | -{ |
89 | | - pinMode(ledPin, OUTPUT); |
90 | | - |
91 | | - taskManager.StartTask(&taskTurnLedOn); // start with turning it on |
92 | | -} |
93 | | -``` |
94 | | -The tasks will continously toggle their running state handing off to the other to turn off and on the the led. |
95 | | - |
96 | | -### BlinkUsingTaskMacros |
97 | | -This demonstrates the use of the Task macros feature of Task library. It will use a custom tasks defined using the helper macros to to blink a LED repeatedly. |
98 | | -This is intended for intermediate level coders where more control is needed. This exposes to the developer the functions that are called when the task is started and stopped along with updated. |
99 | | -The custom task is defined in the taskBlinkLed.h tab. |
100 | | - |
101 | | -### BlinkUsingCustomTask |
102 | | -This demonstrates the use of the custom Task object feature of Task library. It will use a custom task to blink a LED repeatedly. |
103 | | -This is intended for advanced level coders where the most control is required and knowledge of C++ is understood. |
104 | | - |
105 | | -### ButtonTask |
106 | | -This demonstrates the use of the custom Task object feature of Task library. |
107 | | -It will instance two custom ButtonTasks to monitor two different pins and call back when they change state; with debouce and auto repeat support. |
108 | | - |
109 | | -This requires two momentary buttons attached to any io pins and ground. One button will turn on the on board led when it is pressed down, the other button turn off the on board led when it is released. Both will send usefull information to the serial monitor. |
110 | | -The custom task is defined in the ButtonTask.h tab. |
111 | | - |
112 | | -### ButtonInterrupt |
113 | | -This demonstrates the use of the Sleep feature of the Task library. |
114 | | -It will instance two custom ButtonTasks to monitor two different pins and call back when they change state; with debouce and auto repeat support. |
115 | | -An external interrupt is tied to the buttons to wake the Arduino up on any button press. |
116 | | -There are two tasks implementing a LED Blink showing a "heartbeat" that can only run when awake. |
117 | | -There is a task that will put the Arduino into a deep sleep 15 seconds after any button press. |
118 | | - |
119 | | -This requires two momentary buttons attached any io pins and ground. |
120 | | -This requires a diode per button be attached between the button pin and a single external interrupt pin. The cathode (black band) end of the diode is attached to the button pin; the anode to the interrupt pin. |
121 | | - |
122 | | -### MessageTask |
123 | | -This demonstrates the use of the message passing feature of Task library. |
124 | | -It will instance two custom ButtonTasks to monitor two different pins and they will send messages when they change state. It will also have tasks that provide a heartbeat message. |
125 | | - |
126 | | -This requires two momentary buttons attached between pins 4 & 5 and ground, you can change the pins to any digital pin |
127 | | - |
128 | | -### RotaryEncoder |
129 | | -This demonstrates creating a task to manage the details of rotary encoder. The task will track a value and increment and decrement it when the encoder is rotated. It will also provide a callback so the application can respond. Further, it provides a debounced button callback for the encoder press feature. |
130 | | - |
131 | | -This requires a common rotary encoder be connected to available pins. |
132 | | - |
133 | | -## Sleep Modes (advanced feature) |
134 | | -If you want to have your project to deep sleep and use less power, you can call the EnterSleep method and pass in a sleep modes as defined in Arduino header sleep.h. The default is SLEEP_MODE_PWR_DOWN if you dont provide one. |
135 | | -The processor will be placed into the given sleep mode until it is woke up. Different sleep modes have different actions that can cause it to wake. But external interrupts will wake up the Arduino for all sleep modes. |
136 | | - |
137 | | -``` |
138 | | - Serial.println("sleep"); |
139 | | - Serial.flush(); // flush is important, we are about to sleep the complete Arduino |
140 | | -
|
141 | | - taskManager.EnterSleep(); // this will not return until something wakes the Arduino |
142 | | -
|
143 | | - Serial.println("AWAKE"); |
144 | | - Serial.flush(); |
145 | | -``` |
146 | | - |
147 | | -## WatchDog Timer is enabled |
148 | | -This library will turn on the watchdog timer and by default set it too 500ms. If any single function takes longer than 500ms, the Arduino will reset and start over. |
149 | | -This is usefull where a bug in the code may cause an intermittant hang. But it requires that the developer make sure to use the Tasks to keep a single function to a small atomic piece of work. |
150 | | -The length of the WatchDog Timer can be changed by passing in one of the flags defined in wdt.h for the supported timer lengths to the loop method. |
151 | | - |
152 | | -``` |
153 | | -void loop() |
154 | | -{ |
155 | | - taskManager.Loop(WDTO_1S); // use one second watch dog timer |
156 | | -} |
157 | | -``` |
158 | | - |
159 | | -## Multiple Tasks are no problem |
160 | | -While the samples show simple examples, the limit to the number of tasks is based on memory and the time spent in the active update calls. |
161 | | -You can have one task blinking an LED, while another task samples a analog in and sets PWM output. Just keep the work inside each update call to the minimum needed for that time period and set the time cycle on the task to an appropriet value. |
| 25 | +## Documentation |
| 26 | +[See Wiki](https://github.com/Makuna/Task/wiki) |
0 commit comments