Contiki OS Timer by

Salah Amean

background

★ Timer is essential part of

★ Contiki OS system provides set of timer libraries

○ used both by application programs and

○ by the Contiki system itself.

★ timer libraries contain functionality based on the time allotted

○ to wake up the system in the low power mode( LP)

○ real time task scheduling

★ Application uses timer together with the system

○ to allow the system to handle other things

○ to allow the system to enter LP mode for a period of timer and then come back to execute the application

Contiki Timer Modules

❖ Contiki has one clock module and a set of timer modules

➢ timer, stimer, ctimer, etimer, and rtimer.

❖ Different timer has different modules

❖ some provide long-running timers with low granularity, some provide a high granularity but with a short range,

❖ some can be used in interrupt contexts (rtimer) others cannot.

❖ Several things that need to be considered in contiki timer

❖ Clock

❖ Granulaty

❖ Clock is the base for the implementation of contiki libraries

Contiki Timer Modules-cont’

❖ The simplest form of timer is timer and stimer

❖ They are just used in the same way stop watch works

❖ Check if time period passed

❖ Application checks the timer for the expiry

❖ To fire a planned action

❖ What is the difference between stimer and timer?

❖ difference between these is the resolution of time:

❖ timers use system clock ticks while

❖ stimers use seconds to allow longer timer periods

❖ What makes stimer and timer different from other timers?

❖ Stimer and timer libraries are safe to be used from the interrupt

❖ Useful for the hardware drivers

Contiki Timer Modules-etimer

❖ etimer library provides event timers

❖ Used to schedule events to Contiki processes after a period of time

❖ Importance:

❖ used in Contiki processes to wait for a time period while the rest of the system can work or enter low power mode.

❖ Essential to conserve power consumption at the sensor node

Contiki Timer Modules-ctimer

❖ It is a call back timer get (call function)

❖ provides callback timers and are used to schedule calls to callback functions after a period of time

❖ Similar to etimer in the same manner of allowing the system to go in LP mode while getting back to the system when the timer period expires

❖ Usage Example

❖ Useful for protocol implementations

❖ Used in rime protocol stack to handle communication timeouts.

Contiki Timer Modules-rtimer

❖ rtimer provides a scheduling of a real time system

❖ rtimer library pre-empt any running Contiki process in order to let the real-time tasks execute at the scheduled time.

❖ Usage Example:

❖ used in time X-MAC implementation where the radio needs to be turned on or off at scheduled times without delay.

Clock module

Clock Module API

Function clock_time()

returns the current system time in clock ticks.

number of clock ticks per second CLOCK_SECOND constant and

CLOCK_SECOND is platform dependent

System time is specified as the platform dependent type clock_time_tFunction clock_seconds()

getting the system time in seconds

Clock Module API-cont’

Functions used in blocking the CPU:clock_delay(), which blocks the CPU for a specified delay

clock_wait(), which blocks the CPU for a specified number of clock ticks

Clock APIs:

clock_time_t clock_time(); // Get the system time.unsigned long clock_seconds(); // Get the system time in seconds.void clock_delay(unsigned int delay); // Delay the CPU. void clock_wait(int delay); // Delay the CPU for a number of clock ticks.void clock_init(void); // Initialize the clock module. CLOCK_SECOND; // The number of ticks per second.

Timer module

Contiki timer library

Setting, resetting and restarting timers, and for checking if a timer has expired

It is done manually so the user should write this in his application

Timer uses clock_time() in the clock module to check the time in the system

Timer’s API:

void timer_set(struct timer *t, clock_time_t interval); // Start the timer.void timer_reset(struct timer *t); // Restart the timer from the previous expiration time.void timer_restart(struct timer *t); // Restart the timer from current time. int timer_expired(struct timer *t); // Check if the timer has expired.clock_time_t timer_remaining(struct timer *t); // Get the time until the timer expires.

Example showing how a timer can be used to detect timeouts

#include "sys/timer.h"static struct timer rxtimer;void init(void) { timer_set(&rxtimer, CLOCK_SECOND / 2);} interrupt(UART1RX_VECTOR) uart1_rx_interrupt(void){ if(timer_expired(&rxtimer)) {/* Timeout */ /* ... */ }timer_restart(&rxtimer); /* ... */ }

Stimer Library

Stimer Library

Similar to timer library

Uses seconds instead of ticks

Allow longer expiration times

Uses clock_seconds() from the clock module

Stime API :

void stimer_set(struct stimer *t, unsigned long interval); // Start the timer.void stimer_reset(struct stimer *t); // Restart the stimer from the previous expiration time.void stimer_restart(struct stimer *t); // Restart the stimer from current time. int stimer_expired(struct stimer *t); // Check if the stimer has expired. unsigned long stimer_remaining(struct stimer *t); // Get the time until the timer expires.

