trunk/Arduino/libraries/Ticker/README.md

@@ -1,15 +1,15 @@
-# Arduino Ticker Library v3.1.x
+# Arduino Ticker Library v4.x.x
+**Advice: for use with ESP boards and mbed based Arduino boards like Arduino Nano RP2040 Connect and Raspberry Pi Pico (using the official Arduino core) the TickTwo library [https://github.com/sstaub/TickTwo](https://github.com/sstaub/TickTwo) is recommanded**
 
 The **Arduino Ticker Library** allows you to create easily Ticker callbacks, which can call a function in a predetermined interval. You can change the number of repeats of the callbacks, if repeats is 0 the ticker runs in endless mode. Works like a "thread", where a secondary function will run when necessary. The library use no interupts of the hardware timers and works with the **micros() / millis()** function. You are not (really) limited in the number of Tickers.
 
-## New in v2.0
-- You can determine the number of repeats, instead of modes.
-- The internal resolution is now **micros()**, this works with intervals up to 70 minutes. For longer intervals you can change the resolution to **millis()**. ``` Ticker tickerObject(callbackFunction, 1000, 0, MILLIS) ```
-- unified data types and smaller improvments
+## New in v4.0
+- added get interval function
+- added remaining function
+- added support for functional callbacks, only for ARM and ESP devices, e.g.<br> "Examples/FunctionalARM/FunctionalARM.ino"
 
-## New in v2.1
-- You can change the interval time to microseconds. ``` Ticker tickerObject(callbackFunction, 100, 0, MICROS_MICROS) // interval is now 100us```
-- smaller improvments
+## New in v3.1
+- added set interval function
 
 ## New in v3.0
 - radical simplified API
@@ -17,8 +17,20 @@ The **Arduino Ticker Library** allows you to create easily Ticker callbacks, whi
 - deleted many set and get functions
 - if you need former functionality please use the version 2.1
 
-## New in v3.1
-- added interval function
+## New in v2.1
+- You can change the interval time to microseconds.
+```cpp
+Ticker tickerObject(callbackFunction, 100, 0, MICROS_MICROS) // interval is now 100us
+```
+- smaller improvments
+
+## New in v2.0
+- You can determine the number of repeats, instead of modes.
+- The internal resolution is now **micros()**, this works with intervals up to 70 minutes. For longer intervals you can change the resolution to **millis()**.
+```cpp
+Ticker tickerObject(callbackFunction, 1000, 0, MILLIS)
+```
+- unified data types and smaller improvments
 
 ## Installation
 
@@ -31,22 +43,21 @@ The **Arduino Ticker Library** allows you to create easily Ticker callbacks, whi
 
 First, include the TimerObject to your project:
 
-```
+```cpp
 #include "Ticker.h"
 ```
 
 Now, you can create a new object in setup():
 
-```
+```cpp
 Ticker tickerObject(callbackFunction, 1000); 
 tickerObject.start(); //start the ticker.
 ```
 
 In your loop(), add:
 
-```
-tickerObject.update(); //it will check the Ticker 
-and if necessary, it will run the callback function.
+```cpp
+tickerObject.update(); //it will check the Ticker and if necessary, it will run the callback function.
 ```
 
 
@@ -57,7 +68,7 @@ If you use delay(), the Ticker will be ignored! You cannot use delay() command w
 
 Complete example. Here we created five timers, you can run it and test the result in the Serial monitor and the on board LED.
 
-```
+```cpp
 #include "Ticker.h"
 
 void printMessage();
@@ -70,7 +81,7 @@ bool ledState;
 int counterUS;
 
 Ticker timer1(printMessage, 0, 1); // once, immediately 
-Ticker timer2(printCounter, 1000, MILLIS); // internal resolution is milli seconds
+Ticker timer2(printCounter, 1000, 0, MILLIS); // internal resolution is milli seconds
 Ticker timer3(printCountdown, 1000, 5); // 5 times, every second
 Ticker timer4(blink, 500); // changing led every 500ms
 Ticker timer5(printCountUS, 100, 0, MICROS_MICROS); // the interval time is 100us and the internal resolution is micro seconds
@@ -128,48 +139,206 @@ void printCountUS() {
 ## Documentation
 
 ### States
-STOPPED / RUNNING / PAUSED
 
-### Constructors / Destructor
+```cpp
+enum status_t {
+  STOPPED,
+  RUNNING,
+  PAUSED
+  };
+```
+
+### Constructors
+
+```cpp
+Ticker::Ticker(fptr callback, uint32_t timer, uint16_t repeats, interval_t mode)
+```
 
-**Ticker(fptr callback, uint32_t timer, uint32_t repeats = 0, resolution_t resolution = MICROS)**<br>
 Creates a Ticker object
-- parameter callback for the function name you want to call
-- parameter timer sets the interval time in ms or us when using MICROS_MICROS with the resolution parameter
-- parameter repeats sets the number of repeats the callback should executed, 0 is endless
-- parameter resolution sets the internal resolution of the Ticker, it can MICROS, MICROS_MICROS or MILLIS
 
-**~Ticker()**<br>
+- **callback** for the function name you want to call
+- **timer** set the interval time in ms or us depending from mode
+- **repeats** set the number of repeats the callback should executed, 0 is endless (default)
+- **mode** set the interval resolution to MILLIS, MICROS_MICROS or MICROS (default)
+
+**Example**
+
+```cpp
+Ticker timer(blink, 1000); // calls function blink() every second, internal resolution is micros, running endless
+Ticker timer(blink, 1000, 5); // calls function blink() every second, internal resolution is micros, only 5 repeats
+Ticker timer(blink, 1000, 0, MILLIS); // calls function blink() every second, internal resolution is millis, running endless
+Ticker timer(blink, 1000, 0, MICROS_MICROS); // calls function blink() every 1000 microsecond, internal resolution is micros, running endless
+```
+
+### Destructor
+
+```cpp
+Ticker::~Ticker()
+```
 Destructor for Ticker object
-	
-### Functions
 
-**void start()**<br>
+## Class Functions
+
+### Ticker Start
+
+```cpp
+void Ticker::start()
+```
+
 Start the Ticker. Will count the interval from the moment that you start it. If it is paused, it will restart the Ticker.
 
-**void resume()**<br>
-Resume the Ticker. If not started, it will start it. If paused, it will resume it. For example, in a Ticker of 5 seconds, if it was paused at 3 seconds, the resume continues at 3 seconds. Start will set passed time to 0 and restart until it get 5 seconds.
+**Example**
+
+```cpp
+timer.start();
+```
+
+### Ticker Resume
+
+```cpp
+void Ticker::resume()
+```
+
+Resume the Ticker. If not started, it will start it. If paused, it will resume it. For example, in a Ticker of 5 seconds, if it was paused in 3 seconds, the resume in continue in 3 seconds. Start will set passed time to 0 and restart until get 5 seconds.
+
+**Example**
+
+```cpp
+timer.resume();
+```
+
+### Ticker Pause
+
+```cpp
+void Ticker::pause()
+```
 
-**void pause()**<br>
 Pause the Ticker, so you can resume it.
 
-**void stop()**<br>
+**Example**
+
+```cpp
+timer.pause();
+```
+
+### Ticker Stop
+
+```cpp
+void Ticker::stop()
+```
+
 Stop the Ticker.
 
-**void update()**<br>
-Must called in the loop(), it will check the Ticker, and if necessary, will run the callback
+**Example**
 
-**void interval(uint32_t timer)**<br>
-Changes the interval time of the Ticker.
+```cpp
+timer.stop();
+```
+
+### Ticker Update
+
+```cpp
+void Ticker::update()
+```
+
+Must to be called in the main while() loop, it will check the Ticker, and if necessary, will run the callback.
+
+**Example**
+
+```cpp
+while(1) {
+  timer.update();
+1.   }
+```
+
+### Ticker set Interval Time
+
+```cpp
+void Ticker::interval(uint32_t timer)
+```
+
+Changes the interval time of the Ticker. Depending from the mode it can millis or micro seconds.
+
+- **timer** set the interval time in ms or us depending from mode
+
+
+**Example**
+
+```cpp
+timer.interval(500); // new interval time
+```
+
+### Ticker get Interval Time
+
+```cpp
+uint32_t Ticker::interval()
+```
+
+Get the interval time of the Ticker. Depending from the mode it can millis or micro seconds.
+
+**Example**
+
+```cpp
+uint32_t intervalTime;
+intervalTime = timer.interval(); // get the interval time
+```
+
+### Ticker State
+
+```cpp
+status_t Ticker::state()
+```
 
-**status_t state()**<br>
 Returns the state of the Ticker.
 
-**uint32_t elapsed()**<br>
-Returns the time passed since the last tick, ms or us depending from the resolution.
+**Example**
 
-**uint32_t counter()**<br>
-Returns the number of executed callbacks.
+```cpp
+status_t status;
+status = timer.state();
+```
 
+### Ticker Elapsed Time
 
+```cpp
+uint32_t Ticker::elapsed()
+```
 
+Returns the time passed since the last tick in ms or us depending on mode.
+
+**Example**
+
+```cpp
+uint32_t elapse;
+elapse = timer.elapsed();
+```
+
+### Ticker Remaining Time
+
+```cpp
+uint32_t Ticker::remaining()
+```
+
+Returns the remaining time to the next tick in ms or us depending on mode.
+
+**Example**
+
+```cpp
+uint32_t remain;
+remain = timer.remaining();
+```
+
+### Ticker Counter
+
+```cpp
+uint32_t Ticker::counter()
+```
+
+Get the number of executed callbacks.
+
+**Example**
+
+```cpp
+uint32_t count;
+count = timer.counter();
+```

trunk/Arduino/libraries/Ticker/Ticker.cpp

@@ -73,36 +73,39 @@ void Ticker::update() {
 	}
 
 bool Ticker::tick() {
-	if (!enabled)	return false;
-	if (resolution == MILLIS) {
-		if ((millis() - lastTime) >= timer) {
-			lastTime = millis();
-			if (repeat - counts == 1) enabled = false;
-			counts++;				
-	  	return true;
+	if (!enabled)	return false;	
+	uint32_t currentTime = (resolution == MILLIS) ? millis() : micros();
+ 	if ((currentTime - lastTime) >= timer) {
+ 		lastTime = currentTime;
+ 		if (repeat - counts == 1 && counts != 0xFFFFFFFF) {
+			enabled = false;
+			status = STOPPED;
 			}
-		}
-	else {
-		if ((micros() - lastTime) >= timer) {
-			lastTime = micros();
-			if (repeat - counts == 1) enabled = false;
-			counts++;
-			return true;
-			}
-		}
+		counts++;
+ 		return true;
+ 		}
 	return false;
 	}
 
 void Ticker::interval(uint32_t timer) {
-	if (resolution == MICROS) timer = timer * 1000;
+	if (resolution == MICROS) timer *= 1000;
 	this->timer = timer;
 	}
 
+uint32_t Ticker::interval() {
+	if (resolution == MILLIS) return timer / 1000;
+	else return timer;
+	}
+
 uint32_t Ticker::elapsed() {
 	if (resolution == MILLIS) return millis() - lastTime;
 	else return micros() - lastTime;
 	}
 
+uint32_t Ticker::remaining() {
+	return timer - elapsed();
+	}
+
 status_t Ticker::state() {
 	return status;
 	}

trunk/Arduino/libraries/Ticker/Ticker.h

@@ -33,7 +33,11 @@
  * @param MILLIS set the resolution to millis, for longer cycles over 70 minutes
  *
  */
-enum resolution_t {MICROS, MILLIS, MICROS_MICROS};
+enum resolution_t {
+	MICROS,
+	MILLIS,
+	MICROS_MICROS
+	};
 
 /** Ticker status
  *
@@ -42,9 +46,18 @@ enum resolution_t {MICROS, MILLIS, MICROS_MICROS};
  * @param PAUSED ticker is paused
  *
  */
-enum status_t {STOPPED, RUNNING, PAUSED};
+enum status_t {
+	STOPPED,
+	RUNNING,
+	PAUSED};
 
+#if defined(__arm__) || defined(ESP8266) || defined(ESP32)
+#include <functional>
+using fptr = std::function<void()>;
+#else
 typedef void (*fptr)();
+#endif
+
 
 class Ticker {
 
@@ -97,6 +110,13 @@ public:
 	 */
 	void interval(uint32_t timer);
 
+	/**
+	 * @brief get the interval time
+	 * 
+	 * @returns the interval time
+	 */
+	uint32_t interval();
+
 	/** actual ellapsed time
 	 *
 	 * @returns the elapsed time after the last tick
@@ -104,6 +124,13 @@ public:
 	 */
 	uint32_t elapsed();
 
+	/** time remaining to the next tick
+	 *
+	 * @returns the remaining time to the next tick in ms or us depending from mode
+	 *
+	 */
+	uint32_t remaining();
+
 	/** get the state of the ticker
 	 *
 	 * @returns the state of the ticker: STOPPED, RUNNING or PAUSED

trunk/Arduino/libraries/Ticker/examples/Ticker/Ticker.ino

@@ -10,7 +10,7 @@ bool ledState;
 int counterUS;
 
 Ticker timer1(printMessage, 0, 1);
-Ticker timer2(printCounter, 1000, MILLIS);
+Ticker timer2(printCounter, 1000, 0, MILLIS);
 Ticker timer3(printCountdown, 1000, 5);
 Ticker timer4(blink, 500);
 Ticker timer5(printCountUS, 100, 0, MICROS_MICROS);

trunk/Arduino/libraries/Ticker/keywords.txt

@@ -8,3 +8,4 @@ interval	KEYWORD2
 state	KEYWORD2
 counter	KEYWORD2
 elapsed	KEYWORD2
+remaining	KEYWORD2

trunk/Arduino/libraries/Ticker/library.json

@@ -7,7 +7,7 @@
     "type": "git",
     "url": "https://github.com/sstaub/Ticker"
   },
-  "version": "3.2.0",
+  "version": "4.4.0",
   "frameworks": "arduino",
   "platforms": "*"
 }

trunk/Arduino/libraries/Ticker/library.properties

@@ -1,5 +1,5 @@
 name=Ticker
-version=3.2.0
+version=4.4.0
 author=Stefan Staub
 maintainer=Stefan Staub <email@domain.com>
 sentence=A library for creating Tickers which can call repeating functions. Replaces delay() with non-blocking functions.