Demo 1: Single Robot Setup

This guide covers the setup and operation of a single Clearpath Jackal robot for autonomous navigation, obstacle avoidance, and path planning. Each robot is run individually and sequentially, not simultaneously.

Overview

Goal: Configure and run a single Jackal robot to demonstrate autonomous navigation capabilities including: - Simultaneous Localization and Mapping (SLAM) - Obstacle avoidance - Path planning - Localization

Note: This setup is designed for individual robot operation. Each robot should be tested and validated separately before moving to the next robot.

Prerequisites

Before beginning, ensure the following:

  • ROS 2 Humble is installed and configured
  • Clearpath Jackal robot is properly configured
  • All required sensors (ZED camera, Ouster LiDAR) are connected and functional
  • Network connectivity is established
  • Robot has appropriate permissions and access

Preparation & Setup

1. System Preparation

  1. Update ROS 2 Stack:
  2. Ensure the robot has the latest ROS 2 stack installed

  3. Verify all required packages are available

  4. Configuration Files:

  5. Verify configuration files are present and properly configured

  6. Ensure map files are available and accessible

  7. Network Verification:

  8. Confirm network connectivity between the robot and control station
  9. Verify ROS 2 discovery is working correctly

2. Robot-Specific Configuration

Each robot should have its own configuration based on its serial number:

  • GitHub Repository: https://github.com/CRAL-UVA/CRALAutonomyStack/tree/main/jackal{robot_serial_number}
  • Replace {robot_serial_number} with the specific robot's serial number (e.g., jackal93 or jackal96)

Launch Commands

Launch the Nav2 navigation stack:

ros2 launch nav2_bringup bringup_launch.py \
    map:=/home/administrator/clearpath_ws/lab_map.yaml \
    params_file:=/home/administrator/clearpath_ws/config/multi_nav2.yaml \
    use_sim_time:=false

Point Cloud to Laser Scan Conversion

Launch the point cloud to laser scan converter:

ros2 launch pointcloud_to_laserscan sample_pointcloud_to_laserscan_launch.py

SLAM

Launch the SLAM node:

ros2 launch slam_toolbox online_async_launch.py \
    slam_params_file:=/home/administrator/CRALAutonomyStack/config/mapper_params_online_async.yaml \
    use_sim_time:=false

System Architecture

The autonomy stack consists of several interconnected components:

1. Localization

Overview: Provides filtered odometry data for the robot's position estimation.

Implementation: - Uses platform/odom/filtered topic from the Clearpath platform - Applies filtering to IMU data for improved accuracy

Note: The built-in odometry from the Clearpath Jackal has limitations. For improved accuracy, the system uses odometry from the ZED camera (/zed/odom).

2. SLAM (Simultaneous Localization and Mapping)

Overview: Creates a 2D occupancy map of the environment using LiDAR data and odometry.

Functionality: - Combines 2D LiDAR scan data with odometry information - Generates a real-time occupancy grid map - Performs simultaneous localization and mapping

Inputs: - Laser Scan - Type: sensor_msgs/msg/LaserScan - Topic: /scanner/scan - Odometry - Type: nav_msgs/msg/Odometry - Topic: /zed/odom

Outputs: - Map - Type: nav_msgs/msg/OccupancyGrid - Topic: /map

Known Issues and Solutions:

  1. Ouster LiDAR Channel Issue:
  2. Problem: The /ouster/scan topic from the Ouster sensor only reflects one channel out of 128 available channels, resulting in circular map artifacts
  3. Solution: Use the pointcloud_to_laserscan package to convert point cloud data to laser scan format
  4. Package Location: /home/administrator/CRALAutonomyStack/src

  5. Output Topic: /scanner/scan

  6. Odometry Quality:

  7. Problem: Built-in odometry from Clearpath Jackal has poor accuracy
  8. Solution: Use ZED camera odometry (/zed/odom) for improved localization accuracy

3. Perception

Overview: Processes LiDAR point cloud data to create a filtered 2D occupancy grid for navigation.

Functionality: - Filters floor points and points above the robot height - Converts filtered point cloud to 2D occupancy grid - Provides obstacle information for path planning

Inputs: - LiDAR Point Cloud - Type: sensor_msgs.msg.PointCloud2 - Topic: /ouster/points

Outputs: - Occupancy Grid - Type: nav_msgs.msg.OccupancyGrid - Topic: /voxel_grid/occupancy

4. Planner

