Skip to main content
Version: ROS 1 Noetic

Boxer Tutorials

Boxer Overview​

caution

This guide is for the Boxer V2.4 (released in November 2021) and V2.5 (released in May 2023). Boxer V2.4 and V2.5 are not compatible with the older Boxer (V2.2). Owners of previous-generation (V2.2) Boxers should refer to the documentation here.

note

OTTO Motors and Clearpath Robotics operate under the same parent company. Boxer V2.4 and V2.5 are a collaboration between the teams at OTTO Motors and Clearpath Robotics.

Introduction​

Boxer is a large indoor mobile robot for prototyping and development of industrial applications. It is a lightly modified OTTO 100 robot, equipped with a Backpack Computer mounted to the top of the Base Unit. This Backpack Computer communicates with the OTTO 100 via its attachment port, located on the top of the Base Unit.

For more information or to receive a quote, please visit us online.

note

These tutorials assume that you are comfortable working with ROS. We recommend starting with our ROS tutorial if you are not familiar with ROS already.

note

These tutorials specifically target Boxer robots with a Backpack Computer running Ubuntu 20.04 with ROS Noetic, as it is the standard OS environment for Boxer.

Boxer ROS Packages provides the references for the software packages and key ROS topics.

Boxer Software Setup outlines the steps for setting up the software on your Boxer robot and optionally on a remote computer.

Using Boxer describes how to simulate and drive your Boxer. Simulation is a great way for most users to learn more about their Boxer; understanding how to effectively operate Boxer in simulation is valuable whether you are in the testing phase with software you intend to ultimately deploy on a physical Boxer or you do not have one and are simply exploring the platform's capabilities. Driving Boxer covers how to teleoperate Boxer using the remote control, as well as safety procedures for operating the physical robot. Anyone working with a physical robot should be familiar with this section.

Mapping and Navigating with Boxer is a follow-on to what is learned in the Simulation tutorial, as navigation and map-making may be run in the simulated environment. However, this content is applicable to both the simulator and the real platform, if your Boxer is equipped with a laser scanner.

Boxer Tests outlines how to validate that your physical Boxer is working correctly.

Terminology​

The following terms are used throughout this guide:

  • Backpack Computer: the externally-mounted computer that has the ROS Master running on it.
  • Base Unit: the OTTO 100 platform, including its internal computer. Sometimes referred to as "The OTTO 100".
  • Boxer: the combined Base Unit and Backpack Computer.

Differences from OTTO 100​

The most obvious difference between OTTO 100 and Boxer V2.4/V2.5 is that Boxer has been painted black with a yellow stripe on the sides. This change is purely cosmetic, and is to keep the Boxer visually distinct.

Mechanically, the top deck of the Boxer has a slightly thicker, heavier top-plate with a different arrangement of mounting holes than the OTTO 100. This is to allow the attachment of additional payloads, such as robotic arms, larger sensor arrays, and structural elements.

URDF model of Boxer with two Kinova Gen3 arms

Finally, the OTTO 100's attachment interface and ROS 2 API have been enabled. This is necessary to allow the Backpack Computer to communicate with and control the robot.

Operating Boxer​

Boxer is intended to be controlled via the Backpack Computer; all necessary ROS nodes, and the ROS Master, are running on the Backpack Computer. Any topics published by or subscribed to from the OTTO 100's internal computer are relayed from the Backpack Computer.

When the robot powers on it will be in neutral. Use the OTTO App to disengage the safeties and enable operation of the robot. Note that this requires that the Base Unit be connected to your wireless network. Refer to Network Setup for more details.

One ethernet port of the Backpack Computer is reserved for communicating with the Base Unit. By default this is the port identified as eno1, labelled "LAN1" on most computers. All other ethernet ports on the Backpack Computer are bridged together and may be used for diagnostics, connecting external computers, or adding IP-based accessories such as lidar sensors, cameras, or robotic arms.

ROS 2 API​

OTTO Motors has developed a ROS 2 API that is available to monitor and control the Base Unit. When using ROS Noetic, Boxer uses ros1_bridge nodes to translate this ROS 2 API into ROS 1 compatible messages.

The ROS 2 API operates on 3 domains:

Domain IDDescription
100Fleet API
110Autonomy API
95Platform API

Refer to the OTTO 100 documentation for more details on the ROS 2 API.

Standard Sensors​

The Base Unit includes a number of sensors whose data can be consumed by ROS nodes running on the Backpack Computer:

  • front-facing safety lidar, available as /front/scan
  • rear-facing safety lidar, available as /rear/scan
  • internal IMU, available as /imu/module0/data_raw
  • front-facing Intel RealSense camera
    • depth data available as /realsense/depth/image_rect_raw
    • depth camera info available as /realsense/depth/camera_info

At the time of writing OTTO Motors' ROS 2 API does not expose pointcloud or RGB data from the RealSense camera

Boxer ROS Packages​

Boxer fully supports ROS. Boxer's Noetic packages are split into 5 repositories on Github:

  • Boxer: the core description and control packages, needed for physical and simulated robots
  • Boxer Robot: core launch files and services needed for operating a physical Boxer
  • Boxer Simulation: Gazebo simulation packages for Boxer
  • Boxer Desktop: desktop visualization packages for Boxer
  • Boxer Manipulation: optional support for robotic arms and grippers, including Kinova, Kuka, Robotiq, and UR

Description Package​

The boxer_description repository provides a URDF model of Boxer.

Boxer's URDF model can be visualized in RViz. Once you have installed the desktop software in an upcoming tutorial, you will be able to run:

roslaunch boxer_viz view_model.launch
Boxer model

Environment Variables​

Boxer can be customized and extended through the use of several environment variables. The details are in the boxer_description repository. Some of the most important ones are listed below.

