Skip to content
Permalink
main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

rwanda-summer-school-2022/01-install-contiki.org

Go to file
 
 
Cannot retrieve contributors at this time
Install Contiki-NG Overview Many options for installing Contiki-NG Check that virtualisation is turned on Starting the Contiki-NG install Installing git under Windows What is VirtualBox? What is Vagrant? Download contiki-ng This will download a copy of the contiki repository: Check for correct line endings using od Step 2 starting the VM Step 3 login to the VM using SSH Step 4 run the bootstrap script Step 5 reboot the VM Step 6 log back in and try it out Step 7 set-up X windows Step 8 make sure you have all the submodules Step 9 make sure you are running Java 11 Step 10 create a new simulation Step 11 try out the simulator (optional) Send us the proof! Summary
335 lines (258 sloc) 12.8 KB
Raw Blame
Open in GitHub Desktop

Install Contiki-NG

Overview

By the end of this tutorial, you should be able to:

  • Create a virtual machine instance for Contiki-NG
  • Run a basic hello-world program under Contiki-NG
  • Run Contiki-NG’s graphical network simulator

Note: these instructions assume that you are running MS-Windows (the install is much easier under Linux or MacOSX and the default instructions are sufficient).

Many options for installing Contiki-NG

Here are some of them:

  1. Install a dual-boot GNU/Linux system (e.g., Ubuntu) (native toolchain)
  2. Install under Docker
  3. On Windows, install a virtual machine and install Ubuntu then install on that
  4. Use Vagrant to help with installing on a virtual machine

We go with option 4 as it allows us to use an up-to-date Contiki-NG but simplifies some of the install issues.

Please do NOT install InstantContiki as this is an older version of Contiki with slightly different behaviour.

Check that virtualisation is turned on

Before you start, check that virtualisation is turned on

  • See https://bce.berkeley.edu/enabling-virtualization-in-your-pc-bios.html
  • Virtualization is needed for the virtualbox to run normally but some laptop manufacturers turn it off by default.
  • If you skip this step, you might see errors when you try to start Ubuntu.
  • For example, it might suggest you enable PAE/NX (but don’t do this!).

    If you have a 64-bit CPU, PAE/NX shouldn’t be needed and if you don’t, you should instead switch to using a 32-bit version of Ubuntu by changing the Vagrantfile.

Starting the Contiki-NG install

Installing git under Windows

  • Please read this next bit carefully
  • Unless you have a 32 bit machine, download the 64 bit version
  • At section Configuring the line ending conversions
    • Select “Check-out as-is, commit as-is”

What is VirtualBox?

  • VirtualBox allows you to run Virtual Machines (VMs) hosted underneath your current operating system
  • The guest operating system (inside the VM) thinks it has full access to a whole computer
  • In fact, some parts are substituted
    • e.g., a host file contains the guest’s `hard-disk’
  • Some parts are provided optionally
    • e.g., access to USB ports
  • Often, the VM is run `headless’, which means it’s not given a display

What is Vagrant?

  • Vagrant is an open-source software configuration management tool written in Ruby
  • Vagrant’s configuration for a particular development environment sits in a file called Vagrantfile
  • Vagrant is controlled by command line instructions
  • vagrant -h to get a list of commands (such as vagrant up)
  • vagrant up -h to get specific help on the up sub-command

Download contiki-ng

To clone contiki-ng, from the start menu run Git bash prompt

(Note: the default font for Git bash is really small. Click on the top-right corner icon and then Options... to change to a bigger font).

git config --global core.autocrlf false
git config --global core.eol lf
git clone https://github.com/contiki-ng/contiki-ng.git

This will download a copy of the contiki repository:

Cloning into 'contiki-ng'...
remote: Enumerating objects: 29, done.
remote: Counting objects: 100% (29/29), done.
remote: Compressing objects: 100% (23/23), done.
remote: Total 129899 (delta 8), reused 13 (delta 5), pack-reused 129870
Receiving objects: 100% (129899/129899), 76.77 MiB | 6.65 MiB/s, done.
Resolving deltas: 100% (95688/95688), done.

