Skip to main content

Dingo Tutorials

Dingo Overview​

Introduction​

Dingo a lightweight and easy-to-use unmanned indoor ground vehicle for ROS, suitable for research and rapid prototyping applications. These tutorials will assist you with setting up and operating your Dingo. 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.

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 Dingo robots running Ubuntu 20.04 with ROS Noetic, as it is the standard OS environment for Dingo. If instead you have an older Dingo robot running Ubuntu 18.04 with ROS Melodic, please follow this tutorial to upgrade the robot OS environment to Ubuntu 20.04 with ROS Noetic.

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

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

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

Navigating Dingo 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 Dingo is equipped with a laser scanner.

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

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

Dingo ROS Packages​

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

Description Package​

The dingo_description repository provides a URDF model of Dingo.

Dingo'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 dingo_viz view_model.launch
Dingo model

Environment Variables​

Dingo can be customized and extended through the use of several environment variables. These are summarized in the README file. Some of the most important ones are listed below.

VariableDefaultDescription
DINGO_OMNI0Set to 1 to switch from Dingo-D to Dingo-O (with omnidirectional wheels)
DINGO_LASER0Set to 1 to equip Dingo with a primary lidar unit, normally front-facing
DINGO_LASER_SECONDARY0Set to 1 to equip Dingo with a secondary lidar unit, normally rear-facing
DINGO_LASER_3D0Set to 1 to equip Dingo with a primary 3D lidar unit, normally front-facing
DINGO_REALSENSE0Set to 1 to equip Dingo with a RealSense depth camera
DINGO_IMU_MICROSTRAIN0Set to 1 to equip Dingo with a Microstrain IMU

Mounting points​

Dingo-D has 6 evenly-spaced mounting points along its center channel for mounting sensors and other accessories. Dingo-O has 7 similar mounting points. The centers of these mounting points are represented as links in the URDF to facilitate adding sensors to simulated robots and modelling collisions when planning arm motions for mobile manipulation.

Link (front to back)Dingo-DDingo-O
front_mountYesYes
front_b_mountYesYes
front_c_mountYesYes
mid_mountNoYes
rear_c_mountYesYes
rear_b_mountYesYes
rear_mountYesYes
Dingo-D mount points
Dingo-O mount points

Both versions of Dingo also provide a front_bumper_mount, located directly on the front of the robot. While the physical robot does not have any mounting holes here, lightweight sensors (e.g. small cameras) can be placed here using double-sided adhesive if required.

Dingo-D front bumper mount

Configurations​

As an alternative to individually specifying each accessory, some fixed configurations are provided in the package. These can be specified using the config arg to description.launch, and are intended especially as a convenience for simulation launch.

ConfigDescription
baseBase Dingo
front_laserAdds a SICK LMS1xx lidar to the Dingo's front mount
note

Additional configurations coming soon

Key ROS Topics​

You can view all topics that are active using rostopic list. The most important topics are summarized in the table below.

TopicMessage TypePurpose
/cmd_velgeometry_msgs/TwistInput to Dingo's kinematic controller. Publish here to make Dingo go.
/odometry/filterednav_msgs/OdometryPublished by robot_localization, a filtered localization estimate based on wheel odometry (encoders) and integrated IMU.
/imu/datasensor_msgs/IMUPublished by imu_filter_madgwick, an orientation estimated based on the Dingo's internal IMU.
/mcu/statusdingo_msgs/StatusLow-frequency status data for Dingo's systems. This information is republished in human readable form on the diagnostics topic and is best consumed with the Robot Monitor.
/mcu/aux_inputdingo_msgs/UInt8User can subscribe to this topic to monitor the MCU user inputs. See AUX Inputs.
/mcu/aux_outputstd_msgs/UInt8User can publish to this topic to enable and disable the AUX outputs as well as control relays on the MCU. See AUX Outputs and Relays.
/mcu/fansdingo_msgs/FansUser can publish to this topic to control an optionally installed fan. See details Optional Fan.
/mcu/lightsdingo_msgs/LightsUser can publish to this topic to override the default behavior of the Dingo corner LEDs.

Dingo Software Setup​

Backing Up Robot Configuration​

Upgrading your Clearpath Dingo to ROS Noetic from older ROS distributions is a straightforward process; however it's important to understand that each Dingo 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​

note

