Develop for VOXL in a Docker

Table of contents

  1. Prerequisite: Install Docker CE
  2. Clone the voxl-docker repo
  3. Install the voxl-emulator Docker Image
  4. (OPTIONAL) Install the voxl-hexagon Docker Image
  5. Use of voxl-docker Script
  6. Example Projects

Develop for VOXL in a Docker running on your Linux PC! This tool lets you use the docker build environments described in the build environments page.

Prerequisite: Install Docker CE

1) Official instructions are here:

However, they are summarized at time of writing as follows. we can’t gurantee these commands are current whereas the above link should be current.

# install instructions from
sudo apt remove docker docker-engine containerd runc
sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common
curl -fsSL | sudo apt-key add -
sudo apt-key fingerprint 0EBFCD88
sudo add-apt-repository -y \
    "deb [arch=amd64] \
    $(lsb_release -cs) \
sudo apt update
sudo apt install -y docker-ce docker-ce-cli

2) Add current user to docker group to allow usage of docker commands without root privileges. You will need to restart your OS after running this command for the group permissions to be applied.

sudo usermod -a -G docker $USER
sudo reboot

Clone the voxl-docker repo

The voxl-docker repository contains dockerfiles and helper scripts used to build almost all voxl projects.

mkdir -p ~/git
cd ~/git
git clone
cd voxl-docker

Install the voxl-emulator Docker Image

voxl-emulator enables one to develop CPU-based applications for VOXL and test in an emulated environment.

4) Download archived docker image from ModalAI Developer portal (login required). Currently it is on version 1.1.

5) Move archive into the voxl-docker folder you just cloned alongside and

6) Run configuration script to load docker image from archive. This will also install the script to /usr/local/bin so the docker image can be started from within other project directories.


7) Test that the image was properly installed. Note the image is loaded originally with the V1.1 tag. The install script additionally gave it the ‘latest’ tag for ease of use when starting the image.

~/git/voxl-docker$ voxl-docker -l | grep "voxl"
voxl-emulator       V1.1                0f24b9c4d7c7        59 minutes ago      1.49GB
voxl-emulator       latest              0f24b9c4d7c7        59 minutes ago      1.49GB

(OPTIONAL) Install the voxl-hexagon Docker Image

If you wish to build programs for the Hexagon SDSP, you will need the Hexagon SDK from Qualcomm. To make this easier we provide the voxl-hexagon docker image which uses Hexagon SDK V3.1

8) Download and place the following files into cross_toolchain/downloads

Hexagon SDK 3.1 install file: qualcomm_hexagon_sdk_3_1_eval.bin

Linaro ARM compiler binaries: gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabi.tar.xz

9) Run the script. This will also install to usr/bin/ as did in case the user wants the hexagon docker only.


10) Confirm the install worked

~/git/voxl-docker$ voxl-docker -l | grep "voxl"
voxl-hexagon        latest              6b7bb00b90d0        2 minutes ago       5.21GB
voxl-emulator       latest              0e15518b8f95        11 months ago       1.26GB

Use of voxl-docker Script

$ voxl-docker -h

This is primarily used for running the voxl-emulator image for compiling ARM
apps-proc code for VOXL and the voxl-hexagon docker image for cross-compiling
hexagon SDSP programs. This can also launch any other installed docker image
with the -i argument.

By default this mounts the current working directory as the home directory
inside the docker for easy compilation of whichever project you are currently
working in. The directory that gets mounted inside the docker can be manually
specified with the -d argument.

The voxl-hexagon image starts with the username "user" with UID and GID 1000
which should match the first user on your desktop to avoid permissions issues.

The voxl-emulator image starts, by default, with the same username, UID, and GID
inside the docker as the user that launched it.

Since the voxl-emulator image is designed to emulate the userspace environment
that runs onboard the VOXL itself, you may wish to run as the root user inside
the voxl-emulator docker image to test certain behaviors as the root user.
This more closely mimics the on-target environment as the VOXL image runs as
root by default. Enter this mode with the -p option.

You can also specify the entrypoint for the docker image launch. By default this
is set to /bin/bash but can be user-configured with the -e option. This is most
likely used to pass the docker a command to execute before exiting automatically.
For example, to build the librc_math project in one command:

~/git/librc_math$ voxl-docker -i voxl-emulator -e "/bin/bash"

  -h:      : Print this help message
  -d <name>: The name of the directory to mount as ~/ inside the docker
  -i <name>: Docker image to run, usually voxl-emulator or voxl-hexagon
  -p       : for voxl-emulator image ONLY, runs as root user inside docker
  -l       : list installed docker images
  -e       : set the entrypoint for the docker image launch
$ voxl-docker -l
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
voxl-hexagon        latest              637d89d3a530        19 minutes ago      5.28GB
voxl-emulator       latest              0e15518b8f95        1  months ago       1.26GB

Example Projects

The following are good examples of how to build apps-proc code with the voxl-emulator docker image:

The following are good examples of how to build SDSP code with the voxl-hexagon docker image: