Develop your first application

From ContikiWiki

This tutorial shows how to develop a simple Contiki program and how to set up a Contiki project. We go through how to create a project directory, write a simple Contiki application, compile and run it in the MSPsim emulator, and on a Tmote Sky mote. If you don't have a Tmote Sky mote available, it is enough to read how to run the application in emulation.

In its simplest form, a Contiki project is a C source file and a Makefile. The C source file contains the program code whereas the Makefile contains the rules for compiling the program code into a Contiki executable.

We assume that we are using Instant Contiki and that we have already logged into the system.

Contents 1 Step 1: Create a project directory 2 Step 2: Create the Makefile 3 Step 3: Create the program file 4 Step 4: Set the default target 5 Step 5: Compile the project 6 Step 6: Test the project in MSPsim 7 Step 7: Run the project on Tmote Sky hardware

[edit] Step 1: Create a project directory

Each Contiki project resides in its own project directory. We first create the directory in a convenient location. Open a terminal by clicking on the terminal icon on the menu bar at the top of the screen.

Create two directories: one for holding Contiki projects, and one for holding the Hello, World project. Do this by issuing the following commands (if you choose to use different directories change the paths accordingly):

mkdir projects
cd projects
mkdir hello-world-project
cd hello-world-project

[edit] Step 2: Create the Makefile

Once we have created our project directory, we can create the Makefile that will ensure the program is compiled correctly. Creating the Makefile can be done in any of the available editors (gedit, vi, emacs, …). In this example, we use gedit. Issue the command

gedit Makefile &

We type the following text into the Makefile:

CONTIKI=/home/user/contiki-2.x
include $(CONTIKI)/Makefile.include

For Contiki 2.5 you should use:

CONTIKI=/home/user/contiki
include $(CONTIKI)/Makefile.include

Save the file by clicking on the Save button. The Makefile will include the Contiki Make structure and automatically compile your project. We can now start writing our first program.

[edit] Step 3: Create the program file

We have now finished creating the Makefile. Next, we create out main program file by creating a new document called "hello-world.c". If you are using gedit, click on the New document menu item in the File menu.

Now we have to populate our program file by typing the following:

#include "contiki.h"

PROCESS(hello_world_process, "Hello world process");
AUTOSTART_PROCESSES(&hello_world_process);

PROCESS_THREAD(hello_world_process, ev, data)
{
  PROCESS_BEGIN();
  printf("Hello, world!\n");
  PROCESS_END();
}

We will briefly outline what this actually does:

• The first line includes the Contiki C header. This is needed to include all the relevant Contiki definitions and libraries.

• The second line declares a Contiki process. This process has a variable name (hello_world_process), and a string name ("Hello world process"). The string name is used in debugging and for the Contiki shell's ps command.

• The third line tells Contiki that the hello_world_process should be automatically started when Contiki boots.

• The fourth line defines the hello_world_process. The ev and data arguments to the PROCESS_THREAD() macro are the variable names that hold the event number and the event data for subsequent events that this process may receive.

• The process itself is defined between the PROCESS_BEGIN() and PROCESS_END() macros. In this case, the process only prints out the hello, world message and exits.

This should all look somewhat like this:

We save this as hello-world.c:

[edit] Step 4: Set the default target

We switch to the terminal window. We first set the default platform for this project to the sky target by issuing the command

make TARGET=sky savetarget

[edit] Step 5: Compile the project

Now we can compile our new project for the first time. We do this by issuing the command

make hello-world

This will cause the entire Contiki system to be compiled and a lot of compilation output to be produced in the terminal window. When compilation has finished, the terminal window looks like this:

[edit] Step 6: Test the project in MSPsim

We can now run the Hello, world program in MSPsim by running

make hello-world.mspsim

This brings up a number of windows. You may need to rearrange the windows to see what is going on:

The USART1 Port Output window shows the output from the serial port of the mote. We see the Contiki boot-up messages as well as our Hello, world message.

The SkyGui window shows the Tmote Sky mote. The reset and user buttons can be pressed by clicking on them. We press the reset button to see the output:

The boot-up messages and our Hello, World message shows up again in the serial port window.

We stop the simulation by bringing up the terminal window, hold the Ctrl key, and press the C key.

[edit] Step 7: Run the project on Tmote Sky hardware

Insert a Tmote Sky mote into the USB port of the PC. We now have to configure VMware Player to access the Tmote Sky. This is done through the Virtual Machine menu as shown below:

The Tmote Sky should now be accessible from within Instant Contiki. Test this by running

make sky-motelist

If the Tmote Sky shows up, it is possible to reprogram it with the Hello, World application:

make hello-world.upload

This will upload Contiki and the Hello, World program to the Tmote Sky mote.

When the programming is complete, Contiki and the Hello, world program should now be running on the Tmote Sky. See the output of the Tmote Sky by running

make login

In VMware garbage characters may sometimes appear at this point:

To see the Hello, world program in action, we press the reset button on the Tmote Sky. The following output should appear:

Congratulations! A complete Contiki project now runs on your Tmote Sky mote!

Hold the Ctrl key and press C to get back to the prompt.