Developing with the SDK Docker image and ROS

Section

📜 Developing applications - how-tos

Overview

In PAL OS 24.9, your robot runs ROS 2 humble on top of the Ubuntu 22.04 LTS operating system (more details here).

While the primary development environment for PAL OS 24.9 is the PAL-provided Developer Docker image, it is also possible to set up an identical development environment directly on your computer (ROS 2 Humble installation instructions).

This Docker image is based on Ubuntu 22.04 LTS/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.

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.

Recommended configuration for your development workstation

A computer with 8 CPU cores is recommended. Furthermore, in order to have a better user experience when using visualization tools like rviz and the Gazebo simulator a powerful graphics card is recommended.

Note

While officially both ROS humble and Docker are available for Windows, the practical implementation of Windows is still limited, especially when developing with the robot. We recommend using a Linux-based system for development with the PAL OS Docker image.

What is a Docker image?

Docker is a platform for developers and sysadmins to develop, deploy, and run applications inside containers. The use of Linux containers to deploy applications is called containerization. Containerization is increasingly popular due to several of its features:

• Flexible: Complex applications with many and/or non-standard dependencies can be containerized;

• Lightweight compared to e.g. virtual machines: Containers leverage and share the host kernel;

• Interchangeable: Deploy updates and upgrades on-the-fly;

• Portable: Bild locally, deploy to the cloud, and run anywhere;

• Scalable: Increase and automatically distribute container replicas;

• Stackable: Stack services vertically and on-the-fly.

If you are interested on how docker works, visit their webpage .

Installing Docker

First, install Docker for Ubuntu, either via your package manager (apt install docker.io), or following the instructions of the official page.

Note

Do not forget to follow the Linux post-install steps to be able to run docker as a non-root user.

Verify that the Docker Engine installation is successful by running the hello-world image:

docker run hello-world

Downloading your PAL OS Docker image

Once Docker has been installed the PAL OS Docker image image can be pulled from the PAL docker registry with the following steps. First login with the username and password provided by PAL Robotics.

docker login docker.pal-robotics.com

Next, you can pull your Docker image:

docker pull $DOCKER_IMAGE_URL

Hint

If you do not have access to the PAL Robotics Docker registry, please open a ticket on the support platform, requesting your Robot docker.

Configure pal_docker_utils

For your convenience, we have published scripts that simplify the launch of a Docker with GPU acceleration. Follow the instructions at pal_docker_utils to properly set up your environment with nvidia-docker. If these steps are not performed, you will not be able to run gazebo, rviz or other graphical applications from within the docker container. Furthermore, it allows you to access the container as a non-root user, recommended for ROS development.

cd ~
git clone https://github.com/pal-robotics/pal_docker_utils.git

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, you can mount it to the PAL OS Docker image with:

docker run -it -v /home/user/example_ws:/home/user/example_ws/ $DOCKER_IMAGE_URL bash

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_utils 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.

Run the PAL OS Docker image

Once logged and after configuring pal_docker_utils, you will need to execute the pal_docker.sh script with the name of the image and the application you want to start.

cd pal_docker_utils/scripts/
./pal_docker.sh -it $DOCKER_IMAGE_URL bash

The previous command starts a bash terminal inside a container of the specified image.

Note

Before the first creation of the Docker container, ensure that the folder $HOME/exchange exists. If this folder is not created beforehand, the docker will create it automatically. In some cases, the folder will be created with root access only. When this happens, read and write permissions for the Docker user is limited and access to this folder has to be manually changed to set up the proper development environment. Changing the permission of the folder can be done from within the Docker container by running:

sudo chown -R user:host_group /home/user/exchange

Configuring the ROS 2 environment inside the Docker image

In order to use the ROS commands and packages provided in the docker 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.

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 its Gazebo simulation.

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.

See also

• robot-communication-ros2