uavros2 — Multi-Simulator UAV Testbed for ROS 2

Working name: uavros2 (Python package + repo name). Brand candidates for the published project are listed below; pick one when you're ready to rename. Renaming touches setup.py, package.xml, every launch include, and the GitHub URL, so it's worth a deliberate decision.

A ROS 2 UAV testbed shipping x500 + manipulator assets, indoor + outdoor worlds, and a multi-simulator dispatcher (Gazebo primary; MuJoCo / Webots / Isaac / PyBullet / Genesis scaffolded) with PX4 SITL + MAVROS integration.

The brand should make the ROS 2 dependency immediately obvious — these candidates all carry "ros2" / "r2" in the name itself:

Avoid: rosflight (an existing autopilot project), roscopter (existing Python package).

When you pick one, the rename is:

1. Repo: gh repo rename <new> (or via the web UI)
2. Python package: setup.py.name, package.xml.name, uavros2/ dir
3. Every launch_arguments / FindPackageShare("uavros2") reference

A single search-and-replace pass nails most of it.

This package ships a multi-simulator UAV development testbed: ROS 2 Jazzy + PX4 autopilot + Gazebo Harmonic + MAVROS as the primary stack, with a dispatcher layer that fans out to MuJoCo, Webots, Isaac Sim, PyBullet, and Genesis. It includes a curated set of UAV assets (x500 base + sensor variants + four arm manipulators), indoor + outdoor world assets, per-simulator launch configurations, and a canonical ROS 2 topic contract so downstream code is simulator-agnostic.

• 🔧 Complete Toolchain: PX4 + ROS 2 Jazzy + Gazebo Harmonic + MAVROS, with auto-installed dependencies
• 🎮 UAV Catalogue: 9 x500 sensor / arm variants, each with a matching PX4 airframe (IDs 4020–4028), no overlap
• 📐 Asset Descriptor System (v1): generate a UAV's Gazebo SDF + PX4 airframe from a YAML descriptor instead of hand-editing — see docs/ASSETS.md. CLI: uavros2-asset {list,show,validate,build,diff}.
• 🕹️ Flying made easy: bash aliases arm / takeoff / hold / land / disarm / offboard / qgc for the common MAVROS service calls; see docs/FLYING.md.
• 🦾 Manipulators: 4 floating-base arms (three_dof, OpenManipulator-X, Panda, UR5) with controllers + MoveIt configs
• 🌐 World Library: indoor warehouse + 5 outdoor urban* heightmap testbeds (git-lfs)
• 🎛️ Multi-Simulator Dispatcher: simulator:=gazebo|webots|mujoco|isaac|pybullet|genesis from one launch file
• 🐳 Docker Ready: in-tree uavros2_docker submodule with Ubuntu 24 / Jazzy default + Ubuntu 22 / Humble + CUDA + WSL variants
• 📡 Communication Middleware: Zenoh RMW + XRCE-DDS + MAVLink/MAVROS dual bridges
• 🛰️ Protocol Flexibility: Choose between native uXRCE-DDS or classic MAVLink at launch time

Component	Description	Version
	ROS 2 Jazzy Complete robotics middleware	Latest
	Gazebo Harmonic Physics simulation engine	Latest
	PX4 Autopilot Flight control stack	v1.14+
	MAVROS MAVLink-ROS 2 bridge	Jazzy
	MAVLink Protocol Micro air vehicle communication	v2.0
	QGroundControl Ground control station	Latest
	RViz2 3D visualization tool	Jazzy
	Zenoh Middleware High-performance communication	Latest

cd ~/ && mkdir -p ros2_ws/src && cd ros2_ws/src
# Clone the repository
git clone https://github.com/asmbatati/uavros2.git
cd uavros2

# Set environment variables
export DEV_DIR=~
export GIT_USER=your_github_username  # Optional
export GIT_TOKEN=your_github_token    # Optional

# Run the installation script
chmod +x install.sh
./install.sh

# Clone the repository
git clone https://github.com/asmbatati/uavros2.git
git submodule update --init --recursive
cd uavros2/px4_ros2_jazzy_docker/docker

# Make the image
make px4-dev-simulation-ubuntu24

Then run docker container:

# Navigate to Docker setup
cd ..

# Build and run the container
chmod +x docker_run.sh
./docker_run.sh

Then install:

# This is inside the container
# Clone the repository
cd ~/shared_volume
mkdir -p ros2_ws/src && cd ros2_ws/src
git clone https://github.com/asmbatati/uavros2.git
cd uavros2

# Run the installation script
chmod +x install.sh
./install.sh #if asked, passwod is "user"

