Skip to main content
Version: ROS 2 Humble

Upgrading to Humble

note

Users who are installing ROS 2 Humble onto a new robot computer can skip to Robot Installation.

note

Check the list of supported platforms to make sure that your robot is currently supported on ROS 2 Humble.

ROS 2 Humble is the first ROS distribution that runs on Ubuntu 22.04. As a result, any robots running ROS 1 or ROS 2 Foxy will have upgrade their operating system. It is highly recommended to back up any important files on the robot before proceeding, especially for highly customized robots.

caution

It is the user’s responsibility to ensure that any essential files are properly backed-up before upgrading their robot.

Saving a hard drive image​

As a fail-safe, please make an image of your robot's hard drive. You should always be able to restore this image if you need to revert back to your previous configuration. The easiest approach may be to either connect a removable (USB or similar) hard drive to the robot's computer, or to unplug the robot's hard drive and insert it into a computer or workstation. You can then use a tool such as CloneZilla or dd to write a backup image of your robot's hard drive onto another hard drive. Alternatively, you can simply replace the robot computer's hard drive, reserving the drive and installing a new one to use with Humble.

Saving important files​

There are several places in the filesystem you should specifically look for customizations for your robot:

LocationDescription
/etc/network/interfaces or /etc/netplan/*Your robot may have a custom network configuration in this file.
/etc/ros/*/*-core.d/*.launchWill contain base.launch and description.launch, may contain custom launch files for your robot configuration. Replaced by ros.d in newer versions.
/etc/ros/*/ros.d/*.launch Will contain base.launch and description.launch, may contain custom launch files for your robot configuration. Replaces *-core.d in newer versions.
/etc/ros/setup.bashMay contain environment variables for your configuration.
~/catkin_ws/ or ~/colcon_ws/ROS workspace that may contain custom ROS packages.

Please save the files listed above and use them as a reference during Humble configuration.

Backup Software (ROS 1 only)​

Clearpath Robotics provides a package containing several shell scripts to help you back up, upgrade, and/or restore your ROS 1 robot’s important data. You can use these scripts by downloading the robot-backup repository by running the following command on your computer:

git clone https://github.com/clearpathrobotics/robot-backup

You will need to install dependencies to be able to use these scripts. The instructions for installing dependencies can be found in the README.md file of the repository, or run the following command on your computer:

sudo apt-get install sshpass sudo apt-get install rsync

Running the backup script​

Ensure that the robot is turned on and that you can SSH into it from your computer. Then run the following from your computer:

cd robot-backup
bash backup.sh <backup-name> <robot-hostname OR robot-ip-address>

For example, if your robot’s IP address is 192.168.1.103, you would run something like:

bash backup.sh melodic-final-backup 192.168.1.103

This will produce a backup file called melodic-final-backup.tar.gz. Keep this file for when you need to access your backed-up data.

By default all Clearpath robots use the username administrator and the password clearpath. The backup.sh script will use these credentials by default, but you can override them easily.

For example, if your robot’s username and password have been set to my_robot_username and my_robot_password you should run:

bash backup.sh melodic-final-backup my_robot_username@192.168.1.103 my_robot_password

Backed up contents​

The backup script will copy the following data:

  • Home Folder: ~/
  • udev Rules: /etc/udev/rules.d
  • Network Setup: - /etc/network/interfaces - /etc/netplan - /etc/hostname - /etc/hosts
  • IP Tables: /etc/iptables
  • Bringup Files: - /etc/ros/setup.bash - /etc/ros/$ROSDISTRO/ros.d - /usr/sbin/*start - /usr/sbin/*stop
  • rosdep sources: /etc/ros/rosdep
  • rc.local File: /etc/rc.local
  • pip packages
  • systemd configuration: /etc/systemd/system
  • apt sources: /etc/apt/sources.list.d
  • apt packages
  • User Permission Groups

Backing up non-standard data​

The backup.sh script assumes that your robot is in a roughly-standard configuration; it uses a single user account and no files within /opt/ros/$ROS_DISTROhave been modified.

If this is not the case, it is the responsibility of the user to ensure that any modified files and files in other users’ home folders is backed up correctly.

A common example of this might be if you have created customized URDF files to be loaded via environment variables (such as, JACKAL_URDF_EXTRAS for the Jackal) and have stored them outside any of the folders specified above, you must back these up yourself; backup.sh will not do this for you.

Converting Environment Variables to Clearpath Config​

The environment variables used to define your robot in ROS 1 and ROS 2 Foxy can be converted to the robot.yaml format to maintain the same robot description when you upgrade to ROS 2 Humble. Below are some common examples. Visit the robot.yaml documentation for more details.

Attachments​

Each platform has platform-specific attachments (formerly decorations) such as bumpers and top plates. These now reside under the platform section of the robot.yaml file.

Environment variables:

export JACKAL_FRONT_ACCESSORY_FENDER=1
export JACKAL_REAR_ACCESSORY_FENDER=0

robot.yaml configuration:

platform:
  attachments:
    - name: front_fender
      type: fender
      model: default
      parent: base_link
      xyz: [0.0, 0.0, 0.0]
      rpy: [0.0, 0.0, 0.0]
      enabled: true         # JACKAL_FRONT_ACCESSORY_FENDER=1
    - name: rear_fender
      type: fender
      model: default
      parent: base_link
      xyz: [0.0, 0.0, 0.0]
      rpy: [0.0, 0.0, 3.1415]
      enabled: false        # JACKAL_REAR_ACCESSORY_FENDER=0

Sensors​

Sensors can be added under the sensors key in the robot.yaml file. There is no longer a concept of primary, secondary, etc. sensors. Rather, sensors are enumerated in the order that they are added to the config. Sensor topics will be automatically set to match the Clearpath API.

2D Lidar​

Environment variables:

# Primary Laser
export JACKAL_LASER=1
export JACKAL_LASER_MODEL=lms1xx
export JACKAL_LASER_TOPIC="front/scan"
export JACKAL_LASER_HOST="192.168.131.20"
export JACKAL_LASER_MOUNT="front"
export JACKAL_LASER_PREFIX="front"
export JACKAL_LASER_PARENT="front_mount"
export JACKAL_LASER_OFFSET="0 0 0"
export JACKAL_LASER_RPY="0 0 0"

# Secondary Laser
export JACKAL_LASER_SECONDARY=1
export JACKAL_LASER_SECONDARY_MODEL="lms1xx"
export JACKAL_LASER_SECONDARY_HOST="192.168.131.21"
export JACKAL_LASER_SECONDARY_TOPIC="rear/scan"
export JACKAL_LASER_SECONDARY_MOUNT="rear"
export JACKAL_LASER_SECONDARY_PREFIX="rear"
export JACKAL_LASER_SECONDARY_PARENT="rear_mount"
export JACKAL_LASER_SECONDARY_OFFSET="0 0 0"
export JACKAL_LASER_SECONDARY_RPY="0 0 3.14159"

robot.yaml configuration:

sensors:
  lidar2d:
  - model: sick_lms1xx            # JACKAL_LASER_MODEL=lms1xx
    urdf_enabled: true
    launch_enabled: true          # JACKAL_LASER=1
    parent: front_mount           # JACKAL_LASER_PARENT="front_mount"
    xyz: [0.0, 0.0, 0.0]          # JACKAL_LASER_OFFSET="0 0 0"
    rpy: [0.0, 0.0, 0.0]          # JACKAL_LASER_RPY="0 0 0"
    ros_parameters:
      lms1xx:
        frame_id: lidar2d_0_laser
        hostname: 192.168.131.20  # JACKAL_LASER_HOST="192.168.131.20"
        port: 2112
        min_ang: -2.391
        max_ang: 2.391
  - model: sick_lms1xx            # JACKAL_LASER_SECONDARY_MODEL="lms1xx"
    urdf_enabled: true
    launch_enabled: true          # JACKAL_LASER_SECONDARY=1
    parent: rear_mount            # JACKAL_LASER_SECONDARY_PARENT="rear_mount"
    xyz: [0.0, 0.0, 0.0]          # JACKAL_LASER_SECONDARY_OFFSET="0 0 0"
    rpy: [0.0, 0.0, 3.14159]      # JACKAL_LASER_SECONDARY_RPY="0 0 3.14159"
    ros_parameters:
      lms1xx:
        frame_id: lidar2d_1_laser
        hostname: 192.168.131.21  # JACKAL_LASER_SECONDARY_HOST="192.168.131.21"
        port: 2112
        min_ang: -2.391
        max_ang: 2.391

3D Lidar​

Environment variables:

export JACKAL_LASER_3D=1
export JACKAL_LASER_3D_HOST="192.168.131.20"
export JACKAL_LASER_3D_TOPIC="mid/points"
export JACKAL_LASER_3D_TOWER=1
export JACKAL_LASER_3D_MOUNT="mid"
export JACKAL_LASER_3D_PREFIX="mid"
export JACKAL_LASER_3D_PARENT="mid_mount"
export JACKAL_LASER_3D_MODEL="vlp16"
export JACKAL_LASER_3D_OFFSET="0 0 0"
export JACKAL_LASER_3D_RPY="0 0 0"

robot.yaml configuration:

sensors:
  lidar3d:
  - model: velodyne_lidar
    urdf_enabled: true
    launch_enabled: true            # JACKAL_LASER_3D=1
    parent: mid_mount               # JACKAL_LASER_3D_PARENT="mid_mount"
    xyz: [0.0, 0.0, 0.0]            # JACKAL_LASER_3D_OFFSET="0 0 0"
    rpy: [0.0, 0.0, 0.0]            # JACKAL_LASER_3D_RPY="0 0 0"
    ros_parameters:
      velodyne_driver_node:
        frame_id: lidar3d_0_laser
        device_ip: 192.168.131.20   # JACKAL_LASER_3D_HOST="192.168.131.20"
        port: 2368
        model: VLP16

Camera​

Environment variables:

# Primary Camera
export HUSKY_REALSENSE_ENABLED=1
export HUSKY_REALSENSE_SERIAL='0'
export HUSKY_REALSENSE_TOPIC='realsense'
export HUSKY_REALSENSE_POINTCLOUD_ENABLED=1
export HUSKY_REALSENSE_DEPTH_ENABLED=1
export HUSKY_REALSENSE_DEPTH_FRAMERATE='30'
export HUSKY_REALSENSE_DEPTH_HEIGHT='480'
export HUSKY_REALSENSE_DEPTH_WIDTH='640'
export HUSKY_REALSENSE_COLOR_ENABLED=1
export HUSKY_REALSENSE_COLOR_FRAMERATE='30'
export HUSKY_REALSENSE_COLOR_HEIGHT='480'
export HUSKY_REALSENSE_COLOR_WIDTH='640'
export HUSKY_REALSENSE_PREFIX='camera'
export HUSKY_REALSENSE_PARENT='top_plate_link'
export HUSKY_REALSENSE_XYZ='0 0 0'
export HUSKY_REALSENSE_RPY='0 0 0'

# Secondary Camera
export HUSKY_REALSENSE_SECONDARY_ENABLED=1
export HUSKY_REALSENSE_SECONDARY_SERIAL='1'
export HUSKY_REALSENSE_SECONDARY_TOPIC='realsense_secondary'
export HUSKY_REALSENSE_SECONDARY_POINTCLOUD_ENABLED=1
export HUSKY_REALSENSE_SECONDARY_DEPTH_ENABLED=1
export HUSKY_REALSENSE_SECONDARY_DEPTH_FRAMERATE='30'
export HUSKY_REALSENSE_SECONDARY_DEPTH_HEIGHT='480'
export HUSKY_REALSENSE_SECONDARY_DEPTH_WIDTH='640'
export HUSKY_REALSENSE_SECONDARY_COLOR_ENABLED=1
export HUSKY_REALSENSE_SECONDARY_COLOR_FRAMERATE='30'
export HUSKY_REALSENSE_SECONDARY_COLOR_HEIGHT='480'
export HUSKY_REALSENSE_SECONDARY_COLOR_WIDTH='640'
export HUSKY_REALSENSE_SECONDARY_PREFIX='secondary_camera'
export HUSKY_REALSENSE_SECONDARY_PARENT='top_plate_link'
export HUSKY_REALSENSE_SECONDARY_XYZ='0 0 0'
export HUSKY_REALSENSE_SECONDARY_RPY='0 0 0'

robot.yaml configuration:

sensors:
  camera:
  - model: intel_realsense
    urdf_enabled: true
    launch_enabled: true                  # HUSKY_REALSENSE_ENABLED=1
    parent: top_plate_link                # HUSKY_REALSENSE_PARENT='top_plate_link'
    xyz: [0.0, 0.0, 0.0]                  # HUSKY_REALSENSE_XYZ='0 0 0'
    rpy: [0.0, 0.0, 0.0]                  # HUSKY_REALSENSE_RPY='0 0 0'
    ros_parameters:
      intel_realsense:
        camera_name: camera_0
        device_type: d435
        serial_no: "0"                    # HUSKY_REALSENSE_SERIAL='0'
        enable_color: true                # HUSKY_REALSENSE_COLOR_ENABLED=1
        rgb_camera.profile: 640,480,30    # HUSKY_REALSENSE_COLOR_WIDTH='640'
                                          # HUSKY_REALSENSE_COLOR_HEIGHT='480'
                                          # HUSKY_REALSENSE_COLOR_FRAMERATE='30'
        enable_depth: true                # HUSKY_REALSENSE_DEPTH_ENABLED=1
        depth_module.profile: 640,480,30  # HUSKY_REALSENSE_DEPTH_WIDTH='640'
                                          # HUSKY_REALSENSE_DEPTH_HEIGHT='480'
                                          # HUSKY_REALSENSE_DEPTH_FRAMERATE='30'
        pointcloud.enable: true           # HUSKY_REALSENSE_POINTCLOUD_ENABLED=1
  - model: intel_realsense
    urdf_enabled: true
    launch_enabled: true                  # HUSKY_REALSENSE_SECONDARY_ENABLED=1
    parent: top_plate_link                # HUSKY_REALSENSE_SECONDARY_PARENT='top_plate_link'
    xyz: [0.0, 0.0, 0.0]                  # HUSKY_REALSENSE_SECONDARY_XYZ='0 0 0'
    rpy: [0.0, 0.0, 0.0]                  # HUSKY_REALSENSE_SECONDARY_RPY='0 0 0'
    ros_parameters:
      intel_realsense:
        camera_name: camera_1
        device_type: d435
        serial_no: "1"                    # HUSKY_REALSENSE_SECONDARY_SERIAL='1'
        enable_color: true                # HUSKY_REALSENSE_SECONDARY_COLOR_ENABLED=1
        rgb_camera.profile: 640,480,30    # HUSKY_REALSENSE_SECONDARY_COLOR_WIDTH='640'
                                          # HUSKY_REALSENSE_SECONDARY_COLOR_HEIGHT='480'
                                          # HUSKY_REALSENSE_SECONDARY_COLOR_FRAMERATE='30'
        enable_depth: true                # HUSKY_REALSENSE_SECONDARY_DEPTH_ENABLED=1
        depth_module.profile: 640,480,30  # HUSKY_REALSENSE_SECONDARY_DEPTH_WIDTH='640'
                                          # HUSKY_REALSENSE_SECONDARY_DEPTH_HEIGHT='480'
                                          # HUSKY_REALSENSE_SECONDARY_DEPTH_FRAMERATE='30'
        pointcloud.enable: true           # HUSKY_REALSENSE_SECONDARY_POINTCLOUD_ENABLED=1

IMU​

Environment variables:

export JACKAL_IMU_MICROSTRAIN=1
export JACKAL_IMU_MICROSTRAIN_NAME="microstrain"
export JACKAL_IMU_MICROSTRAIN_LINK="microstrain_link"
export JACKAL_IMU_MICROSTRAIN_PARENT="base_link"
export JACKAL_IMU_MICROSTRAIN_OFFSET="-0.139 0.096 0.100"
export JACKAL_IMU_MICROSTRAIN_RPY="3.14159 0 -1.5707"

robot.yaml configuration:

sensors:
  imu:
  - model: microstrain_imu        # JACKAL_IMU_MICROSTRAIN=1
    urdf_enabled: true
    launch_enabled: true
    parent: base_link             # JACKAL_IMU_MICROSTRAIN_PARENT="base_link"
    xyz: [-0.139, 0.096, 0.100]   # JACKAL_IMU_MICROSTRAIN_OFFSET="-0.139 0.096 0.100"
    rpy: [3.14159, 0.0, -1.5707]  # JACKAL_IMU_MICROSTRAIN_RPY="3.14159 0 -1.5707"
    ros_parameters:
      imu_frame_id: imu_0_link
      port: /dev/microstrain
      use_enu_frame: true

GPS​

Environment variables:

export JACKAL_NAVSAT=1
export JACKAL_NAVSAT_PORT="/dev/clearpath/gps"
export JACKAL_NAVSAT_BAUD=57600
export JACKAL_NAVSAT_RTK=0
export JACKAL_NAVSAT_RTK_DEVICE=wlan0
export JACKAL_NAVSAT_RTK_BAUD=57600
export JACKAL_NAVSAT_MOUNT="rear"
export JACKAL_NAVSAT_PREFIX="rear"
export JACKAL_NAVSAT_PARENT="rear_mount"
export JACKAL_NAVSAT_MODEL="smart6"
export JACKAL_NAVSAT_OFFSET="0 0 0"
export JACKAL_NAVSAT_RPY="0 0 0"

robot.yaml configuration:

sensors:
  gps:
  - model: novatel_smart6           # JACKAL_NAVSAT_MODEL="smart6"
    urdf_enabled: true
    launch_enabled: true            # JACKAL_NAVSAT=1
    parent: rear_mount              # JACKAL_NAVSAT_PARENT="rear_mount"
    xyz: [0.0, 0.0, 0.0]            # JACKAL_NAVSAT_OFFSET="0 0 0"
    rpy: [0.0, 0.0, 0.0]            # JACKAL_NAVSAT_RPY="0 0 0"
    ros_parameters:
      nmea_navsat_driver:
        port:"/dev/clearpath/gps"   # JACKAL_NAVSAT_PORT="/dev/clearpath/gps"
        baud: 57600                 # JACKAL_NAVSAT_BAUD=57600

Next steps​

Once everything is backed up and you have created your robot.yaml file, the next step is to go through the robot install instructions. This will involve installing the new OS.

Last updated on