Skip to main content

Husky Tutorials (ROS2)

Husky Overview


Husky is a rugged, outdoor-ready unmanned ground vehicle (UGV), suitable for research and rapid prototyping applications. These tutorials will assist you with setting up and operating your Husky. The tutorial topics are listed in the right column and presented in the suggested reading order.

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


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


These tutorials specifically target Husky robots running Ubuntu 20.04 with ROS2 Foxy.

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

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

Using Husky describes how to simulate and drive your Husky. Simuation is a great way for most users to learn more about their Husky; understanding how to effectively operate Husky in simulation is valuable whether you are in the testing phase with software you intend to ultimately deploy on a physical Husky, or you do not have one and are simply exploring the platform's capabilities. Driving Husky covers how to teleoperate Husky 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.

Advanced Topics covers items that are only required in atypical situations.

Husky ROS Packages

Husky fully supports ROS; all of the packages are available in Husky Github.

Description Package

The husky_description repository provides a URDF model of Husky.

Husky's URDF model can be visualized in RViz and can be customized and extended through the use of several environment variables. Once you have installed the desktop software in an upcoming tutorial, you will be able to run:

ros2 launch husky_viz
Husky model

Husky Software Setup

Installing and Configuring Robot Software

Backing Up Robot Configuration

Upgrading your Clearpath Husky to ROS2 Foxy from older ROS distributions (including ROS1) is supported; however it's important to understand that each Husky is different, having undergone customization to your specifications.

Please take the time to understand what these modifications are and how to recreate them on your fresh install of Ubuntu Focal + ROS2 Foxy.

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:

    /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 Ubuntu OS + ROS2

Upgrading Ubuntu OS Version (Optional)

If you already have Ubuntu 20.04 installed, you can skip this step.

ROS2 specifically targets Ubuntu 20.04; therefore, if your computer is currently running an older Ubuntu OS version (e.g. Ubuntu 18.04 for ROS1 Melodic, or Ubuntu 16.04 for ROS2 Kinetic), you will need to update it to Ubuntu 20.04.

The recommended method of installing Ubuntu 20.04 is from an ISO via a bootable USB drive. The Ubuntu 20.04 ISO can be found from Ubuntu's official releases.

On any computer:

  1. Download the .iso file from the link above.
  2. Insert a USB drive.
  3. Write the downloaded Ubuntu 20.04 ISO to the USB drive using a software such as Rufus, Etcher, or UNetbootin. This will erase all data already on the USB drive, so make sure you have backed up anything important!

On the computer to be upgraded to Ubuntu 20.04:

  1. Ensure that it is turned off and has internet access via ethernet.
  2. Insert the newly formatted USB drive.
  3. Turn on and choose to boot from the USB drive.
  4. The installer should run automatically. Step through any prompts that come up. The computer will turn off automatically when the installation completes.
  5. Once the computer turns off, remove the USB drive and turn on the computer. It will now be running your fresh install of Ubuntu 20.04.
Removing ROS1 Noetic (Optional)

If ROS1 Noetic was not previously installed, you can skip this step.

If ROS1 Noetic was previous installed and there is a systemd job to start it on boot, it must be disabled to use ROS2 on boot. This can be done by running:

source /opt/ros/noetic/setup.bash
rosrun robot_upstart uninstall ros
Installing ROS2

Simply follow the official ROS2 Foxy installation instructions to install ROS2 Foxy on your Ubuntu 20.04 computer.

If your Ubuntu 20.04 computer for some reason has ROS1 Noetic installed already, you will just need to source the desired ROS version and distribution before using it.

For example:

source /opt/ros/foxy/setup.bash # Run this command to use ROS2 Foxy
source /opt/ros/noetic/setup.bash # Run this command to use ROS1 Noetic

Installing Husky Software


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


If you wish to install the Husky packages on your computer (e.g. to interface with the physical Husky robot and/or to simulate Husky), then proceed with the following instructions below. A prequisite is to make sure you have a working ROS2 Foxy installation set up on your computer.

