Skip to content

An Introduction to Cooja

Jump to bottom
Benoît Thébaudeau edited this page Sep 23, 2019 · 10 revisions

This page contains information about the COOJA network simulator for Contiki. To get most out of the information contained here, the reader should have basic Contiki knowledge: how to use the Contiki build system and how to create simple Contiki processes. COOJA is included in Contiki since version 2.0. In the Contiki source tree, COOJA resides in

  • tools/cooja Simulator code
  • platform/cooja Native platform with glue drivers for Cooja

Table of Contents

The COOJA Simulator

The section gives a high-level overview of sensor network simulations in COOJA. This information is not strictly needed for using COOJA, but may help users to more easily understand problems, limitations, and features in the simulator.

Contiki level: the Contiki Mote Type

A simulated Contiki Mote in COOJA is an actual compiled and executing Contiki system. The system is controlled and analyzed by COOJA. This is performed by compiling Contiki for the native platform as a shared library, and loading the library into Java using Java Native Interfaces (JNI). Several different Contiki libraries can be compiled and loaded in the same COOJA simulation, representing different kinds of sensor nodes (heterogeneous networks). COOJA controls and analyzes a Contiki system via a few functions. For instance, the simulator informs the Contiki system to handle an event, or fetches the entire Contiki system memory for analysis. This approach gives the simulator full control of simulated systems. Unfortunately, using JNI also has some annoying side-effects. The most significant is the dependency on external tools such as compilers and linkers and their run-time arguments. COOJA was originally developed for Cygwin/Windows and Linux platform, but has later been ported to MacOS.

Getting started

Java version 1.6 or later is required to run COOJA. We recommend using the latest version from Sun. In addition, the build tool ant is also required for building COOJA. For Windows users, we recommend using Cygwin. Add the Cygwin binaries path (for example c:\cygwin\bin) to your PATH environmental variable. To compile and start COOJA: 

   cd tools/cooja
   ant run

COOJA builds and the simulator is started. However, before you can simulate a Contiki system, you need to configure COOJA to correctly interface your toolchain.

  • Open menu Settings > External tools paths
This dialog displays your current COOJA configuration: compiler paths and arguments, a bunch of regular expressions used to parse information from these tools, etc. These settings are stored in your home directory: .cooja.user.properties, such as in home/myuser or C:\Documents And Settings\myuser.

Configuration Wizard

(This wizard replaces the old JNI tests in /tools/cooja/examples/jni_tests.) The configuration wizard helps configuring COOJA for using JNI, a challenging task on many systems. The wizard consists of 4 steps and tests compiling, linking, loading libraries, analyzing library memory, and controlling library execution.

  • Open menu Settings > Cooja mote configuration wizard
Complete all 4 steps. Note that you may have to change the recommended settings. Any changes can later be reviewed in the External tools paths dialog. If errors related to jni.h not being found, review the $JAVA_HOME path points to the right files.

Create a Hello World simulation

After completing the configuration wizard, we are now ready to create a simulation.

  • Open menu File > New simulation, and click Create
A simulation without motes and using the default parameters is created. Before adding motes to the simulation, we first need to create a mote type. The mote type determines the type of sensor hardware and which Contiki applications are to be simulated.
  • Open menu Motes > Add Motes > Create new mote type > Cooja Mote Type
A dialog allowing you to configure the new mote type appears.
  • Enter a suitable description: "My first hello world mote type"
  • Click Browse, and select the Contiki Hello World application: hello-world.c
  • Compile the Contiki shared library by clicking Compile
  • When the compilation finishes, load the library and create the mote type by clicking Create.
We have now added a mote type, however, the simulation does not yet contain any simulated motes. In the Add Motes dialog:
  • Enter 10 and click Add motes
You may later add further motes of this type by menu Motes > Add motes > My first hello world mote type. A few plugins are started: a control panel for starting and pausing the simulation, a visualizer that shows the node positions, and a log listener showing printouts of all simulated nodes.
  • Press Start (or CTRL+S) in the Control Panel plugin to start simulating.

Save and load simulations

Cooja allows for saving and loading simulation configurations. A simulation configuration contains the simulated modes and mote types, radio medium configuration, active plugins, etc.

Note that only the configuration, not the state of the simulation is saved. Hence, when a simulation is loaded, the simulation will start over from time 0.

To save the current simulation:

  • Open menu File > Save simulation as
  • Enter suitable name. Configuration files are stored with the file extension .csc
To load a simulation:
  • Open menu File > Open simulation > Browse...
  • Select configuration file to load.
The simulation is loaded, and the plugins will appear after a while. Loading a simulation with several mote types may take some time, since Contiki is recompiled in the background.

A similar functionality as saving and loading simulation, is reloading a simulation. To reload the current simulation:

  • Open menu Simulation > Reload simulation > Reload with same random seed

COOJA configs for Contiki development: sharing simulation configs

When developing Contiki applications, you should normally keep all your code in a project directory. Your project directory may be a subfolder of Contiki (e.g. examples/myproject), or external to Contiki (e.g. /home/user/mycontikiproject).

COOJA leverages the Contiki project directories by storing any simulation's external file references (such as to Contiki applications) relative to the directory where you save the simulation configuration. If you save a COOJA configuration in your project directory, any references to Contiki code residing in that directory will hence be stored as portable relative paths. This feature enables moving and sharing project directories, for example committing Contiki projects to version control.

Example: Contiki path: /home/user/contiki-2.x Contiki project path: /home/user/mycontikiproject Contiki application: /home/user/mycontikiproject/myapp.c

  • Create a COOJA simulation, compile myapp.c and finally save the simulation configuration in the project directory.
COOJA config: /home/user/mycontikiproject/mysimconfig.csc

The Contiki application path will be stored as "[CONFIG]/myapp.c" i.e. relative to where the configuration file is stored.

COOJA configs for Contiki development: simulation quickstart

It is also possible to quickstart COOJA, instead of starting COOJA from the tools/cooja/ directory.

To quickstart COOJA from a Contiki project directory, /home/user/mycontikiproject/: 

   make myapp.cooja TARGET=cooja

or 

   make mysimconfig.csc TARGET=cooja

Commandline options

  • -quickstart=Simulation Load Simulation at startup. This must be the first parameter.
  • -nogui=Simulation Run simulation without gui. This must be the first parameter.
  • -applet Run as applet. Must be the first parameter.
  • -log4j=File Load Log4j-Config from file.
  • -contiki=Path Set Contiki path
  • -external_tools_config=File Set Cooja config file.

Feature requests, bug reporting, and questions

Questions and requests should normally be posted to the main Contiki developers mailing list.

Clone this wiki locally