Etimer Library

Etimer Library

Provides a timer mechanism that generate timed events

Event timer will post event to PROCESS_EVENT_TIMER when the timer expires

Use clock_time() in the clock module to get the current system time

Timer event is sent to the Contiki process used to schedule the event timer

Etimer Library API

void etimer_set(struct etimer *t, clock_time_t interval); // Start the timer.void etimer_reset(struct etimer *t); // Restart the timer from the previous expiration time.void etimer_restart(struct etimer *t); // Restart the timer from current time. void etimer_stop(struct etimer *t); // Stop the timer.int etimer_expired(struct etimer *t); // Check if the timer has expired.int etimer_pending(); // Check if there are any non-expired event timers.clock_time_t etimer_next_expiration_time(); // Get the next event timer expiration time.void etimer_request_poll(); // Inform the etimer library that the system clock has changed.

Example of setting up events to run every one second

#include "sys/etimer.h“

PROCESS_THREAD(example_process, ev, data) {

static struct etimer et; PROCESS_BEGIN();

/* Delay 1 second */etimer_set(&et, CLOCK_SECOND);

while(1) {

PROCESS_WAIT_EVENT_UNTIL(etimer_expired(&et)); /* Reset the etimer to trig again in 1 second */

etimer_reset(&et); /* ... */

}

PROCESS_END(); }

Porting the Etimer Library

Implemented in core/sys/etimer.c

platform independent but requires callback to etimer_request_poll() for handling the event timers

So this allows the etimer library to wakeup the system from low power mode when an event timer expires.

It provide three important functions:

etimer_pending()

to check if there are any non-expired event timers.

etimer_next_expiration_time()

Get the next event timer expiration time.

etimer_request_poll() : it is safe to call this function from the interrupt

Inform the etimer library that the system clock has changed and

that an etimer might have expired.

Ctimer Library

Ctimer Library

Provides a timer mechanism that calls a specified function when a callback timer expires.

Ctimer APIs are similar to etimer except

ctimer_set() takes callback function pointer and a data pointer as arguments

When ctimer expires

call the callback function with the data pointer as argument.

Porting the Ctimer Library

The ctimer library is implemented using the etimer library and no further porting is needed.

Ctimer Library API:

void ctimer_set(struct ctimer *c, clock_time_t t, void(*f)(void *), void *ptr); // Start the timer.void ctimer_reset(struct ctimer *t); // Restart the timer from the previous expiration time.void ctimer_restart(struct ctimer *t); // Restart the timer from current time. void ctimer_stop(struct ctimer *t); // Stop the timer. int ctimer_expired(struct ctimer *t); // Check if the timer has expired.

Setup a ctimer to call a function once per second:

#include "sys/ctimer.h"

static struct ctimer timer; static void callback(void *ptr) { ctimer_reset(&timer);

/* ... */} void init(void) {ctimer_set(&timer, CLOCK_SECOND, callback, NULL);

}

Rtimer Library

Rtimer

Provides scheduling and execution of real-time tasks (with predictable execution times

Uses its own clock module for scheduling to allow higher clock resolution

RTIMER_NOW() :

To get the current system time in ticks

RTIMER_SECOND

specifies the number of ticks per second.

Distinguishing feature:

real-time tasks pre-empt normal execution for the task to execute immediately.

To be on the safe side

process_poll() is used for interrupt-safe funtions

Rtimer necessary functions

rtimer_arch_init() is called by the rtimer library

to initialize the rtimer architecture code

rtimer_arch_now() is used

to get the current rtimer system time.

rtimer_arch_schedule() is used

to schedule a call to rtimer_run_next() at a specific time

takes one time argument, wakeup_time (used as the requested time for a wakeup callback)

Implemented in core/sys/rtimer.c

RTIMER_CLOCK_LT(a, b); // This should give TRUE if 'a' is less than 'b', otherwise false.RTIMER_ARCH_SECOND; // The number of ticks per second.void rtimer_arch_init(void); // Initialize the rtimer architecture code.rtimer_clock_t rtimer_arch_now(); // Get the current time.int rtimer_arch_schedule(rtimer_clock_t wakeup_time); // Schedule a call to <tt>rtimer_run_next()</tt>.

Conclusions

Contiki contains a set of timer libraries that are used both by core Contiki modules and applications.

The timer libraries are used to detect timeouts as well as schedule process events and function callbacks

to allow the system to work with other things,

or enter low power mode, for a time period before resuming execution