Making Emul8 easier: running Emul8 from Docker


Emul8 logo

Docker is all the rage these days, and since the publication of Emul8 last November we have been looking at ways to make our open source emulation framework easier to install.

Emul8 is a powerful tool which enables you to run unmodified binaries from your embedded devices – with various CPUs including but not limited to ARM Cortex-A and Cortex-M – on a PC, thus making it possible to do testing, debugging and continuous integration of entire embedded system networks without the hardware in the loop!

However, to use those superpowers, normally you need to go through a several step installation procedure.

Well, not any more!

Docker logo

To make things easier for everyone – and especially those who would just like to try Emul8 out – we built a Docker image (and a few underlying ones) with the necessary dependencies, using this fantastic containerization framework as a packaging tool, for a batteries-included setup which is very simple to run.

Provided you have Docker installed, you can run Emul8 using a single command:

docker run -e DISPLAY=$DISPLAY --net=host -t -i antmicro/emul8 emul8

Sit back and relax as the necessary components get downloaded (admittedly, you need a few gigabytes of disk space) and Emul8 runs out of the container.

Should you run into X-passthrough problems (with terminals that should open automatically from the main log window), you could pass your Xauthority file to the docker image via a volume. To do that, try:

docker run -e DISPLAY=$DISPLAY -v $XAUTHORITY:/home/user/.Xauthority --net=host \
    -t -i antmicro/emul8 emul8

Alternatively, if you are on a trusted network, you can run:

xhost +

in a separate console to disable X host checking – the latter has worked for us most consistently (but don’t try it when on a potentially insecure network).

Hopefully at this point you have emul8 running and opening consoles going Hello world! on an emulated Cortex-M target.
To go on from there, check out our Getting Started section.

The magic is provided by Docker and Docker Hub, where the necessary images are stored.

We have been testing this image e.g. with an example project we prepared earlier: a minimum GitHub repository with a sample emulation script and Contiki hello world application (with Contiki as a submodule) on Texas Instruments’ CC2538, a Cortex-M3 platform with a 2.4 GHz radio. To mount the necessary volume from your host, use:

docker run -e DISPLAY=$DISPLAY -v emul8-contiki-sample-project --net=host \
    -t -i antmicro/emul8 emul8

(remember the Xauthority argument in case you are using this).

Alternatively, you could also try RIOT with an analogous GitHub repository!

We’re using the popular Ubuntu 14.04 image as base, chances are you already have it and don’t need the additional download.
This is the first iteration – we are pretty sure with time more images with useful tools can be created.

If you have any comments, please let us know at