Timer Module¶
Since | Origin / Contributor | Maintainer | Source |
---|---|---|---|
2014-12-12 | Zeroday | dnc40085 | tmr.c |
The tmr module allows access to simple timers. It is aimed at setting up regularly occurring tasks and timing out operations.
What the tmr module is not however, is a time keeping module. While all timeouts are expressed in milliseconds, the accuracy is limited and compounding errors would lead to rather inaccurate time keeping. A module for "wall clock" time is not yet available.
Note
The resolution of the timers is determined by FreeRTOS' tick rate. The default rate of 100 kHz (resulting in 10 ms resolution) can be changed with make menuconfig
at item Component config ---> FreeRTOS ---> Tick rate (Hz)
.
tmr.create()¶
Creates a dynamic timer object.
Syntax¶
tmr.create()
Parameters¶
none
Returns¶
timer
object
Example¶
local mytimer = tmr.create()
-- oo calling
mytimer:register(5000, tmr.ALARM_SINGLE, function (t) print("expired") end)
mytimer:start()
mytimer = nil
tmr Object¶
tmr.obj:alarm()¶
This is a convenience function combining tmr.obj:register()
and tmr.obj:start()
into a single call.
To free up the resources with this timer when done using it, call tmr.obj:unregister()
on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
Syntax¶
mytmr:alarm(interval_ms, mode, func())
Parameters¶
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 calltmr.unregister()
)tmr.ALARM_SEMI
manually repeating alarm (calltmr.start()
to restart)tmr.ALARM_AUTO
automatically repeating alarm
func(timer)
callback function which is invoked with the timer object as an argument
Returns¶
true
if the timer was started, false
on error
Example¶
if not tmr.create():alarm(5000, tmr.ALARM_SINGLE, function()
print("hey there")
end)
then
print("whoopsie")
end
See also¶
tmr.obj:interval()¶
Changes a registered timer's expiry interval.
Syntax¶
mytmr:interval(interval_ms)
Parameters¶
interval_ms
new timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).
Returns¶
nil
Example¶
mytimer = tmr.create()
mytimer:register(10000, tmr.ALARM_AUTO, function() print("hey there") end)
mytimer:interval(3000) -- actually, 3 seconds is better!
mytimer:start()
tmr.obj:register()¶
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 tmr.obj:unregister()
on it. For one-shot timers this is not necessary, unless they were stopped before they expired.
Syntax¶
mytmr:register(interval_ms, mode, func())
Parameters¶
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 calltmr.unregister()
)tmr.ALARM_SEMI
manually repeating alarm (calltmr.start()
to restart)tmr.ALARM_AUTO
automatically repeating alarm
func(timer)
callback function which is invoked with the timer object as an argument
Note that registering does not start the alarm.
Returns¶
nil
Example¶
mytimer = tmr.create()
mytimer:register(5000, tmr.ALARM_SINGLE, function() print("hey there") end)
mytimer:start()
See also¶
tmr.obj:start()¶
Starts or restarts a previously configured timer.
Syntax¶
mytmr:start()
Parameters¶
none
Returns¶
true
if the timer was started, false
on error
Example¶
mytimer = tmr.create()
mytimer:register(5000, tmr.ALARM_SINGLE, function() print("hey there") end)
if not mytimer:start() then print("uh oh") end
See also¶
tmr.obj:state()¶
Checks the state of a timer.
Syntax¶
mytmr:state()
Parameters¶
none
Returns¶
(bool, int) or nil
If the specified timer is registered, returns whether it is currently started and its mode. If the timer is not registered, nil
is returned.
Example¶
mytimer = tmr.create()
print(mytimer:state()) -- nil
mytimer:register(5000, tmr.ALARM_SINGLE, function() print("hey there") end)
running, mode = mytimer:state()
print("running: " .. tostring(running) .. ", mode: " .. mode) -- running: false, mode: 0
tmr.obj:stop()¶
Stops a running timer, but does not unregister it. A stopped timer can be restarted with tmr.obj:start()
.
Syntax¶
mytmr:stop()
Parameters¶
none
Returns¶
true
if the timer was stopped, false
on error
Example¶
mytimer = tmr.create()
if not mytimer:stop() then print("timer not stopped, not registered?") end
See also¶
tmr.obj: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¶
mytmr:unregister()
Parameters¶
none
Returns¶
nil
See also¶
tmr.wdclr()¶
Resets the watchdog timer to prevent a reboot due to a perceived hung task.
Use with caution, as this could prevent a reboot to recover from a genuinely hung task.
On the ESP32, the tmr.wdclr()
function is implemented as a task yield
to let the system "IDLE" task do the necessary watchdog maintenance.
Overuse of this function is likely to result in degraded performance.
Syntax¶
tmr.wdclr()
Parameters¶
none
Returns¶
nil
Example¶
function long_running_function()
while 1
do
if some_condition then break end
-- do some heavy calculation here, for example
tmr.wdclr()
end
end