Today we are going to explain how to start developing with Contiki using OpenMote hardware. To follow this tutorial you will need the following materials:
- Computer running GNU/Linux
- OpenMote bronze kit (available at our shop for 200€)
- Segger ARM J-Link (available at Mouser for 48€)
- ARM-JTAG-20-10 adapter (available at Olimex for 4.95€)
- GitHub account
First of all, we assume that you are using a Debian-based operating system. In particular we provide instructions for the latest long-term support release of Ubuntu (14.04 LTS), which was released in May 2014. However, installation in other Debian-based distributions, e.g. Debian itself, should be similar if not equal. We are also aware that the whole process is available in Windows and MacOS X, since all the tools that we use are available for such operating systems, but at the moment we do not provide instructions for them. Alternatively you can download Instant Contiki
, a virtual machine for VMWare Player
that contains the operating system (Ubuntu) and all the software required to follow this tutorial. The password is user
. Assuming that you have a working GN/Linux based on Ubuntu, start by installing the tools to cross-compile C/C++ code for ARM microcontrollers. The tools are not available in the default Ubuntu repositories but are available through PPA repositories. Open a terminal and type the following commands.
sudo add-apt-repository ppa:terry.guo/gcc-arm-embedded
sudo apt-get update
sudo apt-get install gcc-arm-none-eabi gdb-arm-none-eabi
In addition take into account that, at the moment of writting this article, the gdb-arm-none-eabi
packet is broken in Ubuntu 14.04 LTS since it conflicts with the standard GCC tools. In order to be able to install the package it you will need to issue the following command. Hopefully the issue will be resolved soon and this will no longer be needed.
sudo dpkg --install --force-overwrite /var/cache/apt/archives/gdb-arm-none-eabi_188.8.131.5231218-0ubuntu1+1_amd64.deb
To load code and debug you will also need to download and install the latest version of the Segger J-Link drivers for GNU/Linux. At the time of writing the latest version of Segger J-Link is 4.84.6. For Debian-based distributions you can download the DEB package for 32 bits
or 64 bits
systems from the Segger website. There are versions for Fedora-based distributions (RPM package), as well as for Windows (EXE) and MacOS X (DMG). To download the software you will need to provide the serial number of your Segger J-Link probe or confirm that you do not have a pirate probe version. Once the download is complete move to the appropriate folder. To install de DEB package just type the following command and follow the onscreen instructions. Notice that we are using the 64 bit version and that by default the software installs to the /opt/SEGGER/JLink
sudo dpkg --install jlink_4.84.6_x86_64.deb
Finally, you will need two additional packages: git
. First, git
in order to be able to clone the Contiki repository from GitHub to your computer. Second, putty
to be able to communicate with the OpenMote-CC2538 through a serial port. You can install both packages issuing the following commands in a terminal.
sudo apt-get install git putty
Now that you have all the tools required to compile, load and debug code for ARM microcontrollers, we need to obtain the Contiki source code. To do that, go to GitHub
and create an account
if you do not have one already. After that, go to the Contiki repository in gitHub
and create a repository that forks it, as displayed below (top right corner).
Once you have forked the Contiki repository into your GitHub account you need to clone it into your computer by issuing:
git clone https://github.com/username/contiki.git ~/Contiki
If you plan on contributing to Contiki you can also add the original Contiki repository
as an upstream tracking branch in git
. That way you will be able to integrate changes in the Contiki main branch into your own Contiki branch, as well as contribute your changes back to the Contiki main branch by creating a pull request. To do so issue the following commands in a terminal:
git remote add upstream https://github.com/contiki-os/contiki.git
git fetch origin -v
git fetch upstream -v
git merge upstream/master
Now that you have the Contiki source code in your computer is time to compile it. Let's start with a simple "Hello World" project. Issue the following commands on a terminal:
make TARGET=cc2538dk hello-world
The first command changes the current directory to the Contiki directory where the "Hello World" project resides. The second command triggers the compile of the whole Contiki operating system using its Makefile-based build system.
After a certain ammount of time you will see that various files have been compiled and the binaries for the CC2538 generated, as depicted next.
Now that the code is compiled you need to upload it to the OpenMote. Prior to that make sure that the OpenMote is connected to the OpenBase and that the OpenBase is connected to the computer via the USB_FTDI USB port. Also make sure that the OpenBase on/off switch is in the USB_FTDI position. If so, you should see a green led on the OpenBase lighting. Next, make sure that the Segger J-Link is connected to the computer and connected to the OpenBase using the ARM-JTAG-20-10 adapter, as depicted next.
Once everything is properly connected you need to open a new terminal and start the Segger GDB Server by issuing the following command:
/opt/Segger/JLink/JLinkGDBServer -device CC2538SF53
This command executes the JLinkGDBserver to debug a CC2538SF53 device, which is the one we use for the OpenMote-CC2538
board. It is mandatory to include the "-device CC2538SF53
" parameter since the Segger JLink needs to configure the CC2538 chip for standard JTAG operation (4 wire) instead of the new cJTAG (2 wire). You should see a dialog similar to the one depicted next where the JLinkGDBServer waits for a connection from the GDB client.
Once the Segger JLinkGDBServer is connected to the target device you need to go back to the other terminal and issue the following command:
After issuing this command you should see a window like the following. Here GDB is waiting for you to input the commands to load the target code and start debugging.
Once GDB is executing, issue the following commands one by one in the GDB window:
target remote localhost:2331
monitor interface jtag
monitor speed 5000
monitor endian little
monitor flash download = 1
monitor flash breakpoints = 1
This commands are responsible for configuring the GDB client to talk to the GDB server (the one executing in the other terminal) and loading the "Hello World" machine code compiled for the CC2538 (located in the hello-world.elf
file) to the OpenMote. At this point you should see the code loading to the OpenMote, as depicted next.
Each command that you execute in the GDB client reflects in the GDB server, as depicted next.
Once the code has been successfully loaded into the OpenMote-CC2538 board, launch PuTTY and open the appropriate serial port, probably under the name of /dev/ttyUSBX
. In our case the serial port is under /dev/ttyUSB0
, as depicted next. The default serial parameters are 115200 bps, 8 bits, no parity, 1 stop bits and no flow control. In addition, remember that to be able to open the serial port PuTTY will need super user privileges (hint: use sudo
Once the code has been successfully loaded and PuTTY is connected to the appropriate serial port press the reset button on the OpenMote. You will see three leds fade shortly and a "Hello world" message will be sent through the serial port, as shown next.
And that's it, congratulations! You have successfully compiled Contiki and loaded into the OpenMote. In following tutorials we will show how to compile and run more advanced examples.