Out-of-office display, GFX
 All Classes Files Functions Variables Enumerations Enumerator Groups
Files | Classes | Macros | Enumerations | Functions
Tick timer

Provides a tick timer calling provided callbacks at given intervals. More...

Files

file  tickTimer.h

Classes

struct  tick
 A tick is split in seconds and milliseconds. More...

Macros

#define TICKTIMER_MAX_CALLBACKS   15
 Size of the callback function array.
#define TICKTIMER_TIMER_NO   1
 The number of the hardware time to use.

Enumerations

enum  tickTimer_initRetVal { TickTimerInit_OK, TickTimerInit_errPriority, TickTimerInit_errInterval }
 tickTimer_init() return values More...

Functions

int tickTimer_init (unsigned int intervalMs, int priority)
 Initialise the tick timer module.
struct tick tickTimer_getTick ()
 Returs the current tick.
unsigned long tickTimer_diff (const struct tick *lastTick)
 Calculation the duration between the current tick value and the given lastTick
bool tickTimer_hasPassed (const struct tick *lastTick, unsigned long durationMs)
 Compare a previously retrieved tick with the current tick and check if the difference is longer than the expected duration.
int tickTimer_addCallback (void(*callback)(void *arg), void *arg, int intervalSecs, int intervalMSecs, int repeats)
 Add a callback function.
void tickTimer_removeCallback (void(*callback)(void *arg))
 Remove a previously registered callback.
bool tickTimer_callbackActive (void(*callback)(void *arg))
 Check if callback is active.
void tickTimer_handleCallbacks ()
 Check all registered callbacks and see if they chould be called given the current tick value.

Detailed Description

Provides a tick timer calling provided callbacks at given intervals.

Author
Andreas Misje
Date
15.03.13

Tick timer occupies a 16-bit hardware timer and uses it to update a tick value. The interval between every tick update is set by the user, but it must be between 1 and 1000 ms. The accuracy of the ticks depend on the interval chosen by the user, the timer priority set and whether the timer interrupt routine runs undisturbed.

In addition to provide a tick counter, this module enables the user to register callback functions that will be fired at given intervals (or once after a certain delay). This functionality can help eliminating any busy-while delay loops, but its accuracy is limited to how often tickTimer_handleCallbacks() gets called in the main loop. tickTimer_handleCallbacks() iterates over an array of callbacks and fires them in their registered order if their timestamp has expired.


Class Documentation

struct tick

A tick is split in seconds and milliseconds.

Class Members
unsigned int ms Millisecond part of tick
unsigned int s Second part of tick

Enumeration Type Documentation

tickTimer_init() return values

Enumerator:
TickTimerInit_OK 

Everything went OK

TickTimerInit_errPriority 

The priority argument was incorrect

TickTimerInit_errInterval 

The interval argument was incorrect

Function Documentation

int tickTimer_addCallback ( void(*)(void *arg)  callback,
void *  arg,
int  intervalSecs,
int  intervalMSecs,
int  repeats 
)

Add a callback function.

The provided function will be called with the given argument after the given interval has passed. It is then removed from the callback array, providing a vacant space for a new callback function. If repeats is non-zero, the function will be called repeatedly with the given interval before it is removed. If repeats is a negative number, the function will be repeated forever (and forever occupy space in the callback array).

Note that callbacks are called in the order they are added.

Parameters
callbacka pointer to a function returning nothing, expecting one void pointer argument
argthe argument which will be passed to the callback function. May be NULL
intervalSecsthe seconds part of the interval
intervalMSecsthe milliseconds part of the interval
repeatsnumber of times the function will be repeated. If 0, the function will be called only once. If any negative value, the function will be repeated forever.
Return values
0if the callback was registered successfully, non-zero if there was no more room in the interal callback array
bool tickTimer_callbackActive ( void(*)(void *arg)  callback)

Check if callback is active.

Active here means that callback is in the callback array.

Parameters
callbacka pointer to the callback function to check
Return values
trueif the callback exists in the callback array
falseif the callback is not currently active
unsigned long tickTimer_diff ( const struct tick lastTick)

Calculation the duration between the current tick value and the given lastTick

Parameters
lastTickprevious tick to compare against
Returns
number of milliseconds that has passed since lastTick
struct tick tickTimer_getTick ( )
read

Returs the current tick.

Returns
current tick
void tickTimer_handleCallbacks ( )

Check all registered callbacks and see if they chould be called given the current tick value.

This functions must be called often enough in order to ensure a timely response. Note that callbacks are called in the order they are added.

bool tickTimer_hasPassed ( const struct tick lastTick,
unsigned long  durationMs 
)

Compare a previously retrieved tick with the current tick and check if the difference is longer than the expected duration.

Parameters
lastTickprevious tick to compare against
durationMsthe duration (in milliseconds) to test against
Return values
trueif the given duration has passed
falseif the given duration has not yet passed
int tickTimer_init ( unsigned int  intervalMs,
int  priority 
)

Initialise the tick timer module.

Must only be called once during the life time of the application. It starts the hardware timer and resets interal variables.

Parameters
intervalMsthe interval between the tick updates in milliseconds. Must be between 1 and 1000
prioritythe hardware timer interrupt priority. Must be between 0 and 7
Returns
tickTimer_initRetVal
void tickTimer_removeCallback ( void(*)(void *arg)  callback)

Remove a previously registered callback.

Parameters
callbacka pointer to the callback function to remove/unregister