An Introduction to Cooja
From ContikiWiki
TODO: needs updating and cross-checking for version 2.5
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 (http://www.sics.se/contiki) since version 2.0. In the Contiki source tree, COOJA resides in
- //tools/cooja//
> Simulator code (Java)
- //platform/cooja//
> Native platform with glue drivers used by COOJA.
Contents |
[edit] 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.
[edit] 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 kind 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 of 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.
[edit] 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 contiki-2.x/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//.
[edit] 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 > Compiler 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
[edit] Create a Hello World simulation
After completing the configuration wizard, we are now ready to create a simulation.
- Open //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 //Mote Types > Create mote type > Contiki 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.
- Enter **10** and click **Create and Add**
You may later add further motes of this type by menu //Menu > Motes > Add motes of type >// //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.
[edit] 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//
- 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 >// //File > Reload simulation > same random seed//
[edit] 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 (i.e. //contiki-2.x/examples/myproject///), or external to Contiki (i.e. ///home/user/mycontikiproject//).
COOJA's 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 CVS.
- 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 where the configuration file is stored.
[edit] 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
- ///home/user/mycontikiproject///> **make mysimconfig.csc TARGET=cooja**
[edit] Feature requests, bug reporting, and questions
Questions and requests should normally be posted to the main Contiki developers mailing list: contiki-developers@lists.sourceforge.net. See the Contiki website for information of how to subscribe to this list. You may also mail me directly, Fredrik Österlind, fros@sics.se.