If you are upgrading your Dingo from an older version of ROS, please refer to our upgrade instructions here and here.

Installing Dingo Software​

note

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

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

Testing Base Configuration​

  1. To test your configuration, start the background service with the following command:

    sudo systemctl start ros

  2. The Comms indicator should turn green. You can check that the service has started correctly by checking the logs:

    sudo journalctl -u ros

  3. Your Dingo should now be accepting commands from your joystick (see next section). The service will automatically start each time you boot your Dingo'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 Dingo's Network Configuration​

Dingo is normally equipped with a combination Wi-Fi + Bluetooth module. If this is your first unboxing, ensure that Dingo's wireless antennae are firmly screwed on to the chassis.

First Connection​

By default, Dingo'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

Using Dingo​

Simulating Dingo​

Whether you actually have a Dingo robot or not, the Dingo 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 Dingo around.

Installation​

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

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

Launching Gazebo​

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

roslaunch dingo_gazebo dingo_world.launch

You should see the following window appear, or something like it. You will see a base Dingo spawned with no additional sensors. You can adjust the camera angle by clicking and dragging while holding CTRL, ALT, or the Shift key.

Simulated Dingo in the Race World

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.

note

See also Additional Simulation Worlds.

Simulation Configs​

Note that like Dingo itself, Dingo's simulator comes in multiple flavours called configs. A common one which you will need often is the front_laser config. If you close the Gazebo window, and then CTRL-C out of the terminal process, you can re-launch the simulator with a specific config.

roslaunch dingo_gazebo dingo_world.launch config:=front_laser

You should now see the simulator running with the simulated SICK LMS-111 laser present.

Simulated Dingo in the Race World with SICK LMS-111

Gazebo not only simulates the physical presence of the laser scanner, it also provides simulated data which reflects the robot's surroundings in its simulated world. We will visualize the simulated laser scanner data shortly.

Interfacing with Dingo​

Both simulated and real Dingo robots expose the same ROS interface and can be interacted with in the same way.

note

Please make sure that the desktop packages for Dingo are installed:

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

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

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

roslaunch dingo_viz view_robot.launch

You should see RViz appear.

Dingo RViz

The RViz display only shows what the robot knows about its world, which presently, is nothing. Because the robot doesn't yet know about the barriers which exist in its Gazebo world, they are not shown here.

Driving with Interactive Controller​

RViz will also show Dingo's interactive markers around your Dingo'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 Dingo 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 Dingo moving within its simulated world. Or, if you drive real Dingo using this method, it will have moved in the real world.

Visualizing Sensors​

The RViz tool is capable of visualizing many common robotic sensors, as well as other data feeds which can give us clues as to what the robot is doing and why. A great place to start with this is adding the LaserScan plugin to visualize the laser scans being produced by the simulated LMS-111. In the left panel, click the "Add" button, then select the "Topics" tab, and then select the front/scan topic:

Adding a laser scan visualization to Dingo

Click "OK" and you should see laser scan points now visible in the RViz window, relative to the robot.

Visualizing Dingo with simulated laser scans

If you use the interactive markers to drive around, you'll notice that the laser scan points move a little bit but generally stay where they are. This is the first step toward map making using Gmapping.

Control​

There are three ways to send your Dingo 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 Dingo 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.

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

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

Odometry​

Dingo publishes odometry information on the odometry/filtered topic, as nav_msgs/Odometry messages. These are generated by ekf_localization_node, which processes data from several sensor sources using an Extended Kalman filter (EKF). This includes data from the wheel encoders and IMU (if available).

Additional odometry information sources can be added to the EKF in robot_localization.yaml.

Diagnostics​

note

Diagnostics are only applicable to real Dingo robots, not simulation.

Dingo provides hardware and software system diagnostics on the ROS standard /diagnostics topic. The best way to view these messages is using the rqt_runtime_monitor plugin. Run the rqt command, and select Plugins→Robot Tools→Runtime Monitor from the top menu.

The same information is also published as a dingo_msgs\Status message on the Status topic.

Driving Dingo​

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

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

Dingo 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, 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 (Dingo-O only; not supported on Ridgeback)
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 either the /dingo_velocity_controller/cmd_vel or the /cmd_vel ROS topics to drive Dingo.

For example, in terminal, run:

rostopic pub /dingo_velocity_controller/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 Dingo drive forward momentarily at 0.5 m/s without any rotation.

