arduino-timer: library for delaying function calls

Signed-off-by: Michael Contreras <[email protected]>

Author: contrem

.gitignore

@@ -0,0 +1,29 @@
+Copyright (c) 2018, Michael Contreras
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSE

@@ -0,0 +1,8 @@
+NAME := arduino-timer
+VERSION := $(shell grep version library.properties | cut -d= -f2)
+
+$(NAME)-$(VERSION).zip:
+	git archive HEAD --prefix=$(@:.zip=)/ --format=zip -o $@
+
+tag:
+	git tag $(VERSION)

Makefile

@@ -0,0 +1,134 @@
+# arduino-timer - library for delaying function calls
+
+Simple *non-blocking* timer library for calling functions **in / at / every** specified units of time. Supports millis, micros, time rollover, and compile time configurable number of tasks.
+
+### Use It
+
+Include the library and create a *Timer* instance.
+```cpp
+#include <timer.h>
+
+auto timer = timer_create_default();
+```
+
+Or using the *Timer* constructors for different task limits / time resolution
+```cpp
+Timer<10> timer; // 10 concurrent tasks, using millis as resolution
+Timer<10, micros> timer; // 10 concurrent tasks, using micros as resolution
+```
+
+Call *timer*.**tick()** in the loop function
+```cpp
+void loop() {
+    timer.tick();
+}
+```
+
+Make a function to call when the *Timer* expires
+```cpp
+bool function_to_call(void *argument /* optional argument given to in/at/every */) {
+    return false; // to keep the timer active - true removes it (for timer.every())
+}
+```
+
+Call *function\_to\_call* **in** *delay* units of time *(unit of time defaults to milliseconds)*.
+```cpp
+timer.in(delay, function_to_call);
+timer.in(delay, function_to_call, argument); // or with an optional argument for function_to_call
+```
+
+Call *function\_to\_call* **at** a specific *time*.
+```cpp
+timer.at(time, function_to_call);
+timer.at(time, function_to_call, argument); // with argument
+```
+
+Call *function\_to\_call* **every** *interval* units of time.
+```cpp
+timer.every(interval, function_to_call);
+timer.every(interval, function_to_call, argument); // with argument
+```
+
+Be fancy with **lambdas**
+```cpp
+timer.in(1000, [](void*) -> bool { return false; });
+timer.in(1000, [](void *argument) -> bool { return argument; }, argument);
+```
+
+### API
+
+```cpp
+/* Constructors */
+/* Create a timer object with default settings - millis resolution, TIMER_MAX_TASKS (=16) task slots */
+Timer<> timer_create_default(); // auto timer = timer_create_default();
+
+/* Create a timer with max_tasks slots and time_func resolution */
+Timer<size_t max_tasks = TIMER_MAX_TASKS, unsigned long (*time_func)(void) = millis> timer;
+Timer<> timer; // Equivalent to: auto timer = timer_create_default()
+Timer<10> timer; // Timer with 10 task slots
+Timer<10, micros> timer; // timer with 10 task slots and microsecond resolution
+
+/* Signature for handler functions */
+bool handler(void *argument);
+
+/* Timer Methods */
+/* Ticks the timer forward - call this function in loop() */
+void tick();
+
+/* Calls handler with opaque as argument in delay units of time */
+bool in(unsigned long delay, handler_t handler, void *opaque = NULL);
+
+/* Calls handler with opaque as argument at time */
+bool at(unsigned long time, handler_t handler, void *opaque = NULL);
+
+/* Calls handler with opaque as argument every interval units of time */
+bool every(unsigned long interval, handler_t handler, void *opaque = NULL);
+```
+
+### Installation
+
+[Check out the instructions](https://www.arduino.cc/en/Guide/Libraries) from Arduino.
+
+**OR** copy **src/timer.h** into your project folder *(you won't get managed updates this way)*.
+
+### Examples
+
+Found in the **examples/** folder.
+
+The simplest example, blinking an LED every second *(from examples/blink)*:
+
+```cpp
+#include <timer.h>
+
+auto timer = timer_create_default(); // create a timer with default settings
+
+bool toggle_led(void *) {
+  digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // toggle the LED
+  return false; // stop repeating? false
+}
+
+void setup() {
+  pinMode(LED_BUILTIN, OUTPUT); // set LED pin to OUTPUT
+
+  // call the toggle_led function every 1000 millis (1 second)
+  timer.every(1000, toggle_led);
+}
+
+void loop() {
+  timer.tick(); // tick the timer
+}
+```
+
+### LICENSE
+
+Check the LICENSE file - 3-Clause BSD License
+
+### Notes
+
+Currently only a software timer. Any blocking code delaying *timer*.**tick()** will prevent the timer from moving forward and calling any functions.
+
+The library does not do any dynamic memory allocation.
+
+The number of concurrent tasks is a compile time constant, meaning there is a limit to the number of concurrent tasks. The **in / at / every** functions return **false** if the *Timer* is full.
+
+Change the number of concurrent tasks using the *Timer* constructors. Save memory by reducing the number, increase memory use by having more. The default is **TIMER_MAX_TASKS** which is currently 16.

README.md

@@ -0,0 +1,26 @@
+/*
+ * timer_blink
+ *
+ * Blinks the built-in LED every second using the arduino-timer library.
+ *
+ */
+
+#include <timer.h>
+
+auto timer = timer_create_default(); // create a timer with default settings
+
+bool toggle_led(void *) {
+  digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // toggle the LED
+  return false; // stop repeating? false
+}
+
+void setup() {
+  pinMode(LED_BUILTIN, OUTPUT); // set LED pin to OUTPUT
+
+  // call the toggle_led function every 1000 millis (1 second)
+  timer.every(1000, toggle_led);
+}
+
+void loop() {
+  timer.tick(); // tick the timer
+}

examples/blink/blink.ino

@@ -0,0 +1,26 @@
+/*
+ * timer_blink_micros
+ *
+ * Blinks the built-in LED every second using the arduino-timer library.
+ *
+ */
+
+#include <timer.h>
+
+Timer<1, micros> timer; // create a timer with 1 task and microsecond resolution
+
+bool toggle_led(void *) {
+  digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // toggle the LED
+  return false; // stop repeating? false
+}
+
+void setup() {
+  pinMode(LED_BUILTIN, OUTPUT); // set LED pin to OUTPUT
+
+  // call the toggle_led function every 1000000 micros (1 second)
+  timer.every(1000000, toggle_led);
+}
+
+void loop() {
+  timer.tick(); // tick the timer
+}

examples/blink_micros/blink_micros.ino

@@ -0,0 +1,37 @@
+/*
+ * timer_blink_print
+ *
+ * Blinks the built-in LED every half second, and prints a messages every
+ * second using the arduino-timer library.
+ *
+ */
+
+#include <timer.h>
+
+auto timer = timer_create_default(); // create a timer with default settings
+
+bool toggle_led(void *) {
+  digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // toggle the LED
+  return false; // stop repeating? false
+}
+
+bool print_message(void *) {
+  Serial.print("print_message: Called at: ");
+  Serial.println(millis());
+  return false; // stop repeating? false
+}
+
+void setup() {
+  Serial.begin(9600);
+  pinMode(LED_BUILTIN, OUTPUT); // set LED pin to OUTPUT
+
+  // call the toggle_led function every 500 millis (half second)
+  timer.every(500, toggle_led);
+
+  // call the print_message function every 1000 millis (1 second)
+  timer.every(1000, print_message);
+}
+
+void loop() {
+  timer.tick(); // tick the timer
+}

examples/blink_print/blink_print.ino

@@ -0,0 +1,76 @@
+/*
+ * timer_full
+ *
+ * Full example using the arduino-timer library.
+ * Shows:
+ *  - Setting a different number of tasks with microsecond resolution
+ *  - disabling a repeated function
+ *  - running a function after a delay
+ *
+ */
+
+#include <timer.h>
+
+auto timer = timer_create_default(); // create a timer with default settings
+Timer<> default_timer; // save as above
+
+// create a timer that can hold 1 concurrent task, with microsecond resolution
+Timer<1, micros> u_timer;
+
+bool toggle_led(void *) {
+  digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN)); // toggle the LED
+  return false; // stop repeating? false
+}
+
+bool print_message(void *msg) {
+  const char *m = (const char *)msg;
+  Serial.print("print_message: ");
+  Serial.println(m);
+  return false; // stop repeating? false
+}
+
+size_t repeat_count = 1;
+bool repeat_x_times(void *opaque) {
+  size_t limit = (size_t)opaque;
+
+  Serial.print("repeat_x_times: ");
+  Serial.print(repeat_count);
+  Serial.print("/");
+  Serial.println(limit);
+
+  return ++repeat_count > limit; // remove this task after limit reached
+}
+
+void setup() {
+  Serial.begin(9600);
+  pinMode(LED_BUILTIN, OUTPUT); // set LED pin to OUTPUT
+
+  // call the toggle_led function every 500 millis (half second)
+  timer.every(500, toggle_led);
+
+  // call the repeat_x_times function every 1000 millis (1 second)
+  timer.every(1000, repeat_x_times, 10);
+
+  // call the print_message function every 1000 millis (1 second),
+  // passing it an argument string
+  timer.every(1000, print_message, "called every second");
+
+  // call the print_message function in five seconds
+  timer.in(5000, print_message, "delayed five seconds");
+
+  // call the print_message function at time + 10 seconds
+  timer.at(millis() + 10000, print_message, "call at millis() + 10 seconds");
+
+  // call print_message in 2 seconds, but with microsecond resolution
+  u_timer.in(2000000, print_message, "delayed two seconds using microseconds");
+
+  if (!u_timer.in(5000, print_message, "never printed")) {
+  /* this fails because we created u_timer with only 1 concurrent task slot */
+    Serial.println("Failed to add microsecond event - timer full");
+  }
+}
+
+void loop() {
+  timer.tick(); // tick the timer
+  u_timer.tick();
+}

examples/full/full.ino

@@ -0,0 +1,39 @@
+/*
+ Test timer rollover handling
+ */
+
+#include <timer.h>
+
+unsigned long wrapping_millis();
+
+Timer<1, wrapping_millis> timer; // this timer will wrap
+auto _timer = timer_create_default(); // to count milliseconds
+
+unsigned long _millis = 0L;
+unsigned long wrapping_millis()
+{
+    // uses _millis controled by _timer
+    // 6-second time loop starting at rollover - 3 seconds
+    if (_millis - (-3000) >= 6000)
+        _millis = -3000;
+    return _millis;
+}
+
+void setup() {
+    pinMode(LED_BUILTIN, OUTPUT);
+    _timer.every(1, [](void *) -> bool {
+        ++_millis; // increase _millis every millisecond
+        return false;
+    });
+
+    // should blink the led every second, regardless of wrapping
+    timer.every(1000, [](void *) -> bool {
+        digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
+        return false;
+    });
+}
+
+void loop() {
+    _timer.tick();
+    timer.tick();
+}