../_images/tiagopro-icon.png ../_images/tiago-head-icon.png ../_images/kangaroo-icon.png ../_images/tiago-icon.png ../_images/triago-icon.png ../_images/ari-icon.png ../_images/talos-icon.png ../_images/mobile-bases-icon.png

Developing with the PAL Developer Docker image

Overview

To develop applications for your PAL robot, we recommend using a containerized development environment based on Docker. This allows you to run a consistent development environment that matches the software running on your robot, without the need to install all the dependencies directly on your computer.

Important

If you are new to Docker, you can read more about it here.

PAL offers two Docker images for development:

  • The PAL Developer Docker image. It is provided when you purchase a PAL robot and contains all the specific configuration for your specific unit (including eg proprietary code). This page describes how to use this.

  • The PAL public Docker image. It is available to the public from Docker Hub and contains only the open-source packages that PAL Robotics has released. Ideal to get started and explore our API in simulation, but not recommended for actual development on a real robot. Check PAL public Docker image for more information.

What is in the PAL Developer Docker image?

Like your robot, the PAL OS Docker image is based on Ubuntu 22.04 LTS with ROS 2 humble.

It additionally includes several packages (e.g. PAL-specific ROS message definitions) that are essential to develop and deploy code on your robot. This specific PAL distribution is called alum and is also present on the robot.

One of the key tool included in the PAL OS Docker image is the deploy tool, making it easy to install code developed in the Docker image onto your robot. More about it below.

Note

Some of the PAL-specific packages are publicly available. If you decide to develop outside of the provided Docker image, you may want to download these messages and libraries directly from the ROS humble distribution or manually install them from the PAL Robotics public GitHub repository.

Alternatively, the PAL public Docker image is available at Docker Hub and contains all the public PAL package already pre-installed.

Downloading your PAL OS Docker image

Once Docker has been installed, the PAL OS Docker image can be downloaded with the following steps. First, download the PAL Docker script with the link and password provided by PAL Robotics. Create the Docker container with the following command:

bash <client-name>-build-docker.sh --create

Note

If you own more than one PAL robot, you must provide as well the name of your robot:

bash <client-name>-build-docker.sh --create <robot_id>

Run bash <client-name>-build-docker.sh without parameter to see the list of available robots.

The created container can be started with the command:

docker start -ai development-<robot-type>-<serial>

Hint

If you have not received the PAL Docker script, please open a ticket on the support platform, requesting your Robot docker.

Sharing files between the host and the Docker image

A key feature of Docker containers is that modifications to a Docker image are lost when exiting the container.

While this feature ensure your Docker image will always be ‘clean’, you will most likely want to be able to make some permanent changes, e.g. to your code, within the image.

You can achieve this by mounting folders from your host to the image, thus creating a shared folder.

For instance, if you already have a ROS 2 workspace on your main computer under /home/<your username>/example_ws, you can mount it to the PAL OS Docker image with:

docker run -it -v /home/<your username>/example_ws:/home/user/example_ws/ $DOCKER_IMAGE_URL bash

Where the DOCKER_IMAGE_URL is the url of the PAL OS Docker image: development-<robot_type>-<serial_number>.

With the above command, changes made to the files contained in example_ws will be reflected in both the host and the Docker image.

By default PAL Docker script mounts the $HOME/exchange folder of the host to the /home/user/exchange folder of the Docker image. This folder can be used to share all ROS workspaces between the host and the Docker container.

Note

Changes to a Docker image can also be saved by committing the changes to a new image.

See the Docker tutorials to learn more about Docker.

Configuring the ROS 2 environment inside the Docker image

In order to use the ROS commands and packages provided in the Docker image, the following command needs to be executed when opening a new terminal inside a Docker image:

source /opt/pal/alum/setup.bash

A good way to spare the execution of this command everytime is to append it at the end of /home/user/.bashrc in the Docker container. If you do so, do not forget to commit your Docker image with the change.

Note

if you want to open another terminal into the current Docker image, run

docker exec -it -u user alum-devel bash

Compiling software

The PAL OS Docker image includes the ROS messages, system headers and our C++ open source headers necessary to compile and deploy software to the robot, as well as visualization and simulation tools.

Some of the software APIs that we have developed are proprietary, and their headers are not included by default. If you require them you can contact us through our customer service portal and after signing a non-disclosure agreement, they will be provided. These APIs are for accessing advanced features not available through a ROS API.

Deploy code from the Docker image to the robot

You can easily deploy your own ROS nodes from the PAL OS Docker image to your robot, using the pre-installed pal_deploy tool.

Follow the Deploying code to the robot from the Developer Docker image.

System Upgrade

In order to upgrade the software of the PAL OS Docker image, you can execute the following command:

sudo apt update && sudo apt upgrade

PAL Robotics will communicate whenever software upgrades are available.

Frequently Asked Questions

See also