Writing Contiki Programs

Here I write down some simple instructions on how to program WSN motes on the Contiki operating system platform. If you are familier with C programming even for a little bit, you can write programs for Contiki operating system easily after learning the basics which are specific to Contiki operating system. After writing the very first Contiki program, most of the convensions that we have to follow will be clear.

As I have mentioned in a previous post, the most exiting thing we can find as a WSN programmer is the proto-threads in Contiki. Proto-threads allow us to write multi-threaded applications on top of the Contiki operating system. Therefore we can get rid of writing codes to implement state machines to run on the event driven kernel. The below program is the most simplest Contiki program you can write which contains most of the necessary components that should be included in any Contiki program.

1:  #include "contiki.h"  
2:  #include <stdio.h>   
3:  PROCESS(my_first_process, "Hello World Process");  
4:  AUTOSTART_PROCESSES(&my_first_process);  
5:  PROCESS_THREAD(my_first_process, ev, data)  
6:  {  
7:   PROCESS_BEGIN();  
8:   printf("Hello WSN World!\n");  
9:   PROCESS_END();  
10:  }   

Save this file as hello_world.c
The header file "contiki.h" which is included at the very first contains all the declarations of the Contiki operating systems abstractions. stdio.h is included only because I have used printf() function inside the program. The Macro in third line declares a new Contiki process. First parameter of it is the variable for the process and the second parameter is a string name for the process. Fourth line specify that this process should be started in the startup of the Contiki operating system. Therefore when the hardware device which will be the destination of compiled code switches on, our process also begins running.

Fifth line of the code opens the definition of our process. As the first parameter, we pass the process' variable which is my_first_process in this scenario. The second parameter is 'ev' which is the event parameter. It can be used to make the program responding to events that occur in the system. The third parameter 'data' can be used to receive some data which are coming with those events.

The rest of the instructions of the Contiki process will be included inside two important lines which are  PROCESS_BEGIN() and PROCESS_END(). In our Contiki process we just print a string. This output goes to the standard output in the platform where our code will be running. If you compile this code to native platform and run in the terminal, the output will be printed in the terminal. If you run this in a mote, the output most probably will goto the UART port of the mote. However this behavier depends on the design of a particular WSN mote.

Now we have a Contiki program with us. To compile it, we need a Makefile which contains the instructions for the compilation tools to do the task. Therefore create a new file with your text editer and put the below content in it. Save it as Makefile. No file extention needed for it.

1:  CONTIKI=../contiki-2.4  
2:  include $(CONTIKI)/Makefile.include  

Lets compile our code. Before everything you have to have downloaded the Contiki source code. So, goto here and download the latest Contiki source code. Uncompress the zipped file and place in some where in your PC. First we compile the code to native platform. For that, do the following steps.

1) Put the hello_world.c and Makefile files in a new directory. Lets say you place them in a directory named "my_app". 

2) In the first line of your Makefile, put the correct path to the directory where your downloaded and unzipped Contiki source code resides. As an example if your Contiki source code is located in the path "/home/aps/Desktop/contiki-2.4", your first line of the Makefile should look like below.

1:  CONTIKI=/home/aps/Desktop/contiki-2.4  

You don't have to give absolute paths always. It's ok to give relative paths also.

3) Now goto "my_app" directory from the terminal and issue the following commands,

make TARGET=native hello_world

./hello-world.native

If everythings ok, terminal will give an output like this,
Starting Contiki
Hello WSN World!

4) To stop running Contiki, give a CTRL + C on the terminal.

As I have mentioned previously, compiling to the native platform is the simplest way. But I assume that you have real hardware also to test this. Lets say you have a MSB430 motes. Put the batteries to it and switch on. Plug it to your PC with the serial cable provided with the motes. Now goto "my_app" directory from the terminal and issue the following commands,

sudo chmod 777 /dev/parport0

make TARGET=msb430 hello_world.u

Now the compiled code will be written to the flash memory of the MSB430 mote. After it completed writing to flash, remove the mote from the serial cable. Actually as soon as the flash memory writing is complete, Contiki OS will be running with your application on the mote. But you can't see the output it generates on it's pins. To see it, connect the mote with the provided USB cable to the PC. Now open a termianl and issue the following command.

ls /dev/

Check whether there's a device in the listed output named something like ttyUSB0 or ttyUSB1. Lets say it's ttyUSB0. This is the mote that is connected to your PC. So, issue this command now. 

cat /dev/ttyUSB0

Terminal will now hang and listen to any output coming from there. Switch off the mote and on again. You will see the output from the terminal now. The way we connect different types of motes to the PC are different. But the command you issue in the terminal to compile and upload the Contiki source differ only from very small things. When you compile this application to the MicaZ motes, the command you issue will be,

make TARGET=micaz hello_world.upload PORT=/dev/ttyUSB0

Now you have a basic understanding on writing programs for Contiki. You can find more code examples in the 'examples' directory of the Contiki source code. If you don't have real sensor network hardware to run and test Contiki applications you write, you have another way to fulfill your requirement. There are Simulators for that purpose. Some simulators are instruction level simulators like MSPSIM and Avrora while some simulators are network level simulators like Cooja. I'll write about how to use these simulators for testing our Contiki programs later.