Check for correct line endings using od

od -c ./contiki-ng/tools/vagrant/bootstrap.sh | head -2

which should yield something like:

$ od -c ./contiki-ng/tools/vagrant/bootstrap.sh | head -2
0000000    #   !   /   u   s   r   /   b   i   n   /   e   n   v       b
0000020    a   s   h  \n  \n   #       I   n   s   t   a   l   l       i
  • If all is well, you should see \n and not \r\n. If you get a problem at this stage, and you need to re-clone your contik-ng directory, remove it first using rm -rf contiki-ng, and then start again from the git config ... above.

Step 2 starting the VM

The next step will download the guest operating system (Ubuntu) and start it inside a VM

Need to change to the correct directory first! (Hint: look under contiki-ng/tools/vagrant. Vagrant commands should be issued from a directory containing a file called Vagrantfile.)

cd contiki-ng/tools/vagrant
vagrant up

yielding …

Bringing machine 'default' up with 'virtualbox' provider...
==> default: Box 'ubuntu/bionic64' could not be found. Attempting to find and install...

vagrant plugin install vagrant-vbguest
  • reload the VM to shut it down and restart to get this to take effect 
    vagrant reload

If you see mounting shared folders in the messages after the reload this is a good sign!

Step 3 login to the VM using SSH

vagrant ssh

…

vagrant@ubuntu-bionic:~$
  • at this point, this is a vanilla Ubuntu image
  • vagrant sets up a share between the guest and host
    • that means that both your host operating system (e.g., Windows) and the guest (Ubuntu) will be able to access the same files although the folder path may be different

Step 4 run the bootstrap script

From the vagrant@ubuntu-bionic:~$ prompt:

sudo ./contiki-ng/tools/vagrant/bootstrap.sh
  • sudo tells the command to run with root privileges

Step 5 reboot the VM

First exit out of the Ubuntu using exit and then issue vagrant reload to reboot the VM:

vagrant@ubuntu-bionic:~$ exit
...

$ vagrant reload
  • Check to see that it comes up ok and in particular watch for this …
==> default: Mounting shared folders...
  • If shared folders are not mounted then you won’t be able to run the next step.

Step 6 log back in and try it out

https://github.com/contiki-ng/contiki-ng/wiki/Tutorial:-Hello,-World!

The following need to be run from with the VM (i.e., the prompt after vagrant ssh)

cd contiki-ng/examples/hello-world/
make TARGET=native
./hello-world.native

You should get the following output:

[WARN: Tun6      ] Failed to open tun device (you may be lacking permission). Running without network.
[INFO: Main      ] Starting Contiki-NG-release/v4.6-54-g425587de4
[INFO: Main      ] - Routing: RPL Lite
[INFO: Main      ] - Net: tun6
[INFO: Main      ] - MAC: nullmac
[INFO: Main      ] - 802.15.4 PANID: 0xabcd
[INFO: Main      ] - 802.15.4 Default channel: 26
[INFO: Main      ] Node ID: 1800
[INFO: Main      ] Link-layer address: 0102.0304.0506.0708
[INFO: Main      ] Tentative link-local IPv6 address: fe80::302:304:506:708
[INFO: Native    ] Added global IPv6 address fd00::302:304:506:708
Hello, world
  • Press Ctrl-C to exit
  • The network errors are normal when running natively.
  • To edit the Hello, World code with the nano editor, use 
    nano contiki-ng/examples/hello-world/hello-world.c

    Note that you can also edit using a Windows text editor, such as Visual Studio Code but you may prefer open source alternatives, such as Spacemacs.