Add Clearpath Debian Package Repository

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

  1. Install the authentication key for the repository. In a terminal, run:

    wget -O - | sudo apt-key add -
  2. Add the debian sources for the repository. In a terminal, run:

    sudo sh -c 'echo "deb $(lsb_release -cs) main" > /etc/apt/sources.list.d/clearpath-latest.list'
  3. Update your computer's package cache. In a terminal, run:

    sudo apt-get update
Installing from Debian Packages

The preferred way to install robot-specific packages is using precompiled Debian packages. These packages are available for Ubuntu 20.04.

After your computer is configured to use Clearpath's debian package repository, you can install the robot-specific packages needed for this tutorial. In a terminal, run:

sudo apt-get install ros-foxy-husky-desktop ros-foxy-husky-simulator

The <ROBOT>_robot package only needs to be installed on the physical robot; however, you can optionally install it on your computer too. In a terminal, run:

sudo apt-get install ros-foxy-husky-robot
Installing from Source

Robot packages are available on GitHub, and can be compiled and installed from source if desired:

  1. Create a workspace directory. In a terminal, run:

    mkdir -p ~/cpr_ws/src
  2. Clone the repositories into your workspace directory. In terminal, run:

    cd ~/cpr_ws/src
    git clone -b foxy-devel
    cd ..
  3. Install additional dependencies. In a terminal, run:

    rosdep install --from-paths src --ignore-src --rosdistro=$ROS_DISTRO -y
  4. Build the workspace. In a terminal, run:

    colcon build
  5. You can now source your workspace to make use of the packages you just built. In a terminal, run:

    source install/setup.bash
  6. If you would like ROS to run on boot run:

    ros2 run jackal_bringup install

Testing Base Configuration

After installing the software, check that the system has started correct.

  1. The COMM light on your Husky should go from red to green.

  2. Your Husky should be accepting commands from your joystick (see next section).

Pairing the Controller

Joystick controllers are used for teleoperation; they allow you to remotely drive the Husky, whether it is a physical Husky robot, or a simulated Husky. The following instructions below detail how to pair different controllers to the Husky's computer; however, these instructions can also be used to pair these controllers to your own computer.

PS4 Controller

If your Husky comes with a PS4 controller, it will be paired already. Simply turn on the Husky and turn on the 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.

Logitech F710 Controller

Logitech controllers are not considered safe, and usage should be experimental only. If your robot has bluetooth capabilities, please switch to using a PS4 controller instead.

To re-pair the Logitech F710 controller or pair a new Logitech F710 controller, plug the controller's USB dongle into the Husky's computer and turn on the controller. The controller pairs automatically.

Setting up Husky's Network Configuration

Husky is normally equipped with a combination Wi-Fi + Bluetooth module. If this is your first unboxing, ensure that Husky's wireless antennae are firmly screwed on to the chassis. Some Husky robots may only be equipped with a single antenna, depending on the exact model of computer installed in the robot.

First Connection

By default, Husky'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 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 as the static IP under the Address column, and enter 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@

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


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:


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:

# 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
optional: true
dhcp4: true
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.

Remote ROS2 Connection


This step is optional.

It is useful to connect your laptop to the same ROS2 network as your robot, particularly if you want to interface with it through ROS2 topics, services, and actions:

  1. Ensure that your laptop has ROS2 Foxy installed.

  2. Connect your robot's computer and your laptop to the same (wired or wireless) network.

  3. Verify that your robot's computer can ping your laptop. In a terminal on your robot's computer, run:

    ping <YOUR_LAPTOP_IP>
  4. Verify that your laptop can ping your robot's computer. In a terminal on your laptop, run:

  5. You should be able to now be able to access your robot's ROS2 data from your laptop, such as viewing ROS2 topics. In a terminal on your laptop, run:

    source /opt/ros/foxy/setup.bash
    ros2 topic list
  6. If you are unable to access your robot's ROS2 data from your laptop, make sure to set the ROS_DOMAIN_ID environment variable on your laptop to the same value as on your robot's computer. By default, ROS_DOMAIN_ID is set to 0 (in ROS2 and on your robot), so you will not need to do this step. However, if ROS_DOMAIN_ID is set to a different value on your robot, make sure to do the same on your laptop. In a terminal on your laptop, run:

    source /opt/ros/foxy/setup.bash

