../_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#

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

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

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

This PAL OS 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. The PAL OS Docker image is provided by PAL when purchasing a 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.

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 <robot-type>-<serial>-dev

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#