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