mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
98 lines
4.5 KiB
Markdown
98 lines
4.5 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/CountDown/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/CountDown/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/CountDown/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/CountDown/releases)
|
|
|
|
|
|
# CountDown
|
|
|
|
Arduino Library to implement a CountDown clock (in SW polling, no HW timer).
|
|
|
|
|
|
## Description
|
|
|
|
The countdown library is a clock that counts down from a given time to zero.
|
|
It does not call a function or so as the user is responsible to check the time remaining.
|
|
Typically one checks the remaining time in every loop.
|
|
|
|
UNder the hood the function uses **micros()** or **millis()** which results in a maximum time
|
|
of 4294 seconds in micros (1h10m) or about 49+ days when using milliseconds.
|
|
|
|
For longer periods one could cascade countDown, so when one is finished the next one starts.
|
|
|
|
|
|
## Interface
|
|
|
|
The main functions of the CountDown clock are:
|
|
|
|
- **bool start(uint32_t ticks)**
|
|
- **bool start(uint8_t days, uint16_t hours, uint32_t minutes, uint32_t seconds)**
|
|
- **bool start(uint8_t days, uint16_t hours, uint32_t minutes)**
|
|
- **void stop()**
|
|
- **void cont()** *(note continue is a C-Keyword)*
|
|
- **uint32_t remaining()**
|
|
- **bool isRunning()**
|
|
|
|
These functions work straightforward.
|
|
|
|
|
|
## Operation
|
|
|
|
The function **start(days, hours, minutes, seconds)** has changed its
|
|
parameters type to minimize them, given that the total time may not exceed 2^32 milliseconds.
|
|
This allows the user to call **start()** with e.g. four hundred minutes **start(0, 0, 400, 0)**
|
|
or a million seconds **start(0, 0, 0, 1000000)** as parameter.
|
|
The resolution is implicitly set to **CountDown::SECONDS**.
|
|
|
|
Since 0.2.4 the function **start()** will check if the parameters cause an overflow
|
|
in the underlying math. If there is no overflow call to **start()** returns true.
|
|
If there is an overflow it returns false.
|
|
|
|
Total amount of time to countdown for **CountDown::MICROS** may not exceed 2\^32 micros ~ 1 hour 10 minutes.
|
|
Total amount of time to countdown for **CountDown::MILLIS**, **CountDown::SECONDS** and **CountDown::MINUTES**
|
|
may not exceed 2\^32 milliseconds ~49 days.
|
|
|
|
|
|
The function **start(days, hours, minutes)** is new since 0.2.2.
|
|
It also uses **millis()** under the hood. The resolution is implicitly set to **CountDown::MINUTES**.
|
|
|
|
|
|
| Call to start() | resolution | max time | comments |
|
|
|:--------------------------------------|:-----------------|:---------:|:---------|
|
|
| start(days, hours, minutes, seconds) | SECONDS = millis | 49+ days | |
|
|
| start(days, hours, minutes) | MINUTES = millis | 49+ days | |
|
|
| start(ticks) | MILLIS = millis | 49+ days | default |
|
|
| start(ticks) | MICROS = micros | ~70 min | use setResolution(CountDown::MICROS) |
|
|
| start(ticks) | SECONDS = millis | 49+ days | use setResolution(CountDown::SECONDS) |
|
|
| start(ticks) | MINUTES = millis | 49+ days | use setResolution(CountDown::MINUTES) |
|
|
|
|
|
|
The Countdown clock uses by default **millis()** to do the time keeping,
|
|
although this can be changed runtime by **setResolution(res)**. The parameter
|
|
**res** can be:
|
|
- **CountDown::MICROS** // based upon micros()
|
|
- **CountDown::MILLIS** // default
|
|
- **CountDown::SECONDS** // based upon millis()
|
|
- **CountDown::MINUTES** // based upon millis()
|
|
|
|
Although possible one should not change the resolution of the CountDown
|
|
clock while it is running as you mix up different timescales.
|
|
|
|
One can call **start(...)** at any time to reset the running clock to
|
|
a new value. This allows to implement a sort of watchdog clock in which e.g.
|
|
the user must press a button at least once per minute to show he is still
|
|
awake.
|
|
|
|
|
|
## Future
|
|
|
|
- incorporate a real time clock? or EEPROM to be reboot proof?
|
|
- examples with visualisations (e.g. hexadecimal countdown)
|
|
- Countdown based upon external pulses.
|
|
- uint64_t version ==> **CountDown64** class? (only on request)
|
|
- would be useful for micros() in theory but drift / interrupts would make it fail.
|
|
-
|
|
|