Extending Dingo Startup​

Now that you've had Dingo 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 Dingo'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 Dingo'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 Dingo 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 Dingo'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 Dingo's URDF. The first is that you may simply set the Dingo_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 Dingo'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 dingo_description.

Keeping Dingo Updated​

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

To get all Navigation related files for Dingo, run:

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

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

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

Referring to the Simulating Dingo instructions, bring up Dingo with the front laser enabled for the following demos:

roslaunch dingo_gazebo dingo_world.launch config:=front_laser

If you're working with a real Dingo, it's suggested to connect via SSH and launch the dingo_navigation launch files from on board 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 Dingo 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 dingo_navigation odom_navigation_demo.launch

To visualize with the suggested RViz configuration launch:

roslaunch dingo_viz view_robot.launch config:=navigation
RViz with Dingo's odom navigation configuration

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 dingo_navigation into your own workspace and modify the corresponding files in the params subfolder.

Making a Map​

In this demonstration, Dingo generates a map using Gmapping. Begin by launch the Gmapping launch file on the robot:

roslaunch dingo_navigation gmapping_demo.launch

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

roslaunch dingo_viz view_robot.launch config:=gmapping
RViz with Dingo's Gmapping configuration

You must slowly drive Dingo around to build the map. As obstacles come into view of the laser scanner, they will be added to the map, which is shown in RViz. You can either drive manually using the interactive markers, or semi-autonomously by sending navigation goals (as above).

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.

Using amcl, Dingo 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 dingo_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 "Dingo Race" environment which Dingo's simulator spawns in. If you're using a real Dingo 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 dingo_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.

Dingo Tests​

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

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

sudo apt-get install ros-noetic-dingo-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 Dingo robot, open terminal and run:

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

  • Lighting Test

    The Lighting Test checks that the robot's lights are working properly.

    This test turns the lights off, red, green, and blue (in order) by publishing lighting commands to the /cmd_lights ROS topic. The user will be asked to verify that the lights change to the expected colours.

  • Motion Stop Test

    The Motion Stop Test checks that the robot's motion-stop is working properly.

    This test subscribes to the /mcu/status ROS topic and checks that when the motion-stop is manually engaged by the user, the motion-stop state is correctly reported on the /mcu/status ROS topic. The user will be asked to verify that the lights flash red while the motion-stop is engaged.

  • ADC Test

    The ADC Test checks that the robot's voltage and current values across its internal hardware components are within expected tolerances.

    This test subscribes to the /mcu/status ROS topic and checks that the voltage and current values across the internal hardware are within expected tolerances.

  • 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/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 /odometry/filtered 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, encoders, and encoder-fused odometry are working properly.

    This test:

    • Subscribes to the /dingo_velocity_controller/odom ROS topic to receive linear displacement estimations from the encoder-fused odometry. The robot will drive forward until 1 metre is estimated.
    • Subscribes to the /feedback ROS topic to receive linear displacement measurements from the individual encoders. These measurements are output as comparison to the linear displacement estimations from the encoder-fused odometry.
    • Subscribes to the /joint_state ROS topic to receive linear displacement measurements from individual the encoders. These measurements are output as comparison to the linear displacement estimations from the encoder-fused odometry.
    • 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.

  • Cooling Test

    The Cooling Test is an optional test that only applies to Dingo's with an external fan connected to the MCU, and checks that the external fan is working properly.

    This test makes the fan spin at different speeds by publishing fan speed commands to the /mcu/cmd_fans ROS topic. The user will be asked to verify that the fan change to the expected speeds.

CAN Bus Test​

The check_can_bus_interface script checks that communication between the motors, encoders, robot's MCU, and robot's computer are working properly over the CAN bus interface.

This script verifies that the can0 interface is detected and activated, then proceeds to check the output of candump to verify that good CAN packets are being transmitted. Based on the Dingo configuration, either Dingo-D or Dingo-O, this script will know to check for good CAN packets from 2 or 4 encoders, respectively.

Running CAN Bus Test​

To run the check_can_bus_interface script on a Dingo robot, open terminal and run:

rosrun dingo_tests check_can_bus_interface

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 192.168.131.1/24 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 192.168.131.1

network:
version: 2
renderer: networkd
ethernets:
bridge_eth:
  dhcp4: no
  dhcp6: no
  match:
    name: eth*
