Deploy Software on PAL Robots

Deploy Software on PAL Robots#

Overview#

This tutorial introduces the PAL Deploy Tool, a utility provided in the PAL development docker to streamline the transition from code to hardware.

Learning Objectives#

By the end of this guide, you will be able to:

  • Deploy new ROS 2 packages to a PAL robot,

  • Overlay existing system packages with custom versions, and

  • Understand the workspace precedence on the robot.

The Deploy Tool#

The deploy tool simplifies the installation process by managing the transfer and build artifacts of your ROS 2 packages. It is designed to handle two primary use cases:

  1. New Software: Installing an entirely new functionality onto the robot, or

  2. Modifying Behavior: Installing a newer version of an existing package. The tool leaves the original system installation untouched, allowing for safe experimentation.

!!! Note Recall that when a package is deployed it sits in the Deployment Workspace, that is sourced as the the highest priority workspace.

Requirements for Success#

The deploy tool follows the standard ROS 2 release pipeline. It relies strictly on the install rules defined in your package’s configuration files.

If a file (node, configuration, or launch file) is not declared in the install section of your CMakeLists.txt (for C++) or setup.py (for Python), it will not be copied to the robot.

Example: CMakeLists.txt Install Rule

# Ensure your executable and folders are marked for installation
install(TARGETS my_custom_node DESTINATION lib/${PROJECT_NAME})
install(DIRECTORY launch DESTINATION share/${PROJECT_NAME})

Command Reference: deploy#

Run the deploy script from your development workstation terminal. By default, it deploys all packages from any found workspace unless specified otherwise.

usage: deploy [-h] [--port PORT] [--user USER] [--yes] [--package PKG]
              [--install-prefix INSTALL_PREFIX] [--cmake-args CMAKE_ARGS]
              [--no-deploy-dependencies] [--profile PROFILE]
              robot

Deploy built packages to a robot. 

positional arguments:
  robot                 hostname to deploy to (e.g. reemh3-2c)

options:
  -h, --help            show this help message and exit
  --port PORT           hostname port (default: 22)
  --user USER, -u USER  username (default: pal)
  --yes, -y             don't ask for confirmation, do it
  --package PKG, -p PKG
                        deploy specific packages
  --install-prefix INSTALL_PREFIX, -i INSTALL_PREFIX
                        Directory to deploy files
  --cmake-args CMAKE_ARGS, -c CMAKE_ARGS
                        Extra cmake args like --cmake-args="-DCMAKE_CXX_FLAGS='-DNDEBUG'"
  --no-deploy-dependencies, -d
                        When used with --package, don't deploy the dependencies
  --profile PROFILE, -P PROFILE
                        Build profile: 'debug', 'release', 'relwithdebinfo'

# Example Usage:
deploy robot-0c -u root -p pal_tts -c="-DCMAKE_CXX_FLAGS='-DNDEBUG'"

Build Configuration#

Default Build Behavior: The build type is not explicitly defined by default. The compiler uses standard C++ flags (typically -O2 for optimization and -g for debug info). In this mode, executables are optimized but may lack comprehensive debugging symbols.

To customize this behavior, use the --cmake-args flag. For example, to disable debug assertions:

--cmake-args="-DCMAKE_CXX_FLAGS='-DNDEBUG'"

Library Overlay Risks: Overlaying an existing system library can cause dependent executables or libraries to break due to ABI/API incompatibility.

Best Practice: If you modify a low-level library, simultaneously deploy all packages that depend on that library to ensure system-wide consistency.

Deploy Tips & Tricks#

  • Cleanup: To uninstall or revert changes, simply delete the corresponding package directory within /home/pal/deployed_ws on the robot.

  • Create a Shortcut: Simplify your workflow by adding an alias to your ~/.bashrc:

    alias deploy="ros2 run pal_deploy deploy"

  • Streamlined Commands: You can omit --user pal, as pal is the default username.

  • Deploy a single package:

    deploy -p hello_world robot-0c

  • Deploy multiple specific packages:

    deploy -p "package_a package_b package_c" robot-0c

  • Safety First: Before a major deployment, create a backup of your current ~/deployed_ws on the robot. This allows you to quickly roll back to a known stable state if the new code behaves unexpectedly. See Backing Up and Restoring the Workspace below for a convenient way to do this with pal ws.

Backing Up and Restoring the Workspace#

Before a major deployment, it is good practice to back up the robot’s ~/deployed_ws, so that you can quickly roll back to a known stable state if the new code behaves unexpectedly. The palcli_ws package provides the pal ws command for this, copying (or moving) the workspace into another directory while preserving its contents and structure.

!!! Note Backup workspaces are named after the date and time they were created plus a tag, either provided by you or randomly generated, for example deployed_ws-2025_08_27_15_37_09-foo. This makes it easy to identify them later with pal ws list or pal ws info.

Command Reference: pal ws#

  • pal ws backup [--tag|-t <tag>] [--move|-m] [--description|-d <description>]: creates a backup of deployed_ws. Copies by default; use --move to move instead.

  • pal ws move [--tag|-t <tag>] [--description|-d <description>]: alias for pal ws backup --move.

  • pal ws info [--name|-n <name>] [--date-time|-dt <date_time>] [--tag|-t <tag>]: shows information about a workspace (defaults to deployed_ws).

  • pal ws list [--date|-d <date>] [--tag|-t <tag>]: lists existing workspace backups, optionally filtered by date or tag.

  • pal ws remove [--name|-n <name>] [--date|-d <date>] [--tag|-t <tag>] [--force|-f] [--all|-a]: deletes workspaces; asks for confirmation unless --force is used.

  • pal ws restore [--name|-n <name>] [--date-time|-dt <date_time>] [--tag|-t <tag>] [--move|-m] [--force|-f]: restores a previously backed up workspace, reversing backup.

# Example Usage:
pal ws backup --tag pre_release --description "Workspace tooling testing over tag 1.2.3"
pal ws list
pal ws restore --tag pre_release

Deploying from the Developer Docker Image#

Step 0: Initial Setup#

First, set up your Developer Docker image as described in the Developing with the PAL Developer Docker image documentation.

The Exchange Folder#

An exchange folder is created in your home directory at ~/exchange.

  • Function: This folder is used to exchange files between the host computer and the Docker image.

  • Mechanism: The folder is mounted directly inside the Docker image.

  • Best Practice: It is highly recommended to use this folder to store your workspaces.

Step 1: Build and Deploy#

Navigate to your workspace directory inside the Docker container and run the deployment script:

cd ~/exchange/example_ws
ros2 run pal_deploy deploy.py --user pal robot-0c

The deploy tool will build the entire workspace in a separate path. If the build is successful, it will request confirmation to install the package on the robot.

Press Y so that the package files are installed on the robot computer.

Step 2: Connect to the Robot#

Open a terminal and SSH into the robot:

    ssh pal@robot-0c

Run the new node as follows.

For C++:

    ros2 run hello_world hello_world_node

For Python:

    ros2 run hello_world hello_world.py

If everything goes well, you should see Hello world printed on the screen. From the docker, check that the message is correctly published by running:

    ros2 topic echo /hello

IMPORTANT

Always test your software first in simulation and ensure that there is no any strange behaviour i.e high_accelerations, collisions, jerky movements.

See Also#