• OS: Ubuntu 22.04/24.04 LTS or WSL2
• RAM: Minimum 8GB (16GB recommended)
• GPU: NVIDIA GPU recommended for optimal performance
• Storage: At least 20GB free space

• ROS 2 Jazzy Desktop: Complete robotics development stack
• Gazebo Harmonic: Latest simulation environment
• PX4 Development Tools: Firmware development and simulation
• MAVROS: MAVLink-ROS 2 communication bridge
• Python Dependencies: NumPy, Matplotlib, PyMAVLink, and more
• Communication Middleware: Zenoh, XRCE-DDS, MAVLink protocols

The installation script automatically:

1. 🔍 Environment Detection: Identifies container vs host environment
2. 📦 Dependency Management: Installs all required packages (ROS 2, Gazebo, MAVROS, etc.)
3. 🔧 System Configuration: Sets up permissions and environment variables
4. 🌐 Repository Cloning: Downloads PX4, MAVROS, and simulation packages
5. 🏗️ Building: Compiles all ROS 2 packages with smart retry logic
6. ⚙️ Configuration: Copies models, worlds, and airframe configurations

# Source the workspace
source ~/shared_volume/ros2_ws/install/setup.bash

# Launch the simulation
ros2 launch uavros2 sim.launch.py

# For tugbot depot world
ros2 launch uavros2 sim.launch.py world_type:=warehouse

# Navigate to PX4 directory
cd ~/shared_volume/PX4-Autopilot

# Launch X500 with stereo camera and lidar
make px4_sitl gz_x500_twin_stereo_twin_velodyne

# For tugbot depot environment
PX4_GZ_MODEL_POSE="0,0,0.1,0,0,0" make px4_sitl gz_x500_stereo_cam_3d_lidar PX4_GZ_WORLD=warehouse

# Launch QGroundControl
~/shared_volume/QGroundControl.AppImage

# Or use the alias (after sourcing bash.sh)
qgc

• X500 Quadcopter: Basic configuration
• X500 + Intel RealSense D435: With depth camera
• X500 + Stereo Cameras: Dual camera setup
• X500 + LiDAR: 3D scanning configuration
• X500 Complete: Stereo cameras + dual LiDAR

• Default Empty World: Basic testing environment
• Tugbot Depot: Warehouse simulation with obstacles
• Custom Worlds: Expandable world configurations

# Build specific package
cd ~/shared_volume/ros2_ws
colcon build --packages-select uavros2

# Build all packages
colcon build

# Source after building
source install/setup.bash

1. Place model files in models/ directory
2. Add world files to worlds/ directory
3. Configure airframes in config/px4/ directory
4. Rebuild the workspace

This simulation environment supports two distinct communication architectures that allow ROS 2 to interface with PX4. Each has its own advantages and use cases, giving you the flexibility to choose the best approach for your specific needs.

Modern • Official • High Performance

Overview: This is the modern, official, and recommended architecture by the PX4 development team for ROS 2 integration. It provides the highest performance by connecting directly to PX4's internal uORB messaging system.

• Bridge Component: A lightweight uxrce_dds_client runs directly on PX4
• Communication: Talks to a Micro-XRCE-DDS Agent on the companion computer
• Protocol: Directly translates PX4's internal uORB messages to/from DDS standard
• Integration: Makes PX4's uORB topics appear as native ROS 2 topics

• High Performance: Direct, native integration with minimal overhead
• Low Latency: No protocol conversion delays
• Official Support: Maintained by PX4 development team
• Future-Proof: Designed for modern ROS 2 ecosystem

graph TD
    subgraph "🖥️ Companion Computer (ROS 2 Ecosystem)"
        C[🤖 ROS 2 Nodes]
        B[🌉 Micro-XRCE-DDS Agent]
        F[👁️ RViz2 Visualization]
        H[🔗 ros_gz_bridge]
    end

    subgraph "🌍 Simulation Environment"
        A[🚁 PX4 SITL Autopilot]
        D[🎮 Gazebo Physics Engine]
    end

    subgraph "📱 Ground Control"
        E[🎛️ QGroundControl]
    end

    %% Primary Data Flow (uXRCE-DDS)
    A -.->|"⚡ uORB → DDS<br/>Native Bridge"| B
    B <-->|"📡 ROS 2 Topics<br/>High Performance"| C
    
    %% Simulation Integration
    A <-->|"🔌 Physics Interface<br/>Real-time Sync"| D
    D -->|"📊 Sensor Data<br/>ROS 2 Topics"| H
    H <-->|"🔄 Gazebo ↔ ROS 2"| C
    
    %% Visualization & Monitoring
    C -->|"📈 State Visualization"| F
    A -.->|"📻 MAVLink UDP<br/>Telemetry"| E

    %% Styling
    classDef primary fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef simulation fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef ground fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    
    class A,B,C primary
    class D,H simulation
    class E,F ground

