@@ -9,63 +9,27 @@ It is aimed at setting up regularly occurring tasks, timing out operations, and
What the tmr module is *not* however, is a time keeping module. While most timeouts are expressed in milliseconds or even microseconds, the accuracy is limited and compounding errors would lead to rather inaccurate time keeping. Consider using the [rtctime](rtctime.md) module for "wall clock" time.
NodeMCU provides 7 static timers, numbered 0-6, and dynamic timer creation function [`tmr.create()`](#tmrcreate).
!!! attention
Static timers are deprecated and will be removed later. Use the OO API initiated with [`tmr.create()`](#tmrcreate).
## tmr.alarm()
This is a convenience function combining [`tmr.register()`](#tmrregister) and [`tmr.start()`](#tmrstart) into a single call.
To free up the resources with this timer when done using it, call [`tmr.unregister()`](#tmrunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
#### Syntax
`tmr.alarm([id/ref], interval_ms, mode, func())`
#### Parameters
-`id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
-`interval_ms` timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
-`mode` timer mode:
-`tmr.ALARM_SINGLE` a one-shot alarm (and no need to call [`tmr.unregister()`](#tmrunregister))
-`tmr.ALARM_SEMI` manually repeating alarm (call [`tmr.start()`](#tmrstart) to restart)
-`tmr.ALARM_AUTO` automatically repeating alarm
-`func(timer)` callback function which is invoked with the timer object as an argument
@@ -108,66 +66,131 @@ Also note that the actual amount of time delayed for may be noticeably greater,
tmr.delay(100)
```
## tmr.interval()
## tmr.now()
Changes a registered timer's expiry interval.
Returns the system counter, which counts in microseconds. Limited to 31 bits, after that it wraps around back to zero. That is essential if you use this function to [debounce or throttle GPIO input](https://github.com/hackhitchin/esp8266-co-uk/issues/2).
#### Syntax
`tmr.interval([id/ref], interval_ms)`
`tmr.now()`
#### Parameters
-`id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
-`interval_ms` new timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
none
#### Returns
the current value of the system counter
#### Example
```lua
print(tmr.now())
print(tmr.now())
```
## tmr.softwd()
Provides a simple software watchdog, which needs to be re-armed or disabled before it expires, or the system will be restarted.
#### Syntax
`tmr.softwd(timeout_s)`
#### Parameters
`timeout_s` watchdog timeout, in seconds. To disable the watchdog, use -1 (or any other negative value).
Returns the system counter, which counts in microseconds. Limited to 31 bits, after that it wraps around back to zero. That is essential if you use this function to [debounce or throttle GPIO input](https://github.com/hackhitchin/esp8266-co-uk/issues/2).
Returns the system uptime, in seconds. Limited to 31 bits, after that it wraps around back to zero.
#### Syntax
`tmr.now()`
`tmr.time()`
#### Parameters
none
#### Returns
the current value of the system counter
the system uptime, in seconds, possibly wrapped around
#### Example
```lua
print(tmr.now())
print(tmr.now())
print("Uptime (probably):",tmr.time())
```
## tmr.register()
## tmr.wdclr()
Configures a timer and registers the callback function to call on expiry.
Feed the system watchdog.
*In general, if you ever need to use this function, you are doing it wrong.*
The event-driven model of NodeMCU means that there is no need to be sitting in hard loops waiting for things to occur. Rather, simply use the callbacks to get notified when somethings happens. With this approach, there should never be a need to manually feed the system watchdog.
#### Syntax
`tmr.wdclr()`
#### Parameters
none
#### Returns
`nil`
## Timer Object Methods
### tobj:alarm()
To free up the resources with this timer when done using it, call [`tmr.unregister()`](#tmrunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
This is a convenience function combining [`tobj:register()`](#tobjregister) and [`tobj:start()`](#tobjstart) into a single call.
To free up the resources with this timer when done using it, call [`tobj:unregister()`](#tobjunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
mytimer:interval(3000)-- actually, 3 seconds is better!
mytimer:start()
```
#### See also
-[`tmr.create()`](#tmrcreate)
-[`tmr.alarm()`](#tmralarm)
## tmr.softwd()
### tobj:register()
Provides a simple software watchdog, which needs to be re-armed or disabled before it expires, or the system will be restarted.
Configures a timer and registers the callback function to call on expiry.
To free up the resources with this timer when done using it, call [`tobj:unregister()`](#tobjunregister) on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
#### Syntax
`tmr.softwd(timeout_s)`
`tobj:register(interval_ms, mode, func())`
#### Parameters
`timeout_s` watchdog timeout, in seconds. To disable the watchdog, use -1 (or any other negative value).
-`interval_ms` timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
-`mode` timer mode:
-`tmr.ALARM_SINGLE` a one-shot alarm (and no need to call [`tobj:unregister()`](#tobjunregister))
-`tmr.ALARM_SEMI` manually repeating alarm (call [`tobj:start()`](#tobjunregister) to restart)
-`tmr.ALARM_AUTO` automatically repeating alarm
-`func(timer)` callback function which is invoked with the timer object as an argument
Stops a running timer, but does *not* unregister it. A stopped timer can be restarted with [`tmr.start()`](#tmrstart).
Stops a running timer, but does *not* unregister it. A stopped timer can be restarted with [`tobj:start()`](#tobjstart).
#### Syntax
`tmr.stop([id/ref])`
`tobj:stop()`
#### Parameters
`id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
None
#### Returns
`true` if the timer was stopped, `false` on error
...
...
@@ -275,63 +303,25 @@ mytimer = tmr.create()
ifnotmytimer:stop()thenprint("timer not stopped, not registered?")end
```
#### See also
-[`tmr.register()`](#tmrregister)
-[`tmr.stop()`](#tmrstop)
-[`tmr.unregister()`](#tmrunregister)
## tmr.time()
-[`tobj:register()`](#tobjregister)
-[`tobj:stop()`](#tobjstop)
-[`tobj:unregister()`](#tobjunregister)
Returns the system uptime, in seconds. Limited to 31 bits, after that it wraps around back to zero.
#### Syntax
`tmr.time()`
#### Parameters
none
#### Returns
the system uptime, in seconds, possibly wrapped around
#### Example
```lua
print("Uptime (probably):",tmr.time())
```
## tmr.unregister()
### tobj:unregister()
Stops the timer (if running) and unregisters the associated callback.
This isn't necessary for one-shot timers (`tmr.ALARM_SINGLE`), as those automatically unregister themselves when fired.
#### Syntax
`tmr.unregister([id/ref])`
`tobj:unregister()`
#### Parameters
`id`/`ref` timer id (0-6) or object, obsolete for OO API (→ [`tmr.create()`](#tmrcreate))
None
#### Returns
`nil`
#### Example
```lua
tmr.unregister(0)
```
#### See also
[`tmr.register()`](#tmrregister)
## tmr.wdclr()
Feed the system watchdog.
*In general, if you ever need to use this function, you are doing it wrong.*
The event-driven model of NodeMCU means that there is no need to be sitting in hard loops waiting for things to occur. Rather, simply use the callbacks to get notified when somethings happens. With this approach, there should never be a need to manually feed the system watchdog.