[[Contiki_tutorials | Back to Contiki Tutorials]]

__TOC__

== Introduction ==

Timers can be used to control periodic tasks as well as implement sophisticated algorithms. The implementation of each type of timer is platform-dependent and has different properties that make them useful in specific situations; some timers have low granularity (seconds) and overflow once in tens of years, and others provide high granularity (microseconds), but overflow rapidly. There are 5 types of timers provided by Contiki:

* timer
* stimer
* ctimer
* etimer
* rtimer

== Overview ==

The functions of all types of timers are located inside folder '''core/sys/{timer, stimer, ctimer, etimer, rtimer}.{c,h}'''. A complete documentation of Timers in Contiki can be found [https://github.com/contiki-os/contiki/wiki/Timers here].

The '''timer''' and '''stimer''' are the most basic types of timers and are used to check if a time interval has passed. They do not notice when the time period has elapsed, so the application needs to check periodically if they have expired. The difference between them is the resolution: ''timers'' use system clock ticks, which gives high granularity (order of microseconds) but short overflow periods (order of seconds). On the other hand, ''stimers'' use seconds to allow much longer time periods (order of years), but has lesser granularity.

The '''etimer''' provides event timers and are used to schedule events to the processes after a period of time. They are used in Contiki processes to wait for a time period while the rest of the system can work or enter low power mode.

The '''ctimer''' provides callback timers and are used to schedule calls to functions after a period of time. Like event timers, they are used to wait for some time while the rest of the system can work or enter low power mode. Since the callback timers call a function when a timer expires, they are especially useful in any code that do not have an explicit Contiki process such as protocol implementations.

The '''rtimer''' provides scheduling of real-time tasks. The rtimer library preempts any running Contiki process in order to let the real-time tasks execute at the scheduled time. The real-time tasks are used in time critical codes.

== You will learn ==

*Simple implementations of each type of timer
*Tasks each timer can be used for
*Some functions in the timer libraries.

=== Step 1 ===

Again, we will have to change folders. We will create a new file for this tutorial, but let's create it in the same directory we've been working with, so type

<code><nowiki> cd contiki-2.7/examples/rime </nowiki></code>

into the terminal. For this tutorial, we will be modifying the example-broadcast.c file we have previously used, so type

<code><nowiki> cp example-broadcast.c example-timer.c </nowiki></code>

into your terminal. You should now see a new file, "example-timer.c" in your directory. Open it up with an editor of your choice (we will use gedit for this tutorial):

<code><nowiki> edit example-timer.c </nowiki></code>

=== Step 2 ===

There is currently a working example of an etimer in this code, so before we proceed, let's understand this. At the beginning of the process, it is declared with

<code><nowiki> static struct etimer et; </nowiki></code>

This creates an etimer instance. Within the while loop, it is set with the function

<code><nowiki> etimer_set(&et, CLOCK_SECOND*4 + random_rand() % (CLOCK_SECOND * 4)); </nowiki></code>

This function takes the arguments:

<code><nowiki> etimer_set(struct etimer *et, clock_time_t interval); </nowiki></code>

and sets the etimer et to expire after interval.

After that, we see the line:

<code><nowiki> PROCESS_WAIT_EVENT_UNTIL(etimer_expired(&et)); </nowiki></code>

which tells the example_broadcast_process to pause until it receives an event, so the program is essentially giving up system control. When an etimer expires, it posts a PROCESS_EVENT_TIMER event to the example_broadcast_process. So this tells the process to continue and begin running again, as the etimer has expired, and an event has been posted. Now that we understand what the etimer is doing here, let's incorporate some other timers.

=== Step 3 ===

To start simply, we are going to use a timer to just print out a message once it expires. Just below

<code><nowiki> static struct etimer et; </nowiki></code>

declare a timer with the line:

<code><nowiki> static struct timer t; </nowiki></code>

Before the while loop, set the timer with the line:

<code><nowiki> timer_set(&t, CLOCK_SECOND * 10); </nowiki></code>

This sets the timer to expire after 10 seconds.

Below the line

<code><nowiki> printf("broadcast message sent\n"); </nowiki></code>

add in the code:

<code><nowiki> if(timer_expired(&t)){
printf("Timer expired\n");
}</nowiki></code>

Now, save and run your code on your Tmote Sky by typing into your terminal:

<code><nowiki> make TARGET=sky example-timer.upload </nowiki></code>

If you don't have a Sky, run this code on Mspsim with the line

<code><nowiki> make TARGET=sky example-timer.mspsim </nowiki></code>

Among the "broadcast message sent" messages, you should see a "Timer expired" notice. This only occurs one time, however. This is because we never reset the timer. So, return to your example-timer.c file. Underneath your printf("Timer expired\n") line, add the code

<code><nowiki> timer_reset(&t); </nowiki></code>

This will reset the timer to expire again in 10 * CLOCK_SECONDS. Run your code again. You should now see "Timer expired" every few broadcast messages. Now, say we only wanted to send broadcast messages for 30 seconds. Let's use our timer to exit our process after it expires. Change your original timer_set function to:

<code><nowiki> timer_set(&t, CLOCK_SECOND * 30); </nowiki></code>

Now, just delete the line

<code><nowiki> timer_reset(&t); </nowiki></code>

and replace it with

<code><nowiki> PROCESS_EXIT(); </nowiki></code>

Run your code again, and it should stop after the timer expires. You have now learned some basic functionality of the timer.

=== Step 4 ===

Begin by deleting the

<code><nowiki> PROCESS_EXIT(); </nowiki></code>

line that you previously wrote. We are going to implement a ctimer and no longer want to exit the process. At the beginning of the process, where you declared the other timers, include the code

<code><nowiki> static struct ctimer ct </nowiki></code>

This declares a ctimer, which has the property of calling a function when it expires. In order to do this, we will need to declare a function for it to call! So, just before the start of the process, underneath the line

<code><nowiki> static struct broadcast_conn broadcast; </nowiki></code>

Declare the following function:

<code><nowiki> static void timer_events(void *ptr){
printf("Congratulations, you called this function");
}</nowiki></code>

Now, go back to the process. Just before the while loop, set the ctimer by typing

<code><nowiki> ctimer_set(&ct, CLOCK_SECOND * 5, timer_events, NULL); </nowiki></code>

This set function takes in arguments that tell the ctimer which function to call, as well as what to pass into the function (NULL in this case). Run your code. You will see that your function is called one time, but since we never reset the code, it never gets called again. So, let's reset the ctimer as part of the function. Just before you set the ctimer, include this line:

<code><nowiki> void *ct_ptr = &ct; </nowiki></code>

And change your ctimer_set function to read:

<code><nowiki> ctimer_set(&ct, CLOCK_SECOND * 5, timer_events, ct_ptr); </nowiki></code>

Now go up to your function, and change it to read like this:

<code><nowiki> static void timer_events(void *ptr){
printf("Congratulations, you called this function");
struct ctimer* ct_ptr = ptr;
ctimer_reset(ct_ptr);
} </nowiki></code>

Now run your code again. The function should be called over and over again. The last thing we will do with this function is learn how to terminate the process from the function, using our same ctimer. To begin, change your c_timer set function to

<code><nowiki> ctimer_set(&ct, CLOCK_SECOND * 30, timer_events, ct_ptr); </nowiki></code>

so the process runs longer before we exit it. Now go up to your function and delete the ctimer_reset line. Replace it with:

<code><nowiki> process_exit(&example_broadcast_process); </nowiki></code>

Run your code again. You will see that the example_broadcast_process stops running after 30 seconds, and you have learned how to do this from a function called by a ctimer!

=== Step 5 ===
[[Contiki_tutorials | Back to Contiki Tutorials]]

Timers

2014-03-05T05:53:59Z

Timothy: