@@ -15,25 +15,30 @@ Arduino Library to implement a CountDown clock (in SW polling, no HW timer).
1515
1616The countdown library is a clock that counts down from a given time to zero.
1717It does not call a function or so as the user is responsible to check the time remaining.
18- Typically one checks the remaining time in every loop.
18+ Typically one checks the remaining time in every ** loop() ** .
1919
20- UNder the hood the function uses ** micros()** or ** millis()** which results in a maximum time
21- of 4294 seconds in micros (1h10m ) or about 49+ days when using milliseconds.
20+ Under the hood the function uses ** micros()** or ** millis()** which results in a maximum time
21+ of 4294 seconds in micros (1h 10m ) or about 49+ days when using milliseconds.
2222
23- For longer periods one could cascade countDown, so when one is finished the next one starts.
23+ For longer periods one could cascade countDown objects, so when one is finished the next one starts.
24+
25+ Note the countdown object is as accurate as the underlying ** millis()** or ** micros()** .
26+ Interrupts etc might cause deviations.
2427
2528
2629## Interface
2730
2831The main functions of the CountDown clock are:
2932
30- - ** bool start(uint32_t ticks)**
31- - ** bool start(uint8_t days, uint16_t hours, uint32_t minutes, uint32_t seconds)**
32- - ** bool start(uint8_t days, uint16_t hours, uint32_t minutes)**
33- - ** void stop()**
34- - ** void cont()** * (note continue is a C-Keyword)*
35- - ** uint32_t remaining()**
36- - ** bool isRunning()**
33+ - ** CountDown(const enum Resolution res = MILLIS)** constructor, with default resolution of milliseconds.
34+ - ** bool start(uint32_t ticks)** (re)start in current resolution.
35+ - ** bool start(uint8_t days, uint16_t hours, uint32_t minutes, uint32_t seconds)** Implicit set resolution to SECONDS.
36+ - ** bool start(uint8_t days, uint16_t hours, uint32_t minutes)** Implicit set resolution to MINUTES.
37+ - ** void stop()** stop the count-down.
38+ - ** void cont()** resumes / continue the count-down.
39+ * (note continue is a C-Keyword)*
40+ - ** uint32_t remaining()** returns the remaining ticks in current resolution.
41+ - ** bool isRunning()** idem.
3742
3843These functions work straightforward.
3944
@@ -42,36 +47,42 @@ These functions work straightforward.
4247
4348The function ** start(days, hours, minutes, seconds)** has changed its
4449parameters type to minimize them, given that the total time may not exceed 2^32 milliseconds.
45- This allows the user to call ** start()** with e.g. four hundred minutes ** start(0, 0, 400, 0)**
46- or a million seconds ** start(0, 0, 0, 1000000)** as parameter.
50+ This allows the user to call ** start()** with e.g.
51+ - four hundred minutes ** start(0, 0, 400, 0)**
52+ - a million seconds ** start(0, 0, 0, 1000000)**
53+ - a unusual mix ** start(0, 0, 400, 1000)** as parameter.
4754The resolution is implicitly set to ** CountDown::SECONDS** .
4855
4956Since 0.2.4 the function ** start()** will check if the parameters cause an overflow
50- in the underlying math. If there is no overflow call to ** start()** returns true.
51- If there is an overflow it returns false.
52-
53- Total amount of time to countdown for ** CountDown::MICROS** may not exceed 2\^ 32 micros ~ 1 hour 10 minutes.
54- Total amount of time to countdown for ** CountDown::MILLIS** , ** CountDown::SECONDS** and ** CountDown::MINUTES**
55- may not exceed 2\^ 32 milliseconds ~ 49 days.
57+ in the underlying math.
58+ If there is no overflow, a call to ** start()** returns true.
59+ If there is an overflow, a call to ** start()** returns false.
5660
61+ Total amount of time to countdown for ** CountDown::MICROS** may not exceed 2\^ 32 micros
62+ which equals about 1 hour and 10 minutes.
63+ Total amount of time to countdown for ** CountDown::MILLIS** , ** CountDown::SECONDS**
64+ and ** CountDown::MINUTES** may not exceed 2\^ 32 milliseconds, about 49 days.
5765
5866The function ** start(days, hours, minutes)** is new since 0.2.2.
59- It also uses ** millis()** under the hood. The resolution is implicitly set to ** CountDown::MINUTES** .
67+ It also uses ** millis()** under the hood.
68+ The resolution is implicitly set to ** CountDown::MINUTES** .
6069
6170
62- | Call to start() | resolution | max time | comments |
63- | :-------------------------------------- | :-----------------| :- --------:| :---------|
64- | start(days, hours, minutes, seconds) | SECONDS = millis | 49+ days | |
65- | start(days, hours, minutes) | MINUTES = millis | 49+ days | |
66- | start(ticks) | MILLIS = millis | 49+ days | default |
67- | start(ticks) | MICROS = micros | ~ 70 min | use setResolution(CountDown::MICROS) |
68- | start(ticks) | SECONDS = millis | 49+ days | use setResolution(CountDown::SECONDS) |
69- | start(ticks) | MINUTES = millis | 49+ days | use setResolution(CountDown::MINUTES) |
71+ | Call to start() | resolution | max time | comments |
72+ | :-------------------------------------| :-----------------| :--------:| :---------|
73+ | start(days, hours, minutes, seconds) | SECONDS = millis | 49+ days | |
74+ | start(days, hours, minutes) | MINUTES = millis | 49+ days | |
75+ | start(ticks) | MILLIS = millis | 49+ days | default |
76+ | start(ticks) | MICROS = micros | ~ 70 min | setResolution(CountDown::MICROS) |
77+ | start(ticks) | SECONDS = millis | 49+ days | setResolution(CountDown::SECONDS) |
78+ | start(ticks) | MINUTES = millis | 49+ days | setResolution(CountDown::MINUTES) |
7079
7180
7281The Countdown clock uses by default ** millis()** to do the time keeping,
73- although this can be changed runtime by ** setResolution(res)** . The parameter
74- ** res** can be:
82+ although this can be changed runtime by ** setResolution(res)** .
83+
84+ The parameter ** res** can be:
85+
7586- ** CountDown::MICROS** // based upon micros()
7687- ** CountDown::MILLIS** // default
7788- ** CountDown::SECONDS** // based upon millis()
@@ -80,18 +91,34 @@ although this can be changed runtime by **setResolution(res)**. The parameter
8091Although possible one should not change the resolution of the CountDown
8192clock while it is running as you mix up different timescales.
8293
83- One can call ** start(...)** at any time to reset the running clock to
84- a new value. This allows to implement a sort of watchdog clock in which e.g.
85- the user must press a button at least once per minute to show he is still
86- awake.
94+
95+ #### Watchdog
96+
97+ One can call ** start(...)** at any time to reset the running clock to a new value.
98+ This allows to implement a sort of watchdog clock in which e.g.
99+ the user must press a button at least once per minute to show he is still awake.
87100
88101
89102## Future
90103
91- - incorporate a real time clock? or EEPROM to be reboot proof?
92- - examples with visualisations (e.g. hexadecimal countdown)
93- - Countdown based upon external pulses.
104+ #### must
105+ - documentation
106+
107+ #### should
108+
109+
110+ #### could
111+ - incorporate a real time clock
112+ - or EEPROM to be reboot proof?
113+ - examples
114+ - visualisations - hexadecimal - alphabetical (radix 26)
115+ - depends on sensor
94116- uint64_t version ==> ** CountDown64** class? (only on request)
95117 - would be useful for micros() in theory but drift / interrupts would make it fail.
96- -
118+ - countdown with a big number e.g. billions/ second ==> national deficit coounter.
119+
120+ #### wont
121+ - Countdown based upon external pulses.
122+ - pulse counter
123+
97124
0 commit comments