Timer

RTOS timer functions. More...

Functions

zos_result_t zn_rtos_timer_init (zos_timer_t *timer, uint32_t time_ms, zos_timer_handler_t function, void *arg)
 Initializes an RTOS timer. More...
 
zos_result_t zn_rtos_timer_start (zos_timer_t *timer)
 Starts a RTOS timer running. More...
 
zos_result_t zn_rtos_timer_stop (zos_timer_t *timer)
 Stops a running RTOS timer. More...
 
zos_result_t zn_rtos_timer_reload (zos_timer_t *timer)
 Reloads an RTOS timer. More...
 
zos_result_t zn_rtos_timer_update (zos_timer_t *timer, uint32_t timeout)
 Update timer timeout. More...
 
zos_result_t zn_rtos_timer_deinit (zos_timer_t *timer)
 De-initialise a RTOS timer. More...
 
zos_bool_t zn_rtos_timer_is_running (zos_timer_t *timer)
 Check if an RTOS timer is running. More...
 

Detailed Description

RTOS timer functions.

Create a timer and initialize the timer period and callback function with zn_rtos_timer_init().

Start the timer with zn_rtos_timer_start().

RTOS timers are periodic. When a timer expires, the callback function is called, then the timer starts again.

Warning: An RTOS timer callback runs at a very high priority and has a very limited stack. Processing must be very limited in the RTOS timer callback. Heavier processing should be done in other threads, such as the ZAP or network threads. Running the timer frequently, for example every 1ms, is strongly discouraged as it can lead to system instability. See Execution Contexts, RTOS Timer.

To prevent a timer restarting after expiry, call zn_rtos_timer_stop() or zn_rtos_timer_deinit() in the callback.

To reschedule a running timer, call zn_rtos_timer_reload().

To determine if a timer is running, call zn_rtos_timer_is_running().

To update timer period, call zn_rtos_timer_update().

To delete a timer created with zn_rtos_timer_init(), call zn_rtos_timer_deinit().

Multiple RTOS timers can run simultaneously. The number of simultaneous RTOS timers is limited by available memory.

Function Documentation

zos_result_t zn_rtos_timer_deinit ( zos_timer_t *  timer)

De-initialise a RTOS timer.

Deletes an RTOS timer created with zn_rtos_timer_init().

Parameters
timer: a pointer to the RTOS timer handle
Returns
ZOS_SUCCESS : on success.
ZOS_ERROR : if an error occurred
zos_result_t zn_rtos_timer_init ( zos_timer_t *  timer,
uint32_t  time_ms,
zos_timer_handler_t  function,
void *  arg 
)

Initializes an RTOS timer.

Timer does not start running until zn_rtos_timer_start() is called.

Parameters
timer: a pointer to the timer handle to be initialised
time_ms: Timer period in milliseconds
function: the callback handler function that is called each time the timer expires. Warning: The RTOS timer callback should be extremely simple, not execute too frequently, and never block. See Execution Contexts, RTOS Timer.
arg: an argument that will be passed to the callback function
Returns
ZOS_SUCCESS : on success.
ZOS_ERROR : if an error occurred
zos_bool_t zn_rtos_timer_is_running ( zos_timer_t *  timer)

Check if an RTOS timer is running.

Parameters
timer: a pointer to the RTOS timer handle
Returns
ZOS_SUCCESS : if running.
ZOS_ERROR : if not running
zos_result_t zn_rtos_timer_reload ( zos_timer_t *  timer)

Reloads an RTOS timer.

Call prior to the timer expiring, to reschedule the timer with the period specified in zn_rtos_timer_init() or zn_rtos_timer_update().

Parameters
timer: a pointer to the timer handle to reload
Returns
ZOS_SUCCESS : on success.
ZOS_ERROR : if an error occurred
zos_result_t zn_rtos_timer_start ( zos_timer_t *  timer)

Starts a RTOS timer running.

Timer must have been previously initialised with zn_rtos_timer_init()

Parameters
timer: a pointer to the timer handle to start
Returns
ZOS_SUCCESS : on success.
ZOS_ERROR : if an error occurred
zos_result_t zn_rtos_timer_stop ( zos_timer_t *  timer)

Stops a running RTOS timer.

Timer must have been previously started with zn_rtos_timer_start()

Parameters
timer: a pointer to the timer handle to stop
Returns
ZOS_SUCCESS : on success.
ZOS_ERROR : if an error occurred
zos_result_t zn_rtos_timer_update ( zos_timer_t *  timer,
uint32_t  timeout 
)

Update timer timeout.

Parameters
timer: a pointer to the timer handle
timeout: timer period in milliseconds