Overview: Computes a safe path from the current position to a goal position using the A* algorithm.

Functionality: - Receives goal position and current ego position - Applies safety buffer to the occupancy grid - Executes A* pathfinding algorithm - Generates target trajectory

Inputs: - Goal Position - Type: geometry_msgs.msg.Point - Topic: /set_goal - Occupancy Grid - Type: nav_msgs.msg.OccupancyGrid - Topic: /voxel_grid/occupancy - Ego Odometry - Type: nav_msgs.msg.Odometry - Topic: /platform/odom/filtered

Outputs: - Target Trajectory - Type: sensor_msgs.msg.PointCloud2 - Topic: /target_trajectory

5. Controller

Overview: Generates velocity commands to follow the planned trajectory using pure pursuit control.

Functionality: - Receives target trajectory and current ego pose - Implements pure pursuit control algorithm - Computes command velocities to track the trajectory

Inputs: - Target Trajectory - Type: sensor_msgs.msg.PointCloud2 - Topic: /target_trajectory - Ego Odometry - Type: nav_msgs.msg.Odometry - Topic: /platform/odom/filtered

Outputs: - Command Velocity - Type: geometry_msgs.msg.Twist - Topic: /controller/cmd_vel

6. Autonomy (Command Velocity Mux)

Overview: Manages the selection between teleoperation and autonomous control modes, with emergency stop functionality.

Functionality: - Multiplexes between joystick (teleop) and controller (autonomous) command velocities - Provides emergency stop capability - Controlled via joystick button inputs

Joystick Button Mapping:

Function Button Description
Teleop ON Square Enable joystick command velocity
Teleop OFF Triangle Enable controller command velocity (autonomous mode)
Emergency Stop ON X Activate emergency stop
Emergency Stop OFF O Deactivate emergency stop
Faster Acceleration R1 (hold) Increase acceleration in teleop mode
Slower Acceleration L1 (hold) Decrease acceleration in teleop mode

Inputs: - Joystick Inputs - Type: sensor_msgs.msg.Joy - Topic: /joy_teleop/joy - Command Velocity from Joystick - Type: geometry_msgs.msg.Twist - Topic: /joy_teleop/cmd_vel - Command Velocity from Controller - Type: geometry_msgs.msg.Twist - Topic: /controller/cmd_vel

Outputs: - Command Velocity - Type: geometry_msgs.msg.Twist - Topic: /cmd_vel

Validation Steps

For each robot, perform the following validation steps to ensure proper operation before proceeding to the next robot.

1. SLAM/Localization Verification

  1. Launch SLAM and localization nodes: 

    ros2 launch slam_toolbox online_async_launch.py \
    slam_params_file:=/home/administrator/CRALAutonomyStack/config/mapper_params_online_async.yaml \
    use_sim_time:=false

  2. Verify map generation is working correctly: 

    ros2 topic echo /map --once

  3. Confirm robot position is being tracked accurately: 

    ros2 run tf2_ros tf2_echo /map /base_link

2. Navigation Stack Verification

  1. Launch Nav2 navigation stack: 

    ros2 launch nav2_bringup bringup_launch.py \
    map:=/home/administrator/clearpath_ws/lab_map.yaml \
    params_file:=/home/administrator/clearpath_ws/config/multi_nav2.yaml \
    use_sim_time:=false

  2. Verify obstacle avoidance works with static obstacles:

  3. Place obstacles in the environment
  4. Command the robot to navigate around them

  5. Observe avoidance behavior

  6. Test path planning functionality:

  7. Set goal positions using: 
    ros2 topic pub /set_goal geometry_msgs/msg/Point "{x: 2.0, y: 0.0}"
  8. Verify path is generated and followed

3. Sensor Verification

  1. Confirm LiDAR data is being published correctly: 

    ros2 topic echo /ouster/points --once
ros2 topic echo /scanner/scan --once

  2. Verify camera odometry is available: 

    ros2 topic echo /zed/odom --once

  3. Check all sensor topics are active: 

    ros2 topic list | grep -E "(ouster|zed|scanner)"

4. Control Verification

  1. Test teleoperation mode:
  2. Connect joystick and press Square button to enable teleop
  3. Verify robot responds to joystick commands

  4. Check that /joy_teleop/cmd_vel topic is publishing

  5. Test autonomous navigation mode:

  6. Press Triangle button to disable teleop (enable autonomous mode)
  7. Set a goal position and verify robot navigates autonomously

  8. Monitor /controller/cmd_vel topic

  9. Verify emergency stop functionality:

  10. Press X button to activate emergency stop
  11. Confirm robot stops immediately
  12. Press O button to deactivate emergency stop
  13. Verify robot resumes operation