VariableDefaultDescription
ROS_ROBOT_SERIAL_NOundefinedThe Boxer's serial number. This should be of the form A31_0123456789 and must match the serial number stamped on the robot
BOXER_API_VERSIONv1_1The version of the OTTO SDK running on the Base Unit.
BOXER_URDF_EXTRASempty.urdf.xacroOptional path to an additional URDF file to be added to the robot's description. Commonly used to add additional joints and links to add additional payloads, e.g. arms, additional sensors
BOXER_CONTROL_EXTRASempty.yamlOptional path to a configuration file to override any of the Boxer's control parameters. Commonly used to change controller button mappings, EKF parameters, etc.
BOXER_PC1If 1 the URDF will include a model of the Backpack Computer. If 0 the Backpack Computer is omitted from the URDF. The shape of the mode is determined by the BOXER_PC_MODEL variable
BOXER_PC_MODELevs-2000Customizes the shape of the Backpack Computer added to the URDF. Other options are ecx-2000 (for Vecow ECX-2000 series computer) and mini-itx (for common mini-ITX mini desktop enclosure)
BOXER_PC_XYZ0 0 0Defines the position of the Backpack Computer in the URDF relative to the Boxer's top_plate_link
BOXER_PC_RPY0 0 0Defines the orientation of the Backpack Computer in the URDF relative to the Boxer's top_plate_link
BOXER_GPIO0If 1 the GPIO pins on the PC can be controlled via a ROS node. Not yet supported.

Key ROS Topics​

You can view all topics that are active using rostopic list.

Your Boxer can be controlled through ROS, either through a ROS 2 API on the Base Unit or through a ROS 1 API on the optional Backpack Computer. Some key topics that comprise the Boxer's ROS 1 API are listed below. For details on the ROS 2 API, please contact Support.

TopicMessage TypePurpose
/cmd_velgeometry_msgs/TwistInput to Boxer's kinematic controller. Publish here to make Boxer go.
/odomnav_msgs/OdometryPublishes the internal odometry from Boxer's Base Unit, a filtered localization estimate based on wheel odometry (encoders), an integrated IMU, a camera, and a laser.
/imu/module0/datasensor_msgs/IMUPublishes the internal IMU data from Boxer's Base Unit.
/front/scansensor_msgs/LaserScanPublishes the laser scan data from the Base Unit's front localization laser.
/rear/scan/rear/scanPublishes the laser scan data from the Base Unit's rear safety laser.
/realsense/depth/image_rect_rawsensor_msgs/ImagePublishes depth data from the Base Unit's camera.

Boxer Backpack Computer Software Setup​

caution

All of the software instructions in this section apply only to the Backpack Computer, not the software running on the Base Unit. If your Boxer is not equipped with a Backpack Computer, you can skip this section.

Backing Up Robot Configuration​

Upgrading your Clearpath Boxer to ROS Noetic from older ROS distributions is a straightforward process; however it's important to understand that each Boxer is different, having undergone customization to your specifications. For more complete upgrade instructions see this guide.

Please take the time to understand what these modifications are, and how to recreate them on your fresh install of Ubuntu Focal/ROS Noetic.

