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();
+```