Skip to content
Yasuyuki Tanaka edited this page Jul 24, 2019 · 27 revisions

We provide a Docker image for Contiki-NG hosted on DockerHub, as contiker/contiki-ng. The Dockerfile can be found in the Contiki-NG repository under tools/docker. As all Continuous Integration tests in Travis are run in a Docker container, it is easy to reproduce the testing environment locally via Docker.

Setup

To get started, install Docker. On Ubuntu for instance (you'll need set up the repository; see install-docker-ce for details):

$ sudo apt-get install docker-ce

Make sure your user is added to the unix group docker:

sudo usermod -aG docker <your-user>

Log out, and log in again.

Download the Contiki-NG image:

$ docker pull contiker/contiki-ng

This will automatically download contiker/contiki-ng:latest, which is the image used in Travis and which we recommend for development. The image is meant for use with Contiki-NG as a bind mount, which means you make the Contiki-NG repository on the host accessible from inside the container. This way, you can work on the codebase using host tools / editors, and build/run commands on the same codebase from the container. If you do not have it already, you need to check out Contiki-NG:

$ git clone https://github.com/contiki-ng/contiki-ng.git
$ cd contiki-ng
$ git submodule update --init --recursive

Then, it is a good idea to create an alias that will help start docker with all required options. On Linux, you can add the following to ~/.profile or similar, for instance, to ~/.bashrc:

export CNG_PATH=<absolute-path-to-your-contiki-ng>
alias contiker="docker run --privileged --mount type=bind,source=$CNG_PATH,destination=/home/user/contiki-ng -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -v /dev/bus/usb:/dev/bus/usb -ti contiker/contiki-ng"

Launching and Exiting

Shell for new container

To start a bash inside a new container, simply type:

$ contiker

You will be under /home/user/contiki-ng in the container, which is mapped to your local copy of Contiki-NG.

Additional shell for existing container

Typing contiker as above will launch a new container. Sometimes it is useful to have multiple terminal sessions within a single container, e.g., to run a tunslip6 on one terminal and other commands on another one. To achieve this, start by running:

$ docker ps

This will present you with a list of container IDs. Select the ID of the container you wish to open a terminal for and then

$ docker exec -it <the ID> /bin/bash

Exit

To exit a container, use exit.

Usage

From the container, you can directly go to an example project and build it (see tutorial:hello-world). It is also possible to run CI tests, e.g.:

$ cd tests/14-rpl-lite
$ make 01-rpl-up-route.testlog
Running test 01-rpl-up-route with random Seed 1.................... OK

You can even start Cooja from the container:

$ cd tools/cooja
$ ant

Or use the shortcut located in the home directory:

$ ~/cooja

Or directly from the host (outside the container)

$ contiker cooja

It is also possible to start a container to just run one command, e.g.:

$ contiker bash -c ls

To run a CI test:

$ contiker bash -c "make -C tests/14-rpl-lite 01-rpl-up-route.testlog"

The user has sudo rights with no password (obviously sandboxed in the container).

On Windows

Prerequisites

Limitations

How to Run

  1. Start VcXsrv (run XLaunch.exe)
  2. Open cmd.exe (you can use PowerShell if you want)
  3. Hit the following command (replace /c/Users/foobar/contiki-ng with a location of contiki-ng local repository in your environment)
C:\> docker run --privileged --mount type=bind,source=/c/Users/foobar/contiki-ng,destination=/home/user/contiki-ng -e DISPLAY="host.docker.internal:0.0" -ti contiker/contiki-ng

Tested with Windows 10, version 1809.

You can run a Docker container from a WSL environment as well:

  1. Prepare /etc/wsl.conf to make WSL mount drives directly under / instead of under /mnt (see this doc for further information)
  2. Place contiki-ng local repository somewhere other than under %LOCALAPPDATA%, for instance, /c/Users/foobar/contiki-ng
  3. Run the following command in a WSL shell
$ docker run --privileged --mount type=bind,source=/c/Users/foobar/contiki-ng,destination=/home/user/contiki-ng -e DISPLAY=host.docker.internal:0.0 -ti contiker/contiki-ng

On macOS

There are two Docker solutions available: Docker for Mac and Docker Toolbox on macOS. Refer to Docker for Mac vs. Docker Toolbox for general differences between the solutions.

If you want to access USB devices from a Docker container, "Docker Toolbox on macOS" is the only choice as of writhing this. "Docker for Mac" doesn't support USB pass-through (https://docs.docker.com/docker-for-mac/faqs/#questions-about-dockerapp).

Without XQuartz

If you don't need to run cooja with its GUI, the setup procedure becomes simple:

  1. install "Docker for Mac" or "Docker Toolbox on macOS"
  2. prepare contiker alias
  3. run contiker: $ contiker bash

contiker alias you need is slightly different depending on your Docker solution. Note you need CNG_PATH definition as mentioned above.

for "Docker for Mac"

export CNG_PATH=<absolute-path-to-your-contiki-ng>
alias contiker="docker run                                                           \
               --privileged                                                          \
               --mount type=bind,source=$CNG_PATH,destination=/home/user/contiki-ng  \
               -ti contiker/contiki-ng"

for "Docker Toolbox on macOS"

export CNG_PATH=<absolute-path-to-your-contiki-ng>
alias contiker="docker run                                                           \
               --privileged                                                          \
               --mount type=bind,source=$CNG_PATH,destination=/home/user/contiki-ng  \
               --device=/dev/ttyUSB0                                                 \
               --device=/dev/ttyUSB1                                                 \
               -ti contiker/contiki-ng"

With XQuartz

In order to access the X server from a Docker container, you need to use TCP because neither of the Docker solutions can handle Unix domain sockets properly. The option "Allow connections from network clients" in "Security" tab of "X11 Preferences" is for this purpose. You can open "X11 Preferences" by clicking "Preferences..." in XQuartz menu. If you want to limit listening IP address, socat is an option. Note that your host-based firewall may block connections on TCP Port 6000.

  1. install "Docker for Mac" or "Docker Toolbox on macOS"
  2. install XQuartz: $ brew cask install xquartz
  3. (option) install socat: $ brew install socat
  4. open XQuartz: $ open -a XQuartz
  5. (option) map TCP Port 6000 of 127.0.0.1 to /tmp/.X11-unix/X0:
    $ socat TCP-LISTEN:6000,reuseaddr,fork,range=127.0.0.1/32 UNIX-CLIENT:/tmp/.X11-unix/X0
  6. prepare contiker function
  7. run contiker: $ contiker bash

contiker alias is a bit complex compared to one for a Linux system. Actually, we make contiker function instead of alias. Put the following lines into ~/.profile or similar below the CNG_PATH definition.

for "Docker for Mac"

export CNG_PATH=<absolute-path-to-your-contiki-ng>
contiker () {
    COMMAND_STRING="
        cp \${HOME}/dot.Xauthority \${HOME}/.Xauthority
        DISPLAY_NAME=host.docker.internal:0
        export DISPLAY=\${DISPLAY_NAME}.0
        XAUTH_HEXKEY=`xauth list | head -n 1 | awk '{print $3}'`
        xauth add \${DISPLAY_NAME} . \${XAUTH_HEXKEY}
        $@"
    docker run --privileged                                                          \
               --mount type=bind,source=$CNG_PATH,destination=/home/user/contiki-ng  \
               -v ~/.Xauthority:/home/user/dot.Xauthority:ro                         \
               -ti contiker/contiki-ng                                               \
               bash -c "${COMMAND_STRING}"
}

for "Docker Toolbox on macOS"

export CNG_PATH=<absolute-path-to-your-contiki-ng>
contiker () {
    COMMAND_STRING="
        cp \${HOME}/dot.Xauthority \${HOME}/.Xauthority
        DISPLAY_NAME=`ifconfig vboxnet0 | awk '$1=="inet"{print $2}'`:0
        export DISPLAY=\${DISPLAY_NAME}.0
        XAUTH_HEXKEY=`xauth list | head -n 1 | awk '{print $3}'`
        xauth add \${DISPLAY_NAME} . \${XAUTH_HEXKEY}
        $@"
    docker run --privileged                                                          \
               --mount type=bind,source=$CNG_PATH,destination=/home/user/contiki-ng  \
               -v ~/.Xauthority:/home/user/dot.Xauthority:ro                         \
               --device=/dev/ttyUSB0                                                 \
               --device=/dev/ttyUSB1                                                 \
               -ti contiker/contiki-ng                                               \
               bash -c "${COMMAND_STRING}"
}

You need to enable USB devices in VirtualBox; start Virtualbox, and edit the settings for the machine running Docker to allow USB devices. You may want to download Oracle VM VirtualBox Extension Pack for USB 2.0 and USB 3.0 drivers.

Clone this wiki locally
You can’t perform that action at this time.