bridge_en:
  dhcp4: no
  dhcp6: no
  match:
    name: en*
bridges:
br0:
  dhcp4: yes
  dhcp6: no
  interfaces: [bridge_en, bridge_eth]
  addresses:
    - 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.

note

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

Additional Simulation Worlds​

In addtion to the default dingo_world.launch file, dingo_gazebo contains two additional launch files:

  • empty_world.launch, which spawns Dingo in a featureless, infinite plane;
  • spawn_dingo.launch, which is intended to be included in any custom world to add a Dingo simulation to it.
Dingo in the Empty World environment

To add a Dingo to any of your own worlds, simply include the spawn_dingo.launch file in your own world's launch:

<include file="$(find dingo_gazebo)/launch/spawn_dingo.launch">
  <!-- Optionally configure the spawn position -->
  <arg name="x" value="$(arg x)"/>
  <arg name="y" value="$(arg y)"/>
  <arg name="z" value="$(arg z)"/>
  <arg name="yaw" value="$(arg yaw)"/>
</include>

Finally, Clearpath provides an additional suite of simulation environments that can be downloaded separately and used with Dingo, as described below.

Clearpath Gazebo Worlds​

The Clearpath Gazebo Worlds collection contains 4 different simulation worlds, representative of different environments our robots are designed to operate in:

  • Inspection World: a hilly outdoor world with water and a cave
  • Agriculture World: a flat outdoor world with a barn, fences, and solar farm
  • Office World: a flat indoor world with enclosed rooms and furniture
  • Construction World: office world, under construction with small piles of debris and partial walls

Dingo is supported in the Office and Construction worlds.

Installation​

To download the Clearpath Gazebo Worlds, clone the repository from github into the same workspace as your Dingo:

cd ~/catkin_ws/src
git clone https://github.com/clearpathrobotics/cpr_gazebo.git

Before you can build the package, make sure to install dependencies. Because Clearpath Gazebo Worlds depends on all of our robot's simulation packages, and some of these are currently only available as source code, installing dependencies with rosdep install --from-paths [...] will likely fail.

To simulate Dingo in the Office and Construction worlds the only additional dependency is the gazebo_ros package.

Once the dependencies are installed, you can build the package:

cd ~/catkin_ws
catkin_make
source devel/setup.bash

Running the Office Simulation​

Office World is a small indoor environment representing a commercial office space. It features several large, open areas with furniture, as well as a narrow hallway with smaller offices and meeting rooms. It is intended to simulate missions in commercial spaces, such as facilitating deliveries, security monitoring, and inspecting equipment.

Dingo in the Office World

To launch Office World with a Dingo, run the following command:

roslaunch cpr_office_gazebo office_world.launch platform:=dingo

You should see Dingo spawn in the office world, as pictured. You can see the complete layout of the office below:

The layout of Office World

To add sensors to Dingo, use the environment variables described in Description Package. For example, to simulate Dingo with a Sick LMS-1xx lidar, run:

export DINGO_LASER=1
roslaunch cpr_office_gazebo office_world.launch platform:=dingo

You will see Dingo spawn with a lidar sensor mounted to it, which can be used for navigation as described in Simulating Dingo.

Dingo in Office World with a lidar sensor

Running the Construction Simulation​

Construction World is the same basic layout as Office World, representing the same office space under construction/renovation. It is an indoor environment with small hills of debris/rubble, partial walls, and piles of construction supplies. It is designed to simulate missions in any sort of construction site.

Dingo in the Construction World

To launch Construction World with a Dingo, run the following command:

roslaunch cpr_office_gazebo office_construction_world.launch platform:=dingo

You should see Dingo spawn in the construction world, as pictured. You can see the complete layout of the office below:

The layout of Construction World

To add sensors to Dingo, use the environment variables described in Description Package. For example, to simulate Dingo with a Sick LMS-1xx lidar, run:

export DINGO_LASER=1
roslaunch cpr_office_gazebo office_construction_world.launch platform:=dingo

You will see Dingo spawn with a lidar sensor mounted to it, which can be used for navigation as described in Simulating Dingo.

Support​

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

To get in touch with a salesperson regarding Clearpath Robotics products, please email <research-sales@clearpathrobotics.com>.

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 Robotics Stack Exchange. 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 on Robotics Stack Exchange for the benefit of the community.

Last updated on