Battle-Tested • Versatile • Cross-Platform

Overview: This is the classic, highly mature, and versatile architecture that has been the backbone of drone development for years. It uses MAVLink as the communication protocol, which is the industry standard for autopilot communication.

• Bridge Component: The mavros ROS 2 node runs on the companion computer
• Communication: PX4 communicates using the standard MAVLink protocol
• Protocol: MAVLink messages are translated into ROS 2 topics and services
• Compatibility: Works with multiple autopilots (PX4, ArduPilot, etc.)

• Battle-Tested: Years of production use and community validation
• Cross-Platform: Supports multiple autopilot systems beyond PX4
• Mature Ecosystem: Extensive documentation and community support
• Robust: Well-established error handling and recovery mechanisms

graph TD
    subgraph "🖥️ Companion Computer (ROS 2 Ecosystem)"
        C[🤖 ROS 2 Nodes]
        B[🌉 MAVROS Bridge Node]
        F[👁️ RViz2 Visualization]
        H[🔗 ros_gz_bridge]
    end

    subgraph "🌍 Simulation Environment"
        A[🚁 PX4 SITL Autopilot]
        D[🎮 Gazebo Physics Engine]
    end

    subgraph "📱 Ground Control"
        E[🎛️ QGroundControl]
    end

    %% Primary Data Flow (MAVLink)
    A -.->|"📻 MAVLink UDP<br/>Industry Standard"| B
    B <-->|"📡 ROS 2 Topics<br/>Translated Messages"| C
    
    %% Simulation Integration
    A <-->|"🔌 Physics Interface<br/>Real-time Sync"| D
    D -->|"📊 Sensor Data<br/>ROS 2 Topics"| H
    H <-->|"🔄 Gazebo ↔ ROS 2"| C
    
    %% Visualization & Monitoring
    C -->|"📈 State Visualization"| F
    A -.->|"📻 MAVLink UDP<br/>Direct Connection"| E

    %% Styling
    classDef primary fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef simulation fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef ground fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    
    class A,B,C primary
    class D,H simulation
    class E,F ground

Choose uXRCE-DDS if:

• You're building new applications with PX4
• Performance and latency are critical
• You want the latest, official integration approach
• You're working primarily with PX4 autopilots

Choose MAVROS/MAVLink if:

• You need maximum compatibility across different autopilots
• You're working with legacy systems or existing MAVLink infrastructure
• You prefer battle-tested, production-proven solutions
• You need extensive community support and documentation

Both architectures are fully supported in this simulation environment:

• Automatic Setup: The installation script configures both communication bridges
• Runtime Selection: Switch between architectures based on your launch parameters
• Parallel Operation: Both can run simultaneously for development and testing
• Complete Integration: Full support for sensor data, telemetry, and command interfaces

• PX4 Documentation - Complete PX4 development guide
• ROS 2 Jazzy Docs - ROS 2 development resources
• Gazebo Tutorials - Simulation environment guides
• MAVROS Documentation - MAVLink-ROS 2 bridge documentation
• MAVLink Developer Guide - MAVLink protocol specification
• QGroundControl User Guide - Ground station documentation

# Clean and rebuild
cd ~/shared_volume/ros2_ws
rm -rf build/ install/ log/
colcon build

# Add user to dialout group
sudo usermod -a -G dialout $USER
# Logout and login again

# Check NVIDIA driver
nvidia-smi

# For WSL2, ensure WSL GPU support is enabled

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

We extend our heartfelt gratitude to the following individuals and organizations for their invaluable contributions to the UAV simulation community:

• RIOTU Lab - AI, Deep Learning, ROS, and IoT research laboratory for their innovative work in autonomous systems
• Dr. Mohamed Abdelkader Zahana - For his extensive contributions to PX4 integration, multi-agent systems, and drone control frameworks
• Eng. Khaled Gabr - For his expertise in autonomous navigation and ROS 2 development

Parts of this simulation framework have been refactored and enhanced from the following excellent open-source repositories:

• d2dtracker_sim - Drone-to-drone tracking simulation framework
• gps_denied_navigation_sim - GPS-denied navigation simulation environment

• PX4 Development Team - For the excellent autopilot software
• Open Robotics - For ROS 2 and Gazebo simulation tools
• Eclipse Zenoh - For high-performance middleware
• Community Contributors - For continuous improvements and feedback