From c958d41f18bd38005d5006ac8010d600b4593523 Mon Sep 17 00:00:00 2001 From: Google Code Exporter Date: Fri, 17 Apr 2015 04:10:08 -0400 Subject: [PATCH 01/14] Migrating wiki contents from Google Code --- ChangeLog.md | 15 ++++ FAQ.md | 26 ++++++ Features.md | 201 +++++++++++++++++++++++++++++++++++++++++++++ ProjectHome.md | 16 ++++ QuickStartGuide.md | 59 +++++++++++++ SoftTimer.md | 17 ++++ WhyHow.md | 37 +++++++++ 7 files changed, 371 insertions(+) create mode 100644 ChangeLog.md create mode 100644 FAQ.md create mode 100644 Features.md create mode 100644 ProjectHome.md create mode 100644 QuickStartGuide.md create mode 100644 SoftTimer.md create mode 100644 WhyHow.md diff --git a/ChangeLog.md b/ChangeLog.md new file mode 100644 index 0000000..85dcade --- /dev/null +++ b/ChangeLog.md @@ -0,0 +1,15 @@ +# Changelog # + +## v2.0 ## + + * IMPORTANT MODIFICATION: SoftTimer was moved to **microsecond** basis. For most users this means that you can not register tasks with period greater than one hour! + * Dimer task was added. + * FrequencyTask was added. + +## v1.1 ## + + * An ugly bug was found: In some cases task was stopped when timer was overflown. + +## v1.0 ## + + * Initial release. \ No newline at end of file diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..4b45608 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,26 @@ +# Frequently Asked Questions about SoftTimer # + +### I'm new to C++ programming. Can you recommend me SoftTimer? ### + +If you just want to start periodic jobs, you can do that easily with SoftTimer. Also take a look at the provided tools (e.g. blinker, debouncer), as they are also easy to use. See example codes! + +Writing your own Task implementation needs C++ knowledge. The C++ has a quite ugly syntax to define classes, that is hard to understand for beginners. But you can always use my implementations (like the [BlinkTask.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/BlinkTask.h), [BlinkTask.cpp](http://code.google.com/p/arduino-softtimer/source/browse/trunk/BlinkTask.cpp)) as a template. + + +### Can I change the period of a Task? ### + +Sure you can do that. Please take a look at the Task.h interface documentation: +[Task.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Task.h) + +So you can set the period with "setPeriodMs()" any time. + + +### Do I need to remove/add my Task after changing the period? ### + +You do not need to do that, but calling the setPeriodMs() will not reset the existing state of the task. +I you have the restart the counting of the timer while changing the period, you need to do it by either setting the lastCallTimeMicros property of the task, or remove/add your task again. + + +### I have a question, where should I post it? ### + +You can reach me in prampec+softtimer@gmail.com address. \ No newline at end of file diff --git a/Features.md b/Features.md new file mode 100644 index 0000000..7db9b4b --- /dev/null +++ b/Features.md @@ -0,0 +1,201 @@ +# Detailed description of the provided features # + + +## [BlinkTask](http://code.google.com/p/arduino-softtimer/source/browse/trunk/BlinkTask.h) ## + + +Every physical computing project starts with a blinking of a led. +You often need to have an indicator that shows the state of your program. + +BlinkTask works in two mode: + * Perpetual mode - Blinks forever. + * Count mode - Blinks for an amount of occasion. + +Perpetual mode has two kinds: + * On-Off repetition - Repeat on and off states. + * After a count of "on" times suspend for some time. + +BlinkTask can work with on level of HIGH (default) or LOW. + +Use start() function to register the task in the Timer Manager, so start blinking. See [BlinkTask.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/BlinkTask.h) header file for details. + +``` +#include +#include + +#define LED_PIN 13 + +// -- On for 200ms off for 100ms, repeat it 2 times, sleep for 2000 ms and than start again. +BlinkTask heartbeat(LED_PIN, 200, 100, 2, 2000); + +void setup() { + heartbeat.start(); +} +``` + + + +## [TonePlayer](http://code.google.com/p/arduino-softtimer/source/browse/trunk/TonePlayer.h) ## + + +Tone player plays a melody on a specified output pin using the tone() and noTone() Arduino functions. You can specify the melody in quite tricky way, see [TonePlayer.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/TonePlayer.h) header file for details. + +``` +#include +#include + +#define BEEPER_PIN 10 + +TonePlayer tonePlayer(BEEPER_PIN, 200); // -- Tone manager + +void setup(void) +{ + tonePlayer.play("c1g1c1g1j2j2c1g1c1g1j2j2o1n1l1j1h2l2_2j1h1g1e1c2c2"); +} +``` + +Note, that you must take care to wait for the melody to finish before playing the next melody. Otherwise the next play will abort the previous melody. You may find the DelayRun task interesting. + + + +## [SoftPwmTask](http://code.google.com/p/arduino-softtimer/source/browse/trunk/SoftPwmTask.h) ## + +With this task you can add PWM functionality for pins that did not have hardware PWM. See [SoftPwmTask.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/SoftPwmTask.h) header file for details. + +``` +#include +#include + +#define OUT_PIN 13 + +// -- Set up PWM to the out pin. +SoftPwmTask pwm(OUT_PIN); + +void setup(void) +{ + // -- Register the task in the timer manager. + SoftTimer.add(&pwm); + + // -- Writes a value of 128. That means output will "dimmed" half way. + pwm.analogWrite(128); +} +``` + + +## [DelayRun](http://code.google.com/p/arduino-softtimer/source/browse/trunk/DelayRun.h) ## + +This class is to launch something after an amount of period. You can even specify a "followedBy" task, which will be run after this one has finished. See [DelayRun.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/DelayRun.h) header file for details. + +``` +#include +#include + +#define OUT_PIN 13 + +// -- This task will turn off the LED after 1 second. +DelayRun offTask(1000, turnOff); +// -- This task will turn on the LED after 2 seconds. +// -- After the onTask we loop the offTask. +DelayRun onTask(2000, turnOn, &offTask); + + +void setup() { + // -- We close the loop, so after offTask the onTask will start. + offTask.followedBy = &onTask; + + pinMode(OUT_PIN, OUTPUT); + + // -- Turn on the LED; + digitalWrite(OUT_PIN, HIGH); + + // -- Start the offTask to take effect after 1 second. + offTask.startDelayed(); + +} + +boolean turnOff(Task* task) { + digitalWrite(OUT_PIN, LOW); + return true; // -- Return true to enable the "followedBy" task. +} +boolean turnOn(Task* task) { + digitalWrite(OUT_PIN, HIGH); + return true; // -- Return true to enable the "followedBy" task. +} + +``` + + + +## [Debouncer](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Debouncer.h) ## + + +The debouncer task recommends to use the PciManager to manage the pin change interrupts. However you may handle interrupts manually. +After creating the debouncer task, you do not need to register it to the Timer Manager. + +If you are using the PciManager, you only have to register the debouncer to the PciManager. + +If you would like to handle PCI manually, you need make the pciHandleInterrupt() function to be called on pin change. + +Debouncer will call your "onPressed" callback function when the button has a sable pressed state, and the "onReleased" on the end of the press. The "onReleased" callback also receive the total time passed on the pressing state. + +You can use this debouncer both on Normally Opened and on Normally Closed circuits. + +See [Debouncer.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Debouncer.h) header file for details. + +``` +// -- Pin change interrupt +#include +#include +#include + +#define INPUT_PIN 3 + +Debouncer debouncer(INPUT_PIN, MODE_CLOSE_ON_PUSH, onPressed, onReleased); + + +void setup() { + Serial.begin(9800); + PciManager.registerListener(INPUT_PIN, &debouncer); + Serial.println("Ready."); +} + +void onPressed() { + Serial.println("pressed"); +} +void onReleased(unsigned long pressTimespanMs) { + Serial.print("Released after (Ms): "); + Serial.println(pressTimespanMs); +} +``` + + + + + +## [Heartbeat](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Heartbeat.h) ## + + +Heartbeat is a special blinker. It is intended to use a visual indicator for your project more easy. + +Heartbeat creates a custom timed BlinkTask and starts is immediately. + +See [Heartbeat.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Heartbeat.h) header file for details. + + + + +## [Dimmer](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Dimmer.h) ## + + +With the dimmer you can easily adjust the PWM level of an output. The dimming is done in linear scale. Dimmer has some neat options, like hold/continue dimming, or revert direction any time. You can also set it up to be automatically stopped when limit (totally on/totally off) reached. + +See [Dimmer.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Dimmer.h) header file for details. + + + +## [FrequencyTask](http://code.google.com/p/arduino-softtimer/source/browse/trunk/FrequencyTask.h) ## + + +Frequency task is just to play with the possibilities of the SoftTimer library. With the FrequencyTask you can generate square wave frequencies. + +See [FrequencyTask.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/FrequencyTask.h) header file for details. \ No newline at end of file diff --git a/ProjectHome.md b/ProjectHome.md new file mode 100644 index 0000000..9300c09 --- /dev/null +++ b/ProjectHome.md @@ -0,0 +1,16 @@ +SoftTimer enable a higher level Arduino programing, jet easy to use, and lightweight. +You often face with the problem that you need to do multiply tasks in the same time. In SoftTimer manner programmer creates Tasks that runs periodically. + +When you use SoftTimer you do not implement the "loop" function of the Arduino. All your code will run event driven, all processes running asynchronous, no more blocking code (like delay()) is needed. + +I also try to add some usefully tools to use SoftTimer out of the box (like blinker, pwm, debouncer, etc.) + +Debouncer class requires the PciManager library. + +# Documentation content # + + * [Quick-start guide](QuickStartGuide.md) + * [Why use SoftTimer and how does it work? ](WhyHow.md) + * [Detailed description of the provided features.](Features.md) + * [FAQ](FAQ.md) + * [ChangeLog](ChangeLog.md) \ No newline at end of file diff --git a/QuickStartGuide.md b/QuickStartGuide.md new file mode 100644 index 0000000..f27adde --- /dev/null +++ b/QuickStartGuide.md @@ -0,0 +1,59 @@ +# Quick-Start guide # + +1. Include SoftTimer in your program. +``` +#include +``` + +2. You need to create a Task with parameters of period (ms) and the callback function. E.g. callBack1 is to be called in every 2000 milliseconds (that is 2 seconds): +``` +Task t1(2000, callBack1); + +void callBack1(Task* me) { + // -- my code comes here +} +``` + +3. Register your task to the SoftTimer (Timer Manager). +``` +void setup() { + SoftTimer.add(&t1); +} +``` + +4. You are finished. You may add more tasks, or use some bundled task implementations. + +Full code: +``` +#include + +// -- taskOn will be launched on every 2 seconds. +Task taskOn(2000, turnOn); +// -- taskOff will be launched on every 1111 milliseconds. +Task taskOff(1111, turnOff); + +void setup() { + // -- Mark pin 13 as an output pin. + pinMode(13, OUTPUT); + + // -- Register the tasks to the timer manager. Both tasks will start immediately. + SoftTimer.add(&taskOn); + SoftTimer.add(&taskOff); +} + +/** + * Turn ON Arduino's LED on pin 13. + */ +void turnOn(Task* me) { + digitalWrite(13, HIGH); +} + +/** + * Turn OFF Arduino's LED on pin 13. + */ +void turnOff(Task* me) { + digitalWrite(13, LOW); +} +``` + +Note, that the "loop()" method is absent form this full code. This is intended to be so! \ No newline at end of file diff --git a/SoftTimer.md b/SoftTimer.md new file mode 100644 index 0000000..0e124db --- /dev/null +++ b/SoftTimer.md @@ -0,0 +1,17 @@ +# Introduction # + +SoftTimer is an Arduino library. + +SoftTimer enable a higher level Arduino programing, jet easy to use, and lightweight. +You often face with the problem that you need to do multiply task in the same time. In SoftTimer manner programmer creates Tasks that runs periodically. + +When you use SoftTimer you do not implement the "loop" function of the Arduino. All your code will run event driven, all processes running asynchronous, no more blocking code (like sleep) is needed. + +I also try to add some usefully tools to use SoftTimer out of the box (like blinker, pwm, debouncer, etc.) + + + +# Documentation content # + * [Quick-start guide](QuickStartGuide.md) + * [Why use SoftTimer and how does it work? ](WhyHow.md) + * [Detailed description of the provided features.](Features.md) \ No newline at end of file diff --git a/WhyHow.md b/WhyHow.md new file mode 100644 index 0000000..a800032 --- /dev/null +++ b/WhyHow.md @@ -0,0 +1,37 @@ +# Why use SoftTimer? # + +You can add multitasking like functionalities for your code. For example you can blink a led while waiting for an input, or generate warning tones that does not block the running. +If you are facing with a more complex problem, you can organize your code in program tasks. You do not have to care about the timing of these tasks, while the Task Manager does this job for you. This way you can create simplified codes, that is easy to manage. + +SoftTimer is a well designed object oriented solution, it is fun to work with. + +SoftTimer has a small footprint, so using it will not mean a big memory penalty. + + + +# How does it work? # + + +SoftTimer class is a Timer Manager that constantly scans the registered task if it is time to run it. If so (launch start time is passed) the callback is launched. No matter how long the callback is running, the next run will be scheduled according to the previous start time. The period of starting is defined at the Task. The period of the task may be changed if necessary. + +Note that SoftTimer does not run tasks in the same time. The next task can be run after the currently running task is finished. When a callback runs longer than its period, the timing may fail. The tasks will be checked for run in the order of registration. You can register multiply tasks with a period of zero (0), the tasks will run after each other. +If you add only one task with a period value zero (0) it will act like original Arduino setup-loop methods. + +``` +#include + +Task t1(0, myLoop); + +void setup() { + SoftTimer.add(&t1); + // -- Put your setup code here, to run once. +} + +void myLoop(Task* me) { + // -- Put your main code here, to run repeatedly. +} +``` + +You can register (add) or remove tasks any time. + +Note that SoftTimer (from v2.0) works on **microsecond** basis. This means, you can not register task with period more than an hour! \ No newline at end of file From aac3d7a241bbc2e26a9e6bf2692d661859f4c42e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Thu, 25 Jun 2015 17:53:36 +0200 Subject: [PATCH 02/14] Update SoftTimer.md --- SoftTimer.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/SoftTimer.md b/SoftTimer.md index 0e124db..ce5b9b9 100644 --- a/SoftTimer.md +++ b/SoftTimer.md @@ -9,9 +9,10 @@ When you use SoftTimer you do not implement the "loop" function of the Arduino. I also try to add some usefully tools to use SoftTimer out of the box (like blinker, pwm, debouncer, etc.) +You can download the actual version from the [Releases page].(https://github.com/prampec/arduino-softtimer/releases) # Documentation content # * [Quick-start guide](QuickStartGuide.md) * [Why use SoftTimer and how does it work? ](WhyHow.md) - * [Detailed description of the provided features.](Features.md) \ No newline at end of file + * [Detailed description of the provided features.](Features.md) From c870eb8a8f60f03576cd57d3cf72dd48f071f723 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Thu, 25 Jun 2015 17:54:12 +0200 Subject: [PATCH 03/14] Update SoftTimer.md --- SoftTimer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SoftTimer.md b/SoftTimer.md index ce5b9b9..029b4d1 100644 --- a/SoftTimer.md +++ b/SoftTimer.md @@ -9,7 +9,7 @@ When you use SoftTimer you do not implement the "loop" function of the Arduino. I also try to add some usefully tools to use SoftTimer out of the box (like blinker, pwm, debouncer, etc.) -You can download the actual version from the [Releases page].(https://github.com/prampec/arduino-softtimer/releases) +You can download the actual version from the [Releases page](https://github.com/prampec/arduino-softtimer/releases). # Documentation content # From 11d85cd7232dffb99ed72f7daa6d0de0c541046c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Mon, 26 Oct 2015 23:28:39 +0100 Subject: [PATCH 04/14] Rotary encoder driver added. --- Features.md | 40 ++++++++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 16 deletions(-) diff --git a/Features.md b/Features.md index 7db9b4b..19853cb 100644 --- a/Features.md +++ b/Features.md @@ -1,7 +1,7 @@ # Detailed description of the provided features # -## [BlinkTask](http://code.google.com/p/arduino-softtimer/source/browse/trunk/BlinkTask.h) ## +## [BlinkTask](https://github.com/prampec/arduino-softtimer/blob/master/src/BlinkTask.h) ## Every physical computing project starts with a blinking of a led. @@ -17,7 +17,7 @@ Perpetual mode has two kinds: BlinkTask can work with on level of HIGH (default) or LOW. -Use start() function to register the task in the Timer Manager, so start blinking. See [BlinkTask.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/BlinkTask.h) header file for details. +Use start() function to register the task in the Timer Manager, so start blinking. See [BlinkTask.h](https://github.com/prampec/arduino-softtimer/blob/master/src/BlinkTask.h) header file for details. ``` #include @@ -35,10 +35,10 @@ void setup() { -## [TonePlayer](http://code.google.com/p/arduino-softtimer/source/browse/trunk/TonePlayer.h) ## +## [TonePlayer](https://github.com/prampec/arduino-softtimer/blob/master/src/TonePlayer.h) ## -Tone player plays a melody on a specified output pin using the tone() and noTone() Arduino functions. You can specify the melody in quite tricky way, see [TonePlayer.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/TonePlayer.h) header file for details. +Tone player plays a melody on a specified output pin using the tone() and noTone() Arduino functions. You can specify the melody in quite tricky way, see [TonePlayer.h](https://github.com/prampec/arduino-softtimer/blob/master/src/TonePlayer.h) header file for details. ``` #include @@ -58,9 +58,9 @@ Note, that you must take care to wait for the melody to finish before playing th -## [SoftPwmTask](http://code.google.com/p/arduino-softtimer/source/browse/trunk/SoftPwmTask.h) ## +## [SoftPwmTask](https://github.com/prampec/arduino-softtimer/blob/master/src/SoftPwmTask.h) ## -With this task you can add PWM functionality for pins that did not have hardware PWM. See [SoftPwmTask.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/SoftPwmTask.h) header file for details. +With this task you can add PWM functionality for pins that did not have hardware PWM. See [SoftPwmTask.h](https://github.com/prampec/arduino-softtimer/blob/master/src/SoftPwmTask.h) header file for details. ``` #include @@ -82,9 +82,9 @@ void setup(void) ``` -## [DelayRun](http://code.google.com/p/arduino-softtimer/source/browse/trunk/DelayRun.h) ## +## [DelayRun](https://github.com/prampec/arduino-softtimer/blob/master/src/DelayRun.h) ## -This class is to launch something after an amount of period. You can even specify a "followedBy" task, which will be run after this one has finished. See [DelayRun.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/DelayRun.h) header file for details. +This class is to launch something after an amount of period. You can even specify a "followedBy" task, which will be run after this one has finished. See [DelayRun.h](https://github.com/prampec/arduino-softtimer/blob/master/src/DelayRun.h) header file for details. ``` #include @@ -126,7 +126,7 @@ boolean turnOn(Task* task) { -## [Debouncer](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Debouncer.h) ## +## [Debouncer](https://github.com/prampec/arduino-softtimer/blob/master/src/Debouncer.h) ## The debouncer task recommends to use the PciManager to manage the pin change interrupts. However you may handle interrupts manually. @@ -140,7 +140,7 @@ Debouncer will call your "onPressed" callback function when the button has a sab You can use this debouncer both on Normally Opened and on Normally Closed circuits. -See [Debouncer.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Debouncer.h) header file for details. +See [Debouncer.h](https://github.com/prampec/arduino-softtimer/blob/master/src/Debouncer.h) header file for details. ``` // -- Pin change interrupt @@ -170,32 +170,40 @@ void onReleased(unsigned long pressTimespanMs) { +## [Rotary](https://github.com/prampec/arduino-softtimer/blob/master/src/Rotary.h) ## -## [Heartbeat](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Heartbeat.h) ## +Rotary is a rotary encoder driver managed by SoftTimer. + +See [Rotary.h](https://github.com/prampec/arduino-softtimer/blob/master/src/Rotary.h) header file for details. + + + + +## [Heartbeat](https://github.com/prampec/arduino-softtimer/blob/master/src/Heartbeat.h) ## Heartbeat is a special blinker. It is intended to use a visual indicator for your project more easy. Heartbeat creates a custom timed BlinkTask and starts is immediately. -See [Heartbeat.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Heartbeat.h) header file for details. +See [Heartbeat.h](https://github.com/prampec/arduino-softtimer/blob/master/src/Heartbeat.h) header file for details. -## [Dimmer](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Dimmer.h) ## +## [Dimmer](https://github.com/prampec/arduino-softtimer/blob/master/src/Dimmer.h) ## With the dimmer you can easily adjust the PWM level of an output. The dimming is done in linear scale. Dimmer has some neat options, like hold/continue dimming, or revert direction any time. You can also set it up to be automatically stopped when limit (totally on/totally off) reached. -See [Dimmer.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/Dimmer.h) header file for details. +See [Dimmer.h](https://github.com/prampec/arduino-softtimer/blob/master/src/Dimmer.h) header file for details. -## [FrequencyTask](http://code.google.com/p/arduino-softtimer/source/browse/trunk/FrequencyTask.h) ## +## [FrequencyTask](https://github.com/prampec/arduino-softtimer/blob/master/src/FrequencyTask.h) ## Frequency task is just to play with the possibilities of the SoftTimer library. With the FrequencyTask you can generate square wave frequencies. -See [FrequencyTask.h](http://code.google.com/p/arduino-softtimer/source/browse/trunk/FrequencyTask.h) header file for details. \ No newline at end of file +See [FrequencyTask.h](https://github.com/prampec/arduino-softtimer/blob/master/src/FrequencyTask.h) header file for details. From 878aebf2c2530594e6f9376ec2d092ac33de2c30 Mon Sep 17 00:00:00 2001 From: Aron Magyari Date: Mon, 16 Nov 2015 13:40:48 -0800 Subject: [PATCH 05/14] Improved Description --- SoftTimer.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/SoftTimer.md b/SoftTimer.md index 029b4d1..e319b7f 100644 --- a/SoftTimer.md +++ b/SoftTimer.md @@ -2,12 +2,12 @@ SoftTimer is an Arduino library. -SoftTimer enable a higher level Arduino programing, jet easy to use, and lightweight. -You often face with the problem that you need to do multiply task in the same time. In SoftTimer manner programmer creates Tasks that runs periodically. +SoftTimer enables a higher level Arduino programing, while its lightweight and easy to use. +The programmer is often faced with the problem that he/she needs to run multiple tasks at the same time. With SoftTimer, the programmer is able create Tasks that run periodically. -When you use SoftTimer you do not implement the "loop" function of the Arduino. All your code will run event driven, all processes running asynchronous, no more blocking code (like sleep) is needed. +With SoftTimer, one does not implement the "loop" function of the Arduino. Instead, all code will be event driven, all processes running asynchronously, eliminating the need for any blocking code (like sleep). -I also try to add some usefully tools to use SoftTimer out of the box (like blinker, pwm, debouncer, etc.) +Some useful tools are also included with SoftTimer out of the box (like blinker, pwm, debouncer, etc.) You can download the actual version from the [Releases page](https://github.com/prampec/arduino-softtimer/releases). From 1ff089b94bd5ac644a9beb6b3255b1e40b7498c4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Sun, 13 Mar 2016 21:58:19 +0100 Subject: [PATCH 06/14] Update QuickStartGuide.md --- QuickStartGuide.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/QuickStartGuide.md b/QuickStartGuide.md index f27adde..dd84dac 100644 --- a/QuickStartGuide.md +++ b/QuickStartGuide.md @@ -1,11 +1,11 @@ # Quick-Start guide # -1. Include SoftTimer in your program. +##### 1. Include SoftTimer in your program. ``` #include ``` -2. You need to create a Task with parameters of period (ms) and the callback function. E.g. callBack1 is to be called in every 2000 milliseconds (that is 2 seconds): +##### 2. You need to create a Task with parameters of period (ms) and the callback function. E.g. callBack1 is to be called in every 2000 milliseconds (that is 2 seconds): ``` Task t1(2000, callBack1); @@ -14,14 +14,14 @@ void callBack1(Task* me) { } ``` -3. Register your task to the SoftTimer (Timer Manager). +##### 3. Register your task to the SoftTimer (Timer Manager). ``` void setup() { SoftTimer.add(&t1); } ``` -4. You are finished. You may add more tasks, or use some bundled task implementations. +##### 4. You are finished. You may add more tasks, or use some bundled task implementations. Full code: ``` @@ -56,4 +56,4 @@ void turnOff(Task* me) { } ``` -Note, that the "loop()" method is absent form this full code. This is intended to be so! \ No newline at end of file +Note, that the "loop()" method is absent form this full code. This is intended to be so! From 2f8871b568c384b134a6adaaec289d92d4a93db0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Fri, 9 Sep 2016 22:51:46 +0200 Subject: [PATCH 07/14] Update WhyHow.md --- WhyHow.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/WhyHow.md b/WhyHow.md index a800032..d4f291f 100644 --- a/WhyHow.md +++ b/WhyHow.md @@ -32,6 +32,6 @@ void myLoop(Task* me) { } ``` -You can register (add) or remove tasks any time. +You can register (add) or remove tasks any time, and of course you can tune the timings later on. -Note that SoftTimer (from v2.0) works on **microsecond** basis. This means, you can not register task with period more than an hour! \ No newline at end of file +Note that SoftTimer (from v2.0) works on **microsecond** basis. This means, you can not register task with period more than an hour! From 7a8165b5f2c6c9b90aa6bb92c0679c7fbfc1a6da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Sat, 10 Sep 2016 07:39:42 +0200 Subject: [PATCH 08/14] Update Features.md --- Features.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Features.md b/Features.md index 19853cb..d94dcac 100644 --- a/Features.md +++ b/Features.md @@ -1,5 +1,28 @@ # Detailed description of the provided features # +If you want to have detailed documentation it is always a good idea to browse the code for comments. Aspecially suggested to read the header files, where you will find all the available features well documented. + +Here you will find some key features of the software explained. + + +## [Task](https://github.com/prampec/arduino-softtimer/blob/master/src/Task.h) ## + + +Task is the basic building block of SoftTimer. A task defines a timing and a job. To be more precise, you need to specify the time of calling period, and the callback function to be called. + +The basic idea here, is that you will create a job in a callback method, that will be called each time the specified time was passed. Of course you always have the possibility to remove the Task from the timer manager in the job with `SoftTimer.remove(task)`, e.g. in case it is only need to be called once. + +Please take a look at the [Task.h](https://github.com/prampec/arduino-softtimer/blob/master/src/Task.h). You can see the constructor reflects the words above: you need to specify a timing period in milliseconds, and the callback function. + +You can also see in the header file, that the period can be changed later with `setPeriodMs(periodInMilliseconds)`. Further more, the period is stored in microseconds basis in a public property, that you are free to adjust. + +> In the task a nowMicros property also provided. The idea for this is that the timer manager already needs to check for the current microseconds, and your job might also interested in the current time. Checking the microseconds two times is a waste of cpu-cycles, so you can have it in this property for your own use. + +The time of the last calling occurrence also stored in a public property. You must understand, that the timer manager will call your job, when the **lastCallTimeMicros** plus the **periodMicros** is passed (added value is less than the actual time). Advanced developers might want to tweak the system by modifying the lastCallTimeMicros of a job (e.g. reset a countdown timer). + + > When you are about to use the SoftTimer module. You will find yourself, that you will like to write proper C++ code. The way to achieve this, is to inherit from the Task class, and define your job logic in this class. Separated from other logic and reusable. The following part of this documentation contains good example for that: all of these features are inherits Task. You might want to follow them as templates. +**Note**: Arduino does not let you to pass class member methods, as function pointer. You always need to have a static function to act as a callback. This is why the Task is always passed to the callback method as parameter. + ## [BlinkTask](https://github.com/prampec/arduino-softtimer/blob/master/src/BlinkTask.h) ## From 387daba01bec2797809acfe9a7d159b832a07a97 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Mon, 26 Jun 2017 10:25:52 +0200 Subject: [PATCH 09/14] Update SoftTimer.md --- SoftTimer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SoftTimer.md b/SoftTimer.md index e319b7f..c8d69fb 100644 --- a/SoftTimer.md +++ b/SoftTimer.md @@ -9,7 +9,7 @@ With SoftTimer, one does not implement the "loop" function of the Arduino. Inste Some useful tools are also included with SoftTimer out of the box (like blinker, pwm, debouncer, etc.) -You can download the actual version from the [Releases page](https://github.com/prampec/arduino-softtimer/releases). +You can download the actual version directly from the Arduino IDE, or from the [Releases page](https://github.com/prampec/arduino-softtimer/releases). # Documentation content # From f1eb611a20383f8d4c7c0d17ffe519f29f0ba66b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Mon, 26 Jun 2017 10:38:02 +0200 Subject: [PATCH 10/14] Update WhyHow.md --- WhyHow.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/WhyHow.md b/WhyHow.md index d4f291f..487191a 100644 --- a/WhyHow.md +++ b/WhyHow.md @@ -35,3 +35,25 @@ void myLoop(Task* me) { You can register (add) or remove tasks any time, and of course you can tune the timings later on. Note that SoftTimer (from v2.0) works on **microsecond** basis. This means, you can not register task with period more than an hour! + + +# Platform dependent notes # + +As SoftTimer eliminates the use of the "loop()" function, on platforms, that has an internal watchdog (like the ESP8266) you need to "feed" the watchdog manually to prevent resets. (Or just disable the watchdog.) +You can feed the watchdog with a task, e.g.: +```c +#include + +// -- Define method signature. +void feedWatchdog(Task* me); + +Task watchdogFeederTask(100, feedWatchdog); + +void setup() { + SoftTimer.add(&watchdogFeederTask); +} + +void feedWatchdog(Task* me) { + ESP.wdtFeed(); +} +``` From f1003c167127c9b39ae95d30d82f1f7ffc6b6651 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Mon, 28 Aug 2017 21:05:38 +0200 Subject: [PATCH 11/14] Update WhyHow.md --- WhyHow.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/WhyHow.md b/WhyHow.md index 487191a..f54f669 100644 --- a/WhyHow.md +++ b/WhyHow.md @@ -37,6 +37,14 @@ You can register (add) or remove tasks any time, and of course you can tune the Note that SoftTimer (from v2.0) works on **microsecond** basis. This means, you can not register task with period more than an hour! +# Options # + +In SoftTimer.h there are some options provided. You include/exclude some macro defines to enable/disable those options. + +* __PREVENT_LOOP_ITERATION__ - With preventing loop() iteration you will benefit some milliseconds. On the other hand some platforms might depend on the loop(). If you are facing with strange behaviour, you might want to try disabling the PREVENT_LOOP_ITERATION option. PREVENT_LOOP_ITERATION is enabled by default. +* __STRICT_TIMING__ - By default the next start of a task scheduled from the begining of the previous execution. But executions might shift if an other task does not finish in time. With STRICT_TIMING the next execution is scheduled for the expected time. STRICT_TIMING is disabled by default, as it might likely to cause starvation in the Tasks. + + # Platform dependent notes # As SoftTimer eliminates the use of the "loop()" function, on platforms, that has an internal watchdog (like the ESP8266) you need to "feed" the watchdog manually to prevent resets. (Or just disable the watchdog.) From 3b8f7a5cec69cbd9909bff8815ee4c2478db275a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Mon, 28 Aug 2017 21:23:29 +0200 Subject: [PATCH 12/14] Update WhyHow.md --- WhyHow.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/WhyHow.md b/WhyHow.md index f54f669..b343d2a 100644 --- a/WhyHow.md +++ b/WhyHow.md @@ -47,7 +47,10 @@ In SoftTimer.h there are some options provided. You include/exclude some macro d # Platform dependent notes # -As SoftTimer eliminates the use of the "loop()" function, on platforms, that has an internal watchdog (like the ESP8266) you need to "feed" the watchdog manually to prevent resets. (Or just disable the watchdog.) +As SoftTimer eliminates the use of the "loop()" function, on platforms, that has some extra processing in every loop cicle, some troubles might appear. +As a workaround a PREVENT_LOOP_ITERATION option is introduced. (See Options above!) + +For example, the internal watchdog in ESP8266 is feed by the system in every loop cycle, so if you do not disable the PREVENT_LOOP_ITERATION option, you need to "feed" the watchdog manually to prevent resets. (Or just disable the watchdog.) You can feed the watchdog with a task, e.g.: ```c #include From 21d31e93b9539c3464e961862540c9cd3a5616b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bal=C3=A1zs=20Kelemen?= <10376327+prampec@users.noreply.github.com> Date: Tue, 24 Apr 2018 23:15:02 +0200 Subject: [PATCH 13/14] Update WhyHow.md --- WhyHow.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/WhyHow.md b/WhyHow.md index b343d2a..4d412b4 100644 --- a/WhyHow.md +++ b/WhyHow.md @@ -39,18 +39,18 @@ Note that SoftTimer (from v2.0) works on **microsecond** basis. This means, you # Options # -In SoftTimer.h there are some options provided. You include/exclude some macro defines to enable/disable those options. +In SoftTimer.h there are some options provided. You can include/exclude the following macro definitions in the SoftTimer.h to enable/disable these options. -* __PREVENT_LOOP_ITERATION__ - With preventing loop() iteration you will benefit some milliseconds. On the other hand some platforms might depend on the loop(). If you are facing with strange behaviour, you might want to try disabling the PREVENT_LOOP_ITERATION option. PREVENT_LOOP_ITERATION is enabled by default. +* __ENABLE_LOOP_ITERATION__ - With preventing loop() iteration you will benefit some milliseconds. On the other hand some platforms might depend on the loop(). If you are facing with strange behaviour, you might want to try including the ENABLE_LOOP_ITERATION option. ENABLE_LOOP_ITERATION is disabled by default. * __STRICT_TIMING__ - By default the next start of a task scheduled from the begining of the previous execution. But executions might shift if an other task does not finish in time. With STRICT_TIMING the next execution is scheduled for the expected time. STRICT_TIMING is disabled by default, as it might likely to cause starvation in the Tasks. # Platform dependent notes # As SoftTimer eliminates the use of the "loop()" function, on platforms, that has some extra processing in every loop cicle, some troubles might appear. -As a workaround a PREVENT_LOOP_ITERATION option is introduced. (See Options above!) +As a workaround the ENABLE_LOOP_ITERATION option is introduced. (See Options above!) -For example, the internal watchdog in ESP8266 is feed by the system in every loop cycle, so if you do not disable the PREVENT_LOOP_ITERATION option, you need to "feed" the watchdog manually to prevent resets. (Or just disable the watchdog.) +For example, the internal watchdog in ESP8266 is normally feed by the system in every loop cycle. So you will have two options for ESP8266. Either include the ENABLE_LOOP_ITERATION option, or "feed" the watchdog manually to prevent resets. (Or just disable the watchdog.) You can feed the watchdog with a task, e.g.: ```c #include From 15c1b18d9c9ee6d33443c2273a5d851595f850ec Mon Sep 17 00:00:00 2001 From: Elijah Mock <92Eli@users.noreply.github.com> Date: Sun, 23 Aug 2020 15:32:46 -0500 Subject: [PATCH 14/14] Add method signature before defining tasks Fix #31 by telling the compiler that the functions exist. Tested and it works now. --- QuickStartGuide.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/QuickStartGuide.md b/QuickStartGuide.md index dd84dac..5e75274 100644 --- a/QuickStartGuide.md +++ b/QuickStartGuide.md @@ -27,6 +27,10 @@ Full code: ``` #include +// -- Define method signature. +void turnOn(Task* me); +void turnOff(Task* me); + // -- taskOn will be launched on every 2 seconds. Task taskOn(2000, turnOn); // -- taskOff will be launched on every 1111 milliseconds.