Step 7 set-up X windows

  • Cooja is Contiki-NG’s network simulator
  • While compiling Contiki-NG doesn’t require a windowing display, Cooja does
  • We follow the instructions at: https://github.com/contiki-ng/contiki-ng/wiki/Vagrant#provision-a-vm-with-a-desktop-environment
  • For the next step, you can use the nano editor to edit contiki-ng/tools/vagrant/Vagrantfile
  • Remember to use the arrow keys and not the mouse when editing with nano.
  • Adjust the Vagrantfile to uncomment (remove the # character) for four lines so that it looks like this: 
    config.vm.provider "virtualbox" do |vb|
  # Display the VirtualBox GUI when booting the machine
  vb.gui = true
  vb.memory = 1024
end
  • On the vagrant ssh shell, run the bootstrap script for setting up X packages
./contiki-ng/tools/vagrant/bootstrap-vbox-with-x.sh
  • Reboot after the install 
    vagrant reload
  • I found that this added some virtualbox-guest packages which were then removed by vagrant’s vbguest plugin. If so, you may find that another vagrant reload is required.
  • You now need to login on the VirtualBox window that comes up after the reboot. The username should be vagrant with the password vagrant.
  • To get X running, you can just run startx on the command line after logging in on the gui window.

Note: at this stage, some people end up using sudo startx (WARNING! DO NOT DO THIS!), which (a) is not needed and (b) means that everything then has to run under the root user. If you have a problem with permissions at this stage, read the messages carefully and try to resolve the specific problems. To resolve (ONLY IF YOU NEED TO) use the following find command

sudo find . -user root -exec chown vagrant:vagrant {} \;

Step 8 make sure you have all the submodules

  • You may need to download the cooja submodules if you haven’t already 
    cd ~/contiki-ng
git submodule update --init --recursive

Step 9 make sure you are running Java 11

For some reason, the vagrant image forces Java 8 but currently this produces errors due to missing jni.h, possibly since the newer build.xml points to release 11.

The good news is that Java 11 appears to work. To set this up do the following:

sudo update-java-alternatives --auto

Ignore the error about the Mozilla plugin.

Now revise the JAVA_HOME in your profile settings with the following command:

sed -i "s/java-1.8.0-openjdk-amd64/default-java/" ~/.bashrc

To ensure this takes effect, type exit to close the window and start a new terminal window, then:

echo $JAVA_HOME
javac -version
java -version

which should give:

vagrant@ubuntu-bionic:~$ echo $JAVA_HOME
/usr/lib/jvm/default-java
vagrant@ubuntu-bionic:~$ javac -version
javac 11.0.15
vagrant@ubuntu-bionic:~$ java -version
openjdk version "11.0.15" 2022-04-19
OpenJDK Runtime Environment (build 11.0.15+10-Ubuntu-0ubuntu0.18.04.1)
OpenJDK 64-Bit Server VM (build 11.0.15+10-Ubuntu-0ubuntu0.18.04.1, mixed mode, sharing)

Step 10 create a new simulation

Follow the tutorial listed here: https://github.com/contiki-ng/contiki-ng/wiki/Tutorial:-Running-Contiki%E2%80%90NG-in-Cooja

Note that the instructions ask you to cd tools/cooja but you may need to cd contiki-ng first.

figures/cooja-new-sim.png

Step 11 try out the simulator (optional)

RPL is the Routing Protocol for Low power and Lossy Networks

Follow the instructions at: https://github.com/contiki-ng/contiki-ng/wiki/Tutorial:-running-a-RPL-network-in-Cooja

figures/cooja-rpl-udp.png

Send us the proof!

  • The final step is to send us proof that your install is working.
  • Modify hello-world.c to do something different so we can be sure it’s you.
  • You could:
    • Write out your name
    • Include the clock_time() (see the documentation) in the printed output
    • Write out a counter that increments
  • Either compile using the native target and do a screenshot of it running in a terminal
  • OR run it under Cooja and get a screenshot showing the Mote output window
  • Submit to https://forms.gle/JApFhSKfcD46dTgh6

Summary

  • We’ve covered installing Contiki from scratch and getting a hello world program running
  • If you’ve completed everything successfully, don’t forget to submit your hello world screenshot for assessment.