You should now be able to access your robot's ROS2 data (e.g. topics, services, and actions) from your laptop.

Using Husky

Simulating Husky

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


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

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

Launching Gazebo

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

ros2 launch husky_gazebo

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 Husky in the Play Pen

To stop the simulation, close the Gazebo window, and then CTRL-C out of the terminal process.

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

Launch 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 Husky, RViz is used with both.


If you are working with a simulated robot you should leave Gazebo running and open a new terminal to launch RViz. If you installed the Husky simulation packages from source, make sure to run source devel/setup.bash in the workspace where the packages are installed when opening the new terminal.

You can using the following launch invocation to start RViz with a pre-cooked configuration suitable for visualizing any standard Husky config:

ros2 launch husky_viz

You should see RViz appear:

Husky in RViz

Driving Husky

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

  1. Using the interactive remote controller in RViz. See Simulating Husky.
  2. Using autonomous navigation. This will be covered in a future tutorial.
  3. Using the controller for teleoperation. See below.
  4. Publishing ROS2 messages. See below.

Husky is a heavy, robot 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


For instructions on controller pairing, Pairing the Controller.


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

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

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

Using Remote Control with Gazebo

You can also use a remote controller to drive your robot in Gazebo. To set up your computer for teleop using the remote controller follow these steps:

  1. Connect the controller to your computer.

  2. Set the HUSKY_JOY_DEVICE environment variable to point to your game controller device Normally this will be /dev/input/js0.

  3. Launch Gazebo as described in Simulation.

Driving with ROS2 Messages

You can manually publish geometry_msgs/Twist ROS2 messages to either the /husky_velocity_controller/cmd_vel_unstamped or the /cmd_vel ROS2 topics to drive Husky.

For example, in a terminal, run:

ros2 topic pub --once /husky_velocity_controller/cmd_vel_unstamped geometry_msgs/msg/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 Husky drive forward momentarily at 0.5 m/s without any rotation. To have Husky move forward continually, remove --once and add --rate 10 to the command above.

Keeping Husky Updated

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

Advanced Topics

Configuring the Network Bridge

Your computer is configured to bridge its physical network ports together. This allows any network port to be used as a connection to the internal network for connecting sensors, diagnostic equipment, or manipulators, or for connecting the your robot to the internet for the purposes of installing updates.

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

# Configure the wired ports to form a single bridge
# We assume wired ports are en* or eth*
# This host will have address

version: 2
renderer: networkd
dhcp4: no
dhcp6: no
name: eth*
dhcp4: no
dhcp6: no
name: en*
dhcp4: yes
dhcp6: no
interfaces: [bridge_en, bridge_eth]

This file will create a bridged interface called br0 that will have a static address of, 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; changing this may cause sensors that communicate over Ethernet (e.g. lidars, cameras, GPS arrays) from working properly.


See also Network IP Addresses for common IP addresses on Clearpath robots.

Jetson Installation

Refer to the Jetson page for details on installing a Jetson in Husky. However, at present, ROS2 software is not supported on Jetson in Husky.


Clearpath is committed to your success. Please get in touch with us and we will do our best to get you rolling again quickly:

To get in touch with a salesperson regarding Clearpath Robotics products, please email

If you have an issue that is specifically about ROS and is something which may be of interest to the broader community, consider asking it on If you do not get a satisfactory response, please ping us and include a link to your question as posted there. If appropriate, we will answer in the ROS Answers context for the benefit of the community.