This repository provides a comprehensive framework for off-road mobile robot research, integrating ROS 2 Humble, Gazebo Fortress, and PyTorch with Stable Baselines3 (SB3) and a Gymnasium interface for reinforcement learning. It includes the models for the Rover Zero, Clearpath Husky and Leo Rover platforms and as well as mutiple outdoor Gazebo environments to include industrial inspection, agricultural and construction sites. Autonmated metrics logging includes Success Rate (SC), Total Collisions (TC), Mean time to Traverse (MTT), Travers Rate (TR), and Velocify Over Rough terrain (VORT). This framework serves as a foundation for developing and testing mobile robot tasks on unstructured terrain.
- Introduction
- Features
- Prerequisites
- Getting Started
- Using the Framework
- Repository Structure
- Contributing
- License
This project aims to facilitate off-road mobile robot research by providing a ready-to-use simulation environment and tools for developing reinforcement learning agents. It leverages:
- ROS 2 Humble: The latest ROS 2 distribution for robotics development.
- Gazebo Fortress: A powerful simulation environment compatible with ROS 2 Humble.
- PyTorch and Stable Baselines3: For implementing PPO (Proximal Policy Optimization) RL agents.
The framework is designed to simulate the Rover Zero robot, but it can be extended to other platforms.
- Off Road Robot Simulation: Models of the Rover Zero, Leo Rover and Clearpath Husky platforms in Gazebo Fortress.
- Reinforcement Learning Integration: Placeholder and structure for implementing SB3 PPO PointNav RL agents.
- ROS 2 Workspace: Includes necessary ROS 2 packages and custom code.
- Extensibility: Modular design allows for integration of additional robots and sensors.
Main dependencies:
git clone git@github.com:jackvice/RoboTerrain.git
cd RoboTerrain/ros2_ws/
colon build# Source ROS 2 and workspace setup files
source /opt/ros/humble/setup.bash
source /home/ros2_ws/install/setup.bash
# Launch the Rover Zero simulation
ros2 launch roverrobotics_gazebo 4wd_rover_gazebo.launch.py
Gazebo should open on your host machine, displaying the Rover Zero robot in the simulation environment.
-
Running the baseline SAC agent: The agent can be started in 'predict' mode or 'train' mode
cd ros2_ws/src/sb3/ # First run the position bridge node for the Inspection world: python ign_ros2_pose_topic.py inspect rover_zero4wd # to run the pretrained agent python sb3_SAC.py --mode predict \ --load True \ --world inspect \ --vision False \ --checkpoint_name trained_agents/sac_inspect.zip \ --normalize_stats trained_agents/sac_inspect_normalize.pkl # to training the agent python sb3_SAC.py --mode train --load False --world inspect # TensorBoard tensorboard --logdir tboard_logs/
-
Changing World Model: Select between Maze, Inspection, Rubicon or Island worlds.
# open the gazebo launch file and uncommnet the desired world line in the 'DeclareLaunchArgument()' function (line 24): nano RoboTerrain/ros2_ws/src/roverrobotics_ros2/roverrobotics_gazebo/launch/4wd_rover_gazebo.launch.py # Rebuild the workspace: cd RoboTerrain/ros2_ws/ colcon build # Launch the simualtion: ros2 launch roverrobotics_gazebo 4wd_rover_gazebo.launch.py
-
Running the metrics logger: The metrics logger node writes metrics log files to:
RoboTerrain/metrics_analyzer/data/metric_logsros2 run rover_metrics metrics_node
-
Spawn Dynamic Actors: The dynamic actor default trajectories are for Inspection world.
cd RoboTerrain/ros2_ws/src/dynamic_obstacles # First actor python spawn.py # Second actor python spawn2.py
-
Graph Navigation Metrics: Pass log file names to the metrics grapher.
cd RoboTerrain/metrics_analyzer python cli_main.py data/metric_logs/log_filename1.csv data/metric_logs/log_filename3.csv data/metric_logs/log_filename3.csv
Note: Ensure that all ROS 2 nodes and the simulation are running before starting the training script.
project_root/
├── metrics_analyzer
├── ros2_ws/
│ ├── src/
│ │ ├── roverrobotics_ros2/ # Gazebo models and launch files
│ │ ├── sb3/ # SAC and PPO agent code
│ │ ├── dynamic_obstacles/ # Dynamic obstacle generator
│ │ └── rover_metrics/ # Metrics logger
│ ├── install/
│ ├── build/
│ └── log/
├── LICENSE
├── assets
└── README.md
This system provides tools for logging and visualizing robot navigation metrics in ROS2, particularly useful for analyzing robot performance over rough terrain.
-
Metrics Node (
metrics_node.py):- ROS2 node that collects real-time metrics
- Subscribes to key topics:
/scan,/imu/data,/rover/pose_array,/odometry/wheels - Logs data to timestamped CSV files
-
Metrics Analyzer (
cli_main.py):- Command-line tool for analyzing and visualizing the collected metrics
- Supports multiple data files for trial comparison
- Generates publication-ready plots
First, ensure ROS2 and your robot simulation/hardware are running. Then:
Launch the metrics logging node ros2 run rover_metrics metrics_node
This will create a CSV file in /metric_logs with timestamp and metrics including:
- Total Collisions
- Obstacle Clearance
- Current Velocity
- IMU Acceleration Magnitude
- Rough Terrain Detection
After collecting data, use the metrics analyzer to visualize results:
Basic usage (plot all metrics) python cli_main.py path/to/metrics_log.csv
Compare velocity and IMU data from multiple trials python cli_main.py trial1.csv trial2.csv -m CV IM -p time_series
Available metrics flags: TC: Total Collisions CS: Current Collision Status SM: Smoothness Metric OC: Obstacle Clearance DT: Distance Traveled CV: Current Velocity IM: IMU Acceleration Magnitude RT: Is Rough Terrain
The visualization tool will create:
- Individual metric plots
- Combined comparison plots for multiple trials
- Special visualization for velocity vs. terrain roughness
Output files are saved in: output/combined_metrics/
python cli_main.py metrics_log_20250105_190453.csv -m CV IM -p time_series
python cli_main.py \
metrics_log_20250105_190453.csv \
metrics_log_20250105_190759.csv \
-m CV IM -p time_series
- ros2_ws/: ROS 2 workspace containing all source code.
- src/: Source directory for ROS 2 packages and PPO agent.
- install/, build/, log/: Generated after building the workspace.
Contributions are welcome! Please follow these guidelines:
- Fork the repository and create a new branch for your feature or bug fix.
- Ensure code quality by following best practices and including docstrings.
- Submit a pull request with a detailed description of your changes.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
This repository integrates components from several open-source projects. The licensing details for these components are as follows:
- Gazebo Fuel Terrain Models: Apache 2.0 License. See gazebosim.org.
- Rover Zero Robot Model: Apache 2.0 License. See Rover Robotics Repository.
- Leo Rover Robot Model: MIT License. See Leo Rover Repository.
- Clearpath Robotics Terrain and Husky Models: BSD License. See Clearpath Robotics Repositories.
Each license allows for reuse and distribution with proper attribution and adherence to their terms.
For the full license text, please refer to the LICENSE file included in the repository.