Testing Procedure

Phase 1: Start the Robot System

  1. Power on the robot following the procedure in the User Manual

  2. Launch all required nodes: 

    # Terminal 1: Navigation Stack
ros2 launch nav2_bringup bringup_launch.py \
    map:=/home/administrator/clearpath_ws/lab_map.yaml \
    params_file:=/home/administrator/clearpath_ws/config/multi_nav2.yaml \
    use_sim_time:=false

# Terminal 2: Point Cloud to Laser Scan
ros2 launch pointcloud_to_laserscan sample_pointcloud_to_laserscan_launch.py

# Terminal 3: SLAM
ros2 launch slam_toolbox online_async_launch.py \
    slam_params_file:=/home/administrator/CRALAutonomyStack/config/mapper_params_online_async.yaml \
    use_sim_time:=false

  3. Verify all topics are publishing: 

    ros2 topic list
ros2 topic hz /map
ros2 topic hz /scanner/scan
ros2 topic hz /zed/odom

Phase 2: Test Obstacle Avoidance

  1. Place static obstacles in the environment at various locations

  2. Command the robot to navigate around obstacles: 

    ros2 topic pub /set_goal geometry_msgs/msg/Point "{x: 2.0, y: 0.0}"

  3. Verify the robot successfully avoids obstacles:

  4. Monitor robot movement in real-time
  5. Confirm path planning adjusts around obstacles

  6. Verify robot reaches goal without collisions

  7. Observe the robot's path planning behavior:

  8. Visualize in Foxglove or RViz
  9. Check that /target_trajectory shows appropriate paths

Phase 3: Test Path Planning

  1. Set a goal position: 

    ros2 topic pub /set_goal geometry_msgs/msg/Point "{x: 3.0, y: 1.0}"

  2. Verify the planner generates a valid path:

  3. Check that /target_trajectory topic is publishing: 
    ros2 topic echo /target_trajectory --once
  4. Visualize the path in Foxglove or RViz

  5. Confirm path avoids known obstacles

  6. Confirm the robot follows the planned path:

  7. Monitor the robot's movement
  8. Verify it reaches the goal position
  9. Check that controller commands are being generated: 
    ros2 topic echo /controller/cmd_vel

Phase 4: Shutdown and Prepare for Next Robot

  1. Stop all running nodes:
  2. Press Ctrl+C in each terminal running launch files

  3. Or use: pkill -f ros2

  4. Power down the robot:

  5. Follow the shutdown procedure in the User Manual

  6. Ensure proper battery disconnection

  7. Prepare configuration for the next robot:

  8. Update namespace if needed
  9. Verify configuration files are correct
  10. Check that robot-specific settings are applied

Troubleshooting

This section covers common issues and their solutions. If you encounter problems not listed here, refer to the main Troubleshooting Guide.

Issue 1: Map Appears Circular or Distorted

Symptoms: - Map visualization shows circular artifacts - Map doesn't accurately represent the environment - SLAM produces incorrect map geometry

Diagnosis: 1. Check if point cloud to laser scan conversion is running: 

ros2 topic list | grep scanner
ros2 topic hz /scanner/scan

  1. Verify /scanner/scan topic is publishing correctly: 

    ros2 topic echo /scanner/scan --once

  2. Check Ouster LiDAR status: 

    ros2 topic echo /ouster/points --once

Solutions: 1. Ensure point cloud to laser scan converter is launched: 

ros2 launch pointcloud_to_laserscan sample_pointcloud_to_laserscan_launch.py

  1. Verify Ouster LiDAR is properly configured and connected

  2. Check that the package is in the correct location: 

    ls -la /home/administrator/CRALAutonomyStack/src/pointcloud_to_laserscan

  3. Restart the conversion node if it's not publishing

Issue 2: Poor Localization Accuracy

Symptoms: - Robot position drifts significantly - Localization is inconsistent - Map alignment is incorrect

Diagnosis: 1. Verify ZED camera odometry is available: 

ros2 topic echo /zed/odom --once
ros2 topic hz /zed/odom

  1. Check which odometry topic is being used: 

    ros2 topic echo /platform/odom/filtered --once

  2. Verify camera is properly calibrated and functioning

