USV Simulation Stack

A ROS 2-native marine simulation framework for Autonomous Surface Vehicles

---

Table of Contents

• Overview
• Why This Project Exists
• Vision
• Core Architecture
• System Layers
• Development Phases
• Phase Summary Table
• Detailed Roadmap
• Visual Roadmap
• Repository Structure
• ROS 2 Interface Philosophy
• Scenario and Evaluation Strategy
• Validation Philosophy
• Engineering Principles
• Near-Term Milestones
• Long-Term Direction
• What Success Looks Like
• What This Project Is Not
• Final Statement

---

Overview

This repository aims to build a modular, physics-aware, ROS 2-integrated simulation ecosystem for Autonomous Surface Vehicles (USVs).

The objective is not merely to visualize a boat moving in a simulator.
The objective is to create a simulation framework that supports:

• guidance, navigation, and control development
• thrust allocation and actuator modeling
• sensor simulation and autonomy stack integration
• disturbance-aware testing
• scenario-based evaluation
• system identification feedback loops
• future HIL/SIL and digital twin workflows

This project is based on a simple principle:

A useful simulator is not an animation tool.
It is an engineering instrument.

---

Why This Project Exists

Many marine simulation environments fall into one of two categories:

1. Visually impressive but dynamically shallow
2. Academically interesting but difficult to integrate into real robotics workflows

That gap matters.

For USV development, especially in ROS 2-based autonomy systems, simulation must do more than render a floating vehicle. It must support:

• meaningful control development
• realistic actuator constraints
• reproducible experiments
• measurable performance
• clear separation between truth, estimates, and commands
• eventual comparison with real-world logs

This repository exists to address that need.

---

We believe a serious USV simulator must be:

• ROS 2-native
• Modular by design
• Physics-informed
• Control-oriented
• Scenario-driven
• Validation-ready
• Extensible toward real-world deployment workflows

We do not aim to build a monolithic simulator that hides everything behind opaque plugins and fragile dependencies.

We aim to build a clear, inspectable, replaceable, engineering-first simulation stack.

---

Vision

The long-term goal is to establish a simulation framework that can evolve from a research platform into a high-confidence engineering environment.

This means combining:

• Gazebo Sim as the simulation world and physics backbone
• ROS 2 as the communication and autonomy backbone
• custom vehicle dynamics and actuator models
• scenario-based evaluation and benchmarking
• sensorized autonomy workflows
• validation against real-world data
• a path toward digital twin alignment

---

Core Architecture

+------------------------------------------------------------------+
|                    Scenario & Evaluation Layer                   |
| missions | waypoint tasks | DP cases | COLREG cases | metrics    |
+------------------------------------------------------------------+
|                  Navigation, Guidance & Control                  |
| path planner | mission manager | LOS | MPC | allocator | EKF     |
+------------------------------------------------------------------+
|                    Sensor & ROS 2 Interface Layer                |
| IMU | GNSS | heading | AIS | lidar | camera | TF | /clock        |
+------------------------------------------------------------------+
|                 Vehicle Dynamics & Actuator Layer                |
| 3-DOF/6-DOF | thrust model | lag | deadband | saturation         |
+------------------------------------------------------------------+
|                   Marine Physics & World Layer                   |
| buoyancy | hydrodynamics | current | wind | collision            |
+------------------------------------------------------------------+
|                         Gazebo Sim Backbone                      |
+------------------------------------------------------------------+

Visual RoadMap

[Phase 0]
Foundation
    |
    v
[Phase 1]
Minimal Floating Vehicle
    |
    v
[Phase 2]
Control Integration
    |
    v
[Phase 3]
Actuator Realism
    |
    v
[Phase 4]
Disturbance & Environment
    |
    v
[Phase 5]
Sensorized Autonomy Stack
    |
    v
[Phase 6]
Scenario Library
    |
    v
[Phase 7]
Validation & Digital Twin Direction

Repository Structure

usv_sim_ws/
├── src/
│   ├── usv_description/
│   │   ├── sdf/
│   │   ├── meshes/
│   │   ├── config/
│   │   └── launch/
│   │
│   ├── usv_gazebo/
│   │   ├── worlds/
│   │   ├── models/
│   │   ├── bridge/
│   │   └── launch/
│   │
│   ├── usv_dynamics/
│   │   ├── include/
│   │   ├── src/
│   │   └── config/
│   │
│   ├── usv_actuators/
│   │   ├── include/
│   │   ├── src/
│   │   └── config/
│   │
│   ├── usv_sensors/
│   │   ├── src/
│   │   └── config/
│   │
│   ├── usv_control/
│   │   ├── src/
│   │   ├── config/
│   │   └── launch/
│   │
│   ├── usv_navigation/
│   │   ├── src/
│   │   ├── config/
│   │   └── launch/
│   │
│   ├── usv_msgs/
│   │
│   ├── usv_scenarios/
│   │   ├── missions/
│   │   ├── configs/
│   │   └── launch/
│   │
│   └── usv_bringup/
│       ├── launch/
│       └── scripts/
│
└── README.md