Performing a Backup​

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

  2. 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/*.launchWill 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.

  3. Please save all the files listed above and use them as a reference during Noetic configuration.

Installing and Configuring Robot Software​

Installing Boxer Software​

note

The physical Boxer robot comes pre-configured with ROS and the necessary Boxer packages already installed on the Backpack Computer; therefore, you will only need to follow the instructions below if you are re-installing software on the Backpack Computer.

note

To install these packages on your computer, ensure that you have added the ROS 1 Noetic and ROS 2 Foxy sources to your apt configuration, as well as Clearpath's package server:

Note that Foxy is only needed if you plan on installing the boxer_robot packages; because of the OTTO 100's ROS 2 API the Foxy version of ros_bridge is required to operate the physical robot.

note

The boxer_manipulation packages are not available as .deb packages, because they have additional dependencies that can only be installed from source. See below for details on building packages from source, and refer to boxer_manipulation on Github for more details on using these packages.

note

During the installation process, you will be asked to enter the robot's serial number. This is stamped on the back of the robot, and will be of the form A31_ followed by a series of numbers. It is important that this serial number be entered correctly. Otherwise you may have errors communicating with the ROS 2 API published by the Base Unit.

note

The OS installation will require an internet connection via ethernet. When connecting an Ethernet cable to Boxer, make sure to use the eno1 Ethernet port on the Backpack Computer, not the Ethernet port on the Base Unit. This eno1 port is the same port normally used for communicating with the Base Unit. If eno1 (sometimes labelled "LAN1") is connected to the Base Unit, disconnect the Base Unit for now. Once the OS has installed you can reconnect the base platform to eno1. You will also need to connect a monitor and keyboard to the Backpack Computer. We recommend connecting the Boxer to its charger during the installation process to ensure it doesn't lose power.

There are three methods to install software on the physical robot.

The preferred method is using the Clearpath Robotics ISO image, which is covered in this section.

The second method is using Debian (.deb) packages, which is also covered in this section.

The final approach is installing from source by directly cloning Clearpath Robotics Github repositories and building them in your ROS (catkin) workspace; however, this method is not covered in this section.

Install from ISO Image​
caution

Installing with the Clearpath Robotics ISO image will completely wipe data on the robot's computer, since the ISO image will install Ubuntu 20.04 (Focal), ROS Noetic, and robot-specific packages.

note

The Clearpath Robotics ISO image only targets Intel-family computers (amd64 architecture). If your robot runs on an Nvidia Jetson computer, see Jetson Software for software installation details.

Clearpath provides a lightly customized installation image of Ubuntu 20.04 "Focal" that automatically pulls in all necessary dependencies for the robot software. To install the software on a physical robot through the Clearpath Robotics ISO image, you will first need a USB drive of at least 2 GB to create the installation media, an ethernet cable, a monitor, and a keyboard.

  1. Download the appropriate Noetic ISO image for your platform.

  2. Copy the image to a USB drive using unetbootin, rufus, balena etcher, or a similar program. For example:

    sudo unetbootin isofile="clearpath-universal-noetic-amd64-0.4.17.iso"

  3. Connect your robot computer to internet access (via wired Ethernet), a keyboard, and a monitor. Make sure that the robot is connected to shore power (where applicable) or that the robot's battery is fully charged.

    caution

    The next step wipes your robot's hard drive, so make sure you have that image backed up.

  4. Boot your robot computer from the USB drive and let the installer work its magic. If asked for a partitioning method choose Guided - use entire disk and set up LVM.

    note

    You may need to configure the computer's BIOS to prioritize booting from the USB drive. On most common motherboards, pressing Delete during the initial startup will open the BIOS for configuration.

  5. The setup process will be automated and may take a long time depending on the speed of your internet connection.

  6. Once the setup process is complete, the computer will turn off. Please unplug the USB drive and turn the computer back on.

  7. On first boot, the username will be administrator and the password will be clearpath. You should use the passwd utility to change the administrator account password.

  8. To set up a factory-standard robot, ensure all your peripherals are plugged in, and run the following command, which will configure a ros upstart service, that will bring up the base robot launch files on boot. The script will also detect any standard peripherals (IMU, GPS, etc.) you have installed and add them to the service.

    rosrun husky_bringup install
    sudo systemctl daemon-reload

  9. Finally, start ROS for the first time. In terminal, run:

    sudo systemctl start ros
Installing from Debian Packages​

If you are installing software on a physical robot through Debian packages, you will first need to ensure that the robot's computer is running Ubuntu 20.04 (Focal) and ROS Noetic.

  1. Before you can install the robot packages, you need to configure Ubuntu's APT package manager to add Clearpath's package server.

    1. Install the authentication key for the packages.clearpathrobotics.com repository. In terminal, run:

      wget https://packages.clearpathrobotics.com/public.key -O - | sudo apt-key add -

    2. Add the debian sources for the repository. In terminal, run:

      sudo sh -c 'echo "deb https://packages.clearpathrobotics.com/stable/ubuntu $(lsb_release -cs) main" > /etc/apt/sources.list.d/clearpath-latest.list'

    3. Update your computer's package cache. In terminal, run:

      sudo apt-get update

  2. After the robot's computer is configured to use Clearpath's debian package repository, you can install the robot-specific packages.

    1. On a physical robot, you should only need the robot packages. In terminal, run:

      sudo apt-get install ros-noetic-husky-robot

    2. Install the robot_upstart job and configure the bringup service so that ROS will launch each time the robot starts. In terminal, run:

      rosrun husky_bringup install
      sudo systemctl daemon-reload

    3. Finally, start ROS for the first time. In terminal, run:

      sudo systemctl start ros

Configuring the Backpack Computer​

If you are installing the packages on Boxer's Backpack Computer, you will need to set up /etc/ros/setup.bash too:

# Mark location of self so that robot_upstart knows where to find the setup file.
export ROBOT_SETUP=/etc/ros/setup.bash

# Setup robot upstart jobs to use the IP from the network bridge.
# export ROBOT_NETWORK=br0

# Insert extra platform-level environment variables here. The six hashes below are a marker
# for scripts to insert to this file.
######

# Pass through to the main ROS workspace of the system.
source /opt/ros/noetic/setup.bash

# Source your catkin workspace
# Make sure to use the complete path, and avoid using envars like $HOME
# Omit this if you do not have a workspace
source /home/administrator/catkin_ws/devel/setup.bash

# Set the ROS_ROBOT_SERIAL_NO and BOXER_API_VERSION envars
# this is required for the Boxer to operate correctly
# The serial number must match the one stamped on the back of the robot
export ROS_ROBOT_SERIAL_NO=A31_0123456789
export BOXER_API_VERSION=v1_3

# Any additional environment variables that depend on your workspace should be exported here
# e.g.
#export BOXER_URDF_EXTRAS=/path/to/boxer_customizations.urdf.xacro

The BOXER_API_VERSION environment variable must be set on the robot's Backpack Computer. This version is determined by the version of the ROS 2 API running on the Base Unit.

At the time of writing the latest version of the OTTO software uses v1_3

The ROS_ROBOT_SERIAL_NO environment variable must match the serial number stamped on the back of the robot. The serial number is case-sensitive, and will begin with A31_, followed by a series of numbers.

Finally, after you have configured /etc/ros/setup.bash you can run the following to create the ROS systemd jobs that will start ROS automatically when the Backpack Computer start up:

source /etc/ros/setup.bash
rosrun boxer_bringup install
sudo systemctl daemon-reload
sudo systemctl start ros
sudo systemctl start ros-bridge

Testing Base Configuration​

You can check that the service has started correctly by checking the logs:

sudo journalctl -u ros

Your Boxer should now be accepting commands from your joystick (see next section). The service will automatically start each time you boot your Boxer's computer.

Pairing the Controller​

PS4 Controller​

To pair a PS4 controller to your robot:

  1. Ensure your controller's battery is charged.

  2. SSH into the robot. The remaining instructions below assume you are already SSH'd into the robot.

  3. Make sure the ds4drv driver is installed, and the ds4drv daemon service is active and running:

    sudo systemctl status ds4drv

  4. If ds4drv is not installed, install it by running:

    sudo apt-get install python-ds4drv

  5. Put the controller into pairing mode by pressing and holding the SHARE and PS buttons until the controller's LED light bar flashes rapidly in white.

  6. Run the controller pairing script:

    sudo ds4drv-pair

  7. In the output of the ds4drv-pair script, you should see that the controller automatically pairs via the script. The controller's LED light bar should also turn solid blue to indicate successful pairing.

Alternatively, if ds4drv-pair fails to detect the controller, you can pair the controller using bluetoothctl:

  1. Install the bluez package if it is not installed already by running:

    sudo apt-get install bluez

  2. Run the bluetoothctl command:

    sudo bluetoothctl

  3. Enter the following commands in bluetoothctl to scan and display the MAC addresses of nearby devices:

    agent on
    scan on

  4. Determine which MAC address corresponds to the controller and copy it. Then run the following commands in bluetoothctl to pair the controller:

    scan off
    pair <MAC Address>
    trust <MAC Address>
    connect <MAC Address>

  5. The controller should now be correctly paired.

Setting up Boxer's Network Configuration​

Boxer is normally equipped with a combination Wi-Fi + Bluetooth module. If this is your first unboxing, ensure that Boxer's wireless antennae are firmly screwed on to the chassis. Boxer is equipped with a Backpack Computer mounted to the top of the Base Unit. The Base Unit is also equipped with an internal computer. This section explains how to configure the networking for the Backpack Computer only. For instructions on connecting the Base Unit's computer to a network, refer to the OTTO 100 Documentation.

Enabling the OTTO App​

Many of Boxer's features are accessible via the OTTO App. This requires configuring the Base Unit to connect to your Wi-Fi network. To do this, connect your laptop to the diagnostic ethernet port on the rear of the Base Unit. Configure your laptop to have a static IP address on the 10.255.255.0/16 subnet, e.g. 10.255.255.100.

Open a web browser and navigate to http://10.255.255.1:8090. You will be promted to enter your network credentials.

Refer to OTTO Motors' documentation for more details on configuring the Base Unit's networking.

First Connection​

By default, Boxer Backpack Computer's Wi-Fi is in client mode, looking for the wireless network at the Clearpath factory.

Set your laptop's ethernet port to a static IP such as 192.168.131.101. To do this in Ubuntu, follow the steps below:

  1. Click on the Wi-Fi icon in the upper-right corner of your screen, and select Edit Connections.
  2. In the Network Connections window, under Ethernet, select your wired connection and then click Edit.
  3. Select the IPv4 Settings tab and then change the Method to Manual.
  4. Click the Add button to add a new address.
  5. Enter a 192.168.131.101 as the static IP under the Address column, and enter 255.255.255.0 under the Netmask column, and then select Save.
Static IP Configuration (Ubuntu)

The next step is to connect to your robot via SSH. To do so execute the following in a terminal window:

ssh administrator@192.168.131.1

You will be promoted to enter a password. The default password is clearpath and you set a new password on first connection.

Changing the Default Password​

note

All Clearpath robots ship from the factory with their login password set to clearpath. Upon receipt of your robot we recommend changing the password.

To change the password to log into your robot, run the following command:

passwd

This will prompt you to enter the current password, followed by the new password twice. While typing the passwords in the passwd prompt there will be no visual feedback (e.g. "*" characters).

To further restrict access to your robot you can reconfigure the robot's SSH service to disallow logging in with a password and require SSH certificates to log in. This tutorial covers how to configure SSH to disable password-based login.

Wi-Fi Setup​

Now that you are connected via SSH over a wired connection using the steps above, you can set up your robot's computer (running Ubuntu 20.04) to connect to a local Wi-Fi network. (For legacy systems running Ubuntu 18.04, use wicd-curses instead.)

Clearpath robots running Ubuntu 20.04 and later use netplan for configuration of their wired and wireless interfaces. To connect your robot to your wireless network using netplan, create the file /etc/netplan/60-wireless.yaml and fill in the following:

network:
  wifis:
    # Replace WIRELESS_INTERFACE with the name of the wireless network device, e.g. wlan0 or wlp3s0
    # Fill in the SSID and PASSWORD fields as appropriate.  The password may be included as plain-text
    # or as a password hash.  To generate the hashed password, run
    #   echo -n 'WIFI_PASSWORD' | iconv -t UTF-16LE | openssl md4 -binary | xxd -p
    # If you have multiple wireless cards you may include a block for each device.
    # For more options, see https://netplan.io/reference/
    WIRELESS_INTERFACE:
      optional: true
      access-points:
        SSID_GOES_HERE:
          password: PASSWORD_GOES_HERE
      dhcp4: true
      dhcp4-overrides:
        send-hostname: true

Modify the following variables in the file:

  1. Replace WIRELESS_INTERFACE with the name of the robot's Wi-Fi interface (e.g. wlan0, wlp2s0, or wlp3s0).
  2. Replace SSID_GOES_HERE with the name of the local Wi-Fi network.
  3. Replace PASSWORD_GOES_HERE with the password of the local Wi-Fi network.

Once you are done modifying the file, save it by pressing CTRL + O, then ENTER. Close the file by pressing CTRL + X.

Then, run the following to bring up the Wi-Fi connection:

sudo netplan apply

You can validate that the connection was successful and determine the IP address of the Wi-Fi interface by running:

ip a

A list of network connections will be displayed within the terminal. Locate the wireless network and make note of its IP address.

Now that you know robot's wireless IP address, you may now exit the Ethernet SSH session by executing exit.

Remove the Ethernet cable and close up your robot. Now you can SSH into your robot over the wireless network. To do so, execute:

ssh administrator@<IP_OF_ROBOT>

SSH sessions allow you to control your robot's internal computer. You can do various things such as download packages, run updates, add/remove files, transfer files etc.

Installing Remote Computer Software​

note

This step is optional.

It is often convenient to use a Remote Computer (eg. laptop) to command and observe your robot. To do this, your Remote Computer must be configured correctly.

  1. Perform a basic ROS installation. See here for details.

  2. Install the desktop packages:

    sudo apt-get install ros-noetic-husky-desktop

  3. Configure Remote ROS Connectivity.

    Click to expand

    To use ROS desktop tools, you will need the Remote Computer to be able to connect to your robot's ROS master. This will allow you to run ROS commands like rostopic list, rostopic echo, rosnode list, and others, from the Remote Computer and the output will reflect the activity on your robot's ROS master, rather than on the Remote Computer. This can be a tricky process, but we have tried to make it as simple as possible.

    In order for the ROS tools on the Remote Computer to talk to your robot, they need to know two things:

    • How to find the ROS master, which is set in the ROS_MASTER_URI environment variable, and
    • How processes on the ROS master can find the Remote Computer, which is the ROS_IP environment variable.

    The suggested pattern is to create a file in your home directory called remote-robot.sh with the following contents:

    export ROS_MASTER_URI=http://cpr-robot-0001:11311 # Your robot's hostname
    export ROS_IP=10.25.0.102 # Your Remote Computer's wireless IP address

    If your network does not already resolve your robot's hostname to its wireless IP address, you may need to add a corresponding line to the Remote Computer's /etc/hosts file:

    10.25.0.101 cpr-robot-0001
    note

    You can verify the hostname and IP address of your robot using the following commands during an SSH session with the Onboard Computer.

    hostname
    hostname -i

    Then, when you are ready to communicate remotely with your robot, you can source that script like so, thus defining those two key environment variables in the present context.

    source remote-robot.sh

    To verify that everything is set up properly, try running a few ROS commands:

    rosrun rqt_robot_monitor rqt_robot_monitor
    rosrun rqt_console rqt_console

    You can also run the RViz commands outlined in the Tutorials.

    If the tools launch, then everything is setup properly. If you still need assistance in configuring remote access, please contact Clearpath Support. For more general details on how ROS works over TCP with multiple machines, please see: http://wiki.ros.org/ROS/Tutorials/MultipleMachines. For help troubleshooting a multiple machines connectivity issue, see: http://wiki.ros.org/ROS/NetworkSetup.

  4. From your Remote Computer, try launching RViz, the standard ROS robot visualization tool:

    roslaunch husky_viz view_robot.launch

    From within RViz, you can use interactive markers to drive your robot, you can visualize its published localization estimate and you can visualize any attached sensors which have been added to its robot description XML URDF.

Adding a Source Workspace​

Configuring non-standard peripherals requires a source workspace on the robot computer.

tip

The instructions below use cpr_noetic_ws as the workspace name. You can choose a different workspace name and substitute it in the commands below.

  1. Create a new workspace:

    mkdir -p ~/cpr_noetic_ws/src

  2. Add any custom source packages to the ~/cpr_noetic_ws/src directory.

  3. After adding your packages, make sure any necessary dependencies are installed:

    cd ~/cpr_noetic_ws/
    rosdep install --from-paths src --ignore-src --rosdistro noetic -y

  4. Build the workspace:

    cd ~/cpr_noetic_ws/
    catkin_make

  5. Modify your robot-wide setup file (/etc/ros/setup.bash) to source your new workspace instead of the base noetic install:

    source /home/administrator/cpr_noetic_ws/devel/setup.bash

  6. Reinitialize your environment so that it picks up your new workspace:

    source /etc/ros/setup.bash

Reconfiguring the Network Bridge​

In the event you must modify Boxer's ethernet bridge, you can do so by editing the Netplan configuration file found at /etc/netplan/50-clearpath-bridge.yaml:

network:
  version: 2
  renderer: networkd
  ethernets:
    # Configure eno1 to communicate with the OTTO 100 internal computer via the attachment port
    eno1:
      dhcp4: no
      dhcp6: no
      addresses:
        - 10.252.252.100/16

    # Bridge all the remaining ethernet ports together
    bridge_eth:
      dhcp4: no
      dhcp6: no
      match:
        name: eth*
    bridge_enp:
      dhcp4: no
      dhcp6: no
      match:
        name: enp*
    bridge_enx:
      dhcp4: no
      dhcp6: no
      match:
        name: enx*
  bridges:
    br0:
      # yes, allow DHCP4 connections on the bridge; this allows the Backpack Computer to accept
      # wired internet connections, e.g. for installing updates
      dhcp4: yes
      dhcp6: no
      interfaces: [bridge_eth, bridge_enp, bridge_enx]
      addresses:
        # Give the bridge the static 192.168.131.1 address for its internal ROS network
        # Any IP-based ROS sensors connected to the backpack should use the 192.168.131.0/24 subnet
        - 192.168.131.1/24

This file will create a bridged interface called br0 that will have a static address of 192.168.131.1, but will also be able to accept a DHCP lease when connected to a wired router. By default all network ports named en* and eth* are added to the bridge. This includes all common wired port names, such as:

  • eth0
  • eno1
  • enx0123456789ab
  • enp3s0
  • etc

To include/exclude additional ports from the bridge, edit the match fields, or add additional bridge_* sections with their own match fields, and add those interfaces to the interfaces: [bridge_en, bridge_eth] line near the bottom of the file.

We do not recommend changing the static address of the bridge to be anything other than 192.168.131.1; changing this may cause sensors that communicate over ethernet (e.g. lidars, cameras, GPS arrays) from working properly.

Using Boxer​

Simulating Boxer​

Whether you actually have a Boxer robot or not, the Boxer simulator is a great way to get started with ROS robot development. In this tutorial, we will go through the basics of starting Gazebo and RViz and how to drive your Boxer around.

Installation​

To get started with the Boxer simulation, make sure you have a working ROS installation set up on your Ubuntu desktop, and install the Boxer-specific metapackages for desktop and simulation:

sudo apt-get install ros-noetic-boxer-simulator ros-noetic-boxer-desktop

Launching Gazebo​

Gazebo is the most common simulation tool used in ROS. Boxer's model in Gazebo include reasonable approximations of its dynamics, including wheel slippage, skidding, and inertia. To launch simulated Boxer in a simple example world, run the following command:

roslaunch boxer_gazebo boxer_world.launch

You should see the following window appear, or something like it. You can adjust the camera angle by clicking and dragging while holding CTRL, ALT, or the Shift key.

Simulated Boxer

The window which you are looking at is the Gazebo Client. This window shows you the "true" state of the simulated world which the robot exists in. It communicates on the backend with the Gazebo Server, which is doing the heavy lifting of actually maintaining the simulated world. At the moment, you are running both the client and server locally on your own machine, but some advanced users may choose to run heavy duty simulations on separate hardware and connect to them over the network.

note

When simulating, you must leave Gazebo running. Closing Gazebo will prevent other tools, such as RViz (see below) from working correctly.

Launching RViz​

The next tool we will encounter is RViz. Although superficially similar in appearance to Gazebo, RViz has a very different purpose. Unlike Gazebo, which shows the reality of the simulated world, RViz shows the robot's perception of its world, whether real or simulated. So while Gazebo won't be used with your real Boxer, RViz is used with both.

You can use the following launch invocation to start RViz with a predefined configuration suitable for visualizing any standard Boxer config.

roslaunch boxer_viz view_robot.launch

You should see RViz appear.

Boxer RViz

The visualization shows the depth data from the Base Unit's RealSense camera (the rainbow-colored points) as well as the data from the front and rear lidars.

Driving with Interactive Controller​

RViz will also show Boxer's interactive markers around your Boxer's model. These will appear as a blue ring and red arrows. Depending on your robot, there will also be green arrows. If you don't see them in your RViz display, select the Interact tool from the top toolbar and they should appear.

Drag the red arrows in RViz to move in the linear X direction, and the blue circle to move in the angular Z direction. If your robot supports lateral/sideways movement, you can drag the green arrows to move in the linear Y direction. RViz shows you Boxer moving relative to its odometric frame, but it is also moving relative to the simulated world supplied by Gazebo. If you click over to the Gazebo window, you will see Boxer moving within its simulated world. Or, if you drive real Boxer using this method, it will have moved in the real world.

All of Clearpath's robots use the same coordinate system, shown below:

Boxer Coordinate System
AxisPositive MeaningNegative Meaning
XLinear motion forwardsLinear motion backwards
YLinear motion leftLinear motion right
ZLinear motion upLinear motion down
X^ (roll)Roll to the rightRoll to the left
Y^ (pitch)Pitch downPitch up
Z^ (yaw)Rotate leftRotate right

Boxer, in its default configuration, will treat the linear Y and Z axes, as well a the angular X and Y axes, as zero at all times; the robot is incapable of moving in these directions.

Once you start your own development, have your nodes send geometry_msgs/Twist commands to the cmd_vel topic to drive Boxer, either real or simulated. This is the standard ROS interface to differential-drive and holonomic ground vehicles.

The geometry_msgs/Twist message includes fields for linear X/Y/Z in m/s, as well as fields for angular X/Y/Z in rad/s.

$ rosmsg info geometry_msgs/Twist
geometry_msgs/Vector3 linear
  float64 x
  float64 y
  float64 z
geometry_msgs/Vector3 angular
  float64 x
  float64 y
  float64 z

Control​

There are three ways to send your Boxer control commands:

  1. Using the provided PS4 controller. Refer to the User Manual details on how to use the controller.

  2. Using the RViz instance above. If you select the Interact option in the top toolbar, an interactive marker will appear around the Boxer and can be used to control speed.

  3. The rqt_robot_steering plugin. Run the rqt command, and select Plugins→Robot Tools→Robot Steering from the top menu.

Boxer uses twist_mux to mix separate geometry_msgs\Twist control channels into the /cmd_vel topic.

Additional velocity channels can be defined in twist_mux.yaml, or can be piped into the lowest-priority /cmd_vel topic.

Additional Simulation environments​

Boxer is supported by Clearpath's additional simulation environments. To use these environments, clone the repository into your workspace and build it:

cd $HOME/catkin_ws/src
git clone https://github.com/clearpathrobotics/cpr_gazebo.git -b noetic-devel
cd ..
rosdep install --from-paths src --ignore-src --rosdistro=noetic -r
catkin_make
source devel/setup.bash

Note that you may get warnings about missing dependencies for e.g. warthog_gazebo or jackal_gazebo. These dependencies are only needed if you intend to simulate Clearpath's other robotic platforms in these environments. If you only intend to simulate Boxer, you can safely ignore these missing dependencies.

Because Boxer is an indoor platform, it is only usable in the cpr_office_gazebo and cpr_obstacle_gazebo environments

To launch Boxer in the office environment, use:

roslaunch cpr_office_gazebo office_world.launch platform:=boxer
Boxer in the Office World

To launch Boxer in the obstacle environment, use

roslaunch cpr_obstacle_gazebo cpr_obstacle_world.launch platform:=boxer
Boxer in the Obstacle World

Driving Boxer​

There are four ways to drive Boxer and each way will work on a physical Boxer robot as well as on a simulated Boxer.

  1. Using the interactive remote controller in RViz. See Simulating Boxer.
  2. Using autonomous navigation. See Navigating Boxer.
  3. Using the controller for teleoperation. See below.
  4. Publishing ROS messages. See below.
danger

Boxer is capable of reaching high speeds. Careless driving can cause harm to the operator, bystanders, the robot, or other property. Always remain vigilant, ensure you have a clear line of sight to the robot, and operate the robot at safe speeds. We strongly recommend driving in normal (slow) mode first, and only enabling turbo in large, open areas that are free of people and obstacles.

Driving with Remote Controller​

note

For instructions on controller pairing, see Pairing the Controller.

caution

When familiarizing yourself with your robot's operation, always hold the left button (L1/LB). Once you are comfortable with how it operates and you are in a large area with plenty of open room, then you can use R1/RB to enable turbo mode.

Differential Drive Robots (Husky, Jackal, Dingo-D, Warthog, Boxer)​

To drive your differential drive robot, Axis 0 controls the robot's steering, Axis 1 controls the forward/backward velocity, Button 4 acts as enable, and Button 5 acts as enable-turbo. On common controllers these correspond to the following physical controls:

Axis/ButtonPhysical InputPS4F710Xbox OneAction
Axis 0Left thumb stick verticalLJLJLJDrive forward/backward
Axis 1Left thumb stick horizontalLJLJLJRotate/turn
Button 4Left shoulder button or triggerL1LBLBEnable normal speed
Button 5Right shoulder button or triggerR1RBRBEnable turbo speed
note

You must hold either Button 4 or Button 5 at all times to drive the robot.

Omnidirectional Robots (Dingo-O, Ridgeback)​

To drive your omnidirectional robot, Axis 0 controls the robot's steering, Axis 1 controls the robot's left/right translation, and Axis 2 controls the forward/backward velocity. Button 4 acts as enable, and Button 5 acts as enable-turbo. On common controllers these correspond to the following physical controls:

Axis/ButtonPhysical InputPS4F710Xbox OneAction
Axis 0Left thumb stick verticalLJLJLJDrive forward/backward
Axis 1Left thumb stick horizontalLJLJLJTranslate left/right
Axis 2Right thumb stick horizontalRJRJRJRotate/turn
Button 4Left shoulder button or triggerL1LBLBEnable normal speed
Button 5Right shoulder button or triggerR1RBRBEnable turbo speed
note

You must hold either Button 4 or Button 5 at all times to drive the robot.

Driving with ROS Messages​

You can manually publish geometry_msgs/Twist ROS messages to the /cmd_vel ROS topic to drive Boxer.

For example, in terminal, run:

rostopic pub /cmd_vel geometry_msgs/Twist '{linear: {x: 0.5, y: 0.0, z: 0.0}, angular: {x: 0.0, y: 0.0, z: 0.0}}'

The command above makes Boxer drive forward momentarily at 0.5 m/s without any rotation.

Extending Boxer Startup​

Now that you've had Boxer for a while, you may be interested in how to extend it, perhaps add some more payloads, or augment the URDF.

Startup Launch Context​

When ROS packages are grouped together in a directory and then built as one, the result is referred to as a workspace. Each workspace generates a setup.bash file which the user may source in order to correctly set up important environment variables such as PATH, PYTHONPATH, and CMAKE_PREFIX_PATH.

The standard system-wide setup file is in /opt:

source /opt/ros/noetic/setup.bash

When you run this command, you'll have access to rosrun, roslaunch, and all the other tools and packages installed on your system from Debian packages.

However, sometimes you want to add additional system-specific environment variables, or perhaps packages built from source. For this reason, Clearpath platforms use a wrapper setup file, located in /etc/ros:

source /etc/ros/setup.bash

This is the setup file which gets sourced by Boxer's background launch job, and in the default configuration, it is also sourced on your login session. For this reason it can be considered the "global" setup file for Boxer's ROS installation.

This file sets some environment variables and then sources a chosen ROS workspace, so it is one of your primary modification points for altering how Boxer launches.

Launch Files​

The second major modification point is the /etc/ros/noetic/ros.d directory. This location contains the launch files associated with the ros background job. If you add launch files here, they will be launched with Boxer's startup.

However, it's important to note that in the default configuration, any launch files you add may only reference ROS software installed in /opt/ros/noetic. If you want to launch something from workspace in the home directory, you must change /etc/ros/setup.bash to source that workspace's setup file rather than the one from /opt.

Adding URDF​

There are two possible approaches to augmenting Boxer's URDF. The first is that you may simply set the BOXER_URDF_EXTRAS environment variable in /etc/ros/setup.bash. By default, it points to an empty dummy file, but you can point it to a file of additional links and joints which you would like mixed into Boxer's URDF (via xacro) at runtime.

The second, more sophisticated way to modify the URDF is to create a new package for your own robot, and build your own URDF which wraps the one provided by boxer_description.

Keeping Boxer Updated​

For details on updating Boxer software or firmware, refer to Software Maintenance.

note

Boxer includes the latest autonomy software from OTTO, including Fleet Manager.

Please refer to OTTO Motors' documentation and the OTTO 100 user manual for details on how to use OTTO's advanced autonomy software

This section explains how to use basic navigation demos with Boxer. These examples can be used with a simulated Boxer or with the physical robot. Note that if you are using the physical Boxer you also have access to the much more advanced OTTO autonomy software.

To get all Navigation related files for Boxer, run:

sudo apt-get install ros-noetic-boxer-navigation

Below are the example launch files for three different configurations for navigating Boxer:

  • Navigation in an odometric frame without a map, using only move_base.
  • Generating a map using Gmapping.
  • Localization with a known map using amcl.

If you are working in a simulation, bring up Boxer using the following command:

roslaunch boxer_gazebo boxer_race.launch

This will spawn Boxer in a relatively enclosed environment

Boxer in its simulated environment

If you're working with a real Boxer, it's suggested to connect wirelessly via SSH and launch the ROS launch files from onboard the robot. You'll need to have bidirectional communication with the robot's roscore in order to launch RViz on your workstation (see here).

In the odometry navigation demo Boxer attempts to reach a given goal in the world within a user-specified tolerance. The 2D navigation, generated by move_base, takes in information from odometry, laser scanner, and a goal pose and outputs safe velocity commands. In this demo the configuration of move_base is set for navigation without a map in an odometric frame (that is, without reference to a map).

To launch the navigation demo, run:

roslaunch boxer_navigation odom_navigation_demo.launch

To visualize with the suggested RViz configuration launch:

roslaunch boxer_viz view_robot.launch config:=navigation
Boxer driving to its 2D Nav Goal in RViz

To send goals to the robot, select the 2D Nav Goal tool from the top toolbar, and then click anywhere in the RViz view to set the position. Alternatively, click and drag slightly to set the goal position and orientation.

If you wish to customize the parameters of move_base, local costmap, global costmap and base_local_planner, clone boxer_navigation into your own workspace and modify the corresponding files in the params subfolder.

Making a Map​

Gmapping is an open-source tool for Simultaneous Localization And Mapping, or SLAM. SLAM allows a robot to build a map of its environment while exploring, making it helpful when the robot is in unfaimilar environments.

This section explains how to produce a map using Gmapping. We will use this map to set 2D nav goals in the following section.

To begin, run the following command:

roslaunch boxer_navigation gmapping.launch

And on your workstation, launch RViz with the suggested configuration:

roslaunch boxer_viz view_robot.launch config:=gmapping
note

If you are driving a simulated Boxer you may find it easyer to launch RViz without the gmapping configuration:

roslaunch boxer_viz view_robot.launch
RViz with Boxer's Gmapping configuration

Now slowly drive the robot around to produce a map. If you are driving the robot using the interactive controls in RViz you may find it helpful to change the visulaization's fixed frame from map or odom to base_link. Doing so will keep the robot in a fixed position in the window, while the world rotates around the robot.

When you're satisfied, you can save the produced map using map_saver:

rosrun map_server map_saver -f mymap

This will create a mymap.yaml and mymap.pgm file in your current directory.

The resulting map should look something like this:

Boxer's exported map

Using amcl, Boxer is able to globally localize itself in a known map. AMCL takes in information from odometry, laser scanner and an existing map and estimates the robot's pose.

To start the AMCL demo:

roslaunch boxer_navigation amcl_demo.launch map_file:=/path/to/my/map.yaml

If you don't specify map_file, it defaults to an included pre-made map of the default "Boxer World" environment which Boxer's simulator spawns in. If you're using a real Boxer in your own environment, you'll definitely want to override this with the map created using the Gmapping demo.

Before navigating, you need to initialize the localization system by setting the pose of the robot in the map. This can be done using 2D Pose Estimate in RViz or by setting the amcl initial_pose parameters. To visualize with the suggested RViz configuration launch:

roslaunch boxer_viz view_robot.launch config:=localization

When RViz appears, select the Set 2D Pose tool from the toolbar, and click on the map to indicate to the robot approximately where it is.

Advanced Mapping​

If you have an application which requires faster or more accurate SLAM capabilities, our commercial offerings may be a good fit for your team. Please get in touch for more details.

Boxer Tests​

Boxer robots come preinstalled with a set of test scripts as part of the boxer_tests ROS package, which can be run to verify robot functionality at the component and system levels.

If your Boxer does not have the boxer_tests ROS package installed already, you can manually install it by opening terminal and running:

sudo apt-get install ros-noetic-boxer-tests

ROS Tests​

The ros_tests script exposes a set of interactive tests to verify the functionality of core features. These tests run at the ROS-level via ROS topics, and serve as a useful robot-level diagnostic tool for identifying the root cause of problems, or at the very least, narrowing down on where the root cause(s) may be.

Running ROS Tests​

To run ros_tests on a Boxer robot, open terminal and run:

rosrun boxer_tests ros_tests

Upon running ros_tests, a list of available tests will be shown in a menu. From the menu, you can choose individual tests to run, or simply choose the option to automatically run all the tests.

The details of each test are shown below.

  • Serial Number Test

    The Serial Number Test checks that the robot's serial number is set correctly.

    This test checks the ROS_ROBOT_SERIAL_NO environment variable is set to a valid serial number.

  • API Version Test

    The API Version Test checks that the robot's API version is set correctly.

    This test checks the BOXER_API_VERSION environment variable is set to a valid API version, and that the robot is publishing data on ROS topics under this API version.

  • ROS Bridge Test

    The ROS Bridge Test checks that the ROS bridge is working properly, and that the robot's description model is loaded.

    This test checks that the list of expected ROS topics from the ROS bridge exist, and that these ROS topics are publishing data at the expected frequencies. The expected ROS topics are published by the robot's Base Unit, and the ROS bridge "bridges" these ROS topics to the robot's Backpack Computer, including the Base Unit's IMU, camera, laser, and battery data.

    This test also the robot's model is loaded into the robot_description ROS parameter.

  • Emergency Stop Test

    The Emergency Stop Test checks that the robot's emergency stop is working properly.

    This test subscribes to the /platform/emergency_stop ROS topic and checks that when the emergency stop is manually engaged and disengaged by the user, the emergency stop states are correctly reported on the /platform/emergency_stop ROS topic.

  • Rotate Test

    The Rotate Test rotates the robot counter clockwise 2 full revolutions and checks that the motors, IMU, and EKF odometry are working properly.

    This test:

    • Subscribes to the /imu/module1/data ROS topic to receive angular velocity measurements from the IMU's Gyroscope. These measurements are converted into angular displacement estimations, and the robot will rotate until 2 full revolutions are estimated.
    • Subscribes to the /odom ROS topic to receive angular velocity estimations from the EKF odometry. These measurements are converted into angular displacement estimations, and are output as comparison to the angular displacement estimations from the IMU's Gyroscope.
    • Publishes to the /cmd_vel ROS topic to send drive commands to rotate the robot.
    • The user will be asked to verify that the robot rotates 2 full revolutions.
    note

    The Rotate Test rotates the robot using the IMU's Gyroscope data, which inherently will not be 100% accurate. Therefore, some undershoot/overshoot is to be expected.

  • Drive Test

    The Drive Test drives the robot forward 1 metre and checks that the motors, and EKF odometry are working properly.

    This test:

    • Subscribes to the /odom ROS topic to receive linear displacement estimations from the EKF odometry. The robot will drive forward until 1 metre is estimated, then it will drive backward until 1 metre is estimated.
    • Publishes to the /cmd_vel ROS topic to send drive commands to drive the robot.
    • The user will be asked to verify that the robot drives forward 1 metre.
    note

    The Drive Test drives the robot using the Odometry data, which inherently will not be 100% accurate. Therefore, some undershoot/overshoot is to be expected.

Last updated on