Solutions: 1. Ensure ZED camera driver is running: 

ros2 launch zed_wrapper zed_camera.launch.py \
    camera_model:=zed2 \
    namespace:=<robot_namespace>

  1. Verify /zed/odom topic is publishing at expected rate (should be > 10 Hz)

  2. Check camera calibration if odometry seems incorrect

  3. Restart the ZED camera node if odometry stops publishing

Issue 3: Navigation Stack Not Responding

Symptoms: - Robot doesn't respond to goal commands - Path planning doesn't generate paths - Navigation stack appears frozen

Diagnosis: 1. Verify all required topics are publishing: 

ros2 topic list
ros2 topic hz /map
ros2 topic hz /voxel_grid/occupancy
ros2 topic hz /platform/odom/filtered

  1. Check that map file is accessible: 

    ls -la /home/administrator/clearpath_ws/lab_map.yaml

  2. Verify configuration files exist and are correct: 

    cat /home/administrator/clearpath_ws/config/multi_nav2.yaml

Solutions: 1. Restart all navigation-related nodes: - Stop all launch files - Relaunch in the correct order (SLAM → Navigation → Perception)

  1. Verify map file path is correct in launch command

  2. Check configuration file syntax: 

    ros2 param validate /nav2_bringup

  3. Review node logs for errors: 

    ros2 topic echo /rosout

Issue 4: Emergency Stop Not Working

Symptoms: - Emergency stop button doesn't stop the robot - Robot continues moving after pressing X button - No response from joystick emergency stop

Diagnosis: 1. Verify joystick is connected and publishing: 

ros2 topic echo /joy_teleop/joy --once
ros2 topic hz /joy_teleop/joy

  1. Check that autonomy node is running: 

    ros2 node list | grep autonomy

  2. Verify button mappings are correct:

  3. X button should activate emergency stop
  4. O button should deactivate emergency stop

Solutions: 1. Reconnect joystick: - Disconnect and reconnect USB cable - Press PS4 button to reconnect wirelessly - Wait for solid light indicator

  1. Restart autonomy node if it's not running: 

    # Find and restart the autonomy launch file

  2. Verify joystick button mappings in the autonomy node configuration

  3. Test joystick input directly: 

    ros2 topic echo /joy_teleop/joy
# Press buttons and verify messages are received

Issue 5: Topics Not Publishing

Symptoms: - Expected topics are missing from ros2 topic list - Nodes appear to be running but topics are empty - System seems unresponsive

Diagnosis: 1. Check if nodes are actually running: 

ros2 node list

  1. Verify topics are being published: 

    ros2 topic list
ros2 topic hz <topic_name>

  2. Check for node errors: 

    ros2 topic echo /rosout

Solutions: 1. Restart the affected service: 

sudo systemctl restart clearpath-platform.service
sudo systemctl restart clearpath-sensors.service
sudo systemctl restart clearpath-custom.service

  1. Reboot the robot if services fail to start: 

    sudo reboot

  2. Verify workspace is properly sourced: 

    source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
source ~/CRALAutonomyStack/install/setup.bash

Issue 6: SLAM Not Generating Map

Symptoms: - /map topic is empty or not publishing - Map doesn't update as robot moves - SLAM node appears to be running but no output

Diagnosis: 1. Check SLAM node is running: 

ros2 node list | grep slam

  1. Verify required input topics are available: 

    ros2 topic hz /scanner/scan
ros2 topic hz /zed/odom

  2. Check SLAM configuration file: 

    cat /home/administrator/CRALAutonomyStack/config/mapper_params_online_async.yaml

Solutions: 1. Ensure all input topics are publishing: - Verify point cloud to laser scan is running - Check ZED camera odometry is available

  1. Restart SLAM node with correct parameters: 

    ros2 launch slam_toolbox online_async_launch.py \
    slam_params_file:=/home/administrator/CRALAutonomyStack/config/mapper_params_online_async.yaml \
    use_sim_time:=false

  2. Check SLAM logs for specific errors: 

    ros2 topic echo /rosout | grep slam

Additional Resources

  • Code Repository: https://github.com/CRAL-UVA/CRALAutonomyStack/tree/main/jackal{robot_serial_number}
  • Point Cloud to Laser Scan Package: /home/administrator/CRALAutonomyStack/src
  • Configuration Files: /home/administrator/clearpath_ws/config/
  • Map Files: /home/administrator/clearpath_ws/lab_map.yaml