RDC_Simulation/docs/architecture.md

Architecture Overview

GPS-denied drone landing simulation with multiple operation modes.

Operation Modes

1. Standalone Mode (Any Platform)

Single-process simulation - no ROS 2 or networking required:

┌────────────────────────────────────────┐
│      standalone_simulation.py          │
│  ┌──────────────────────────────────┐  │
│  │  PyBullet Physics + Camera       │  │
│  │  Built-in Landing Controller     │  │
│  │  Rover Movement Patterns         │  │
│  │  Configuration from config.py    │  │
│  └──────────────────────────────────┘  │
└────────────────────────────────────────┘

2. PyBullet + ROS 2 Mode (Two Terminals)

Terminal 1                    Terminal 2
┌──────────────────┐         ┌──────────────────────────┐
│ simulation_host  │◄─UDP───►│      run_bridge.py       │
│   (PyBullet)     │         │  ┌────────────────────┐  │
│   Port 5555      │         │  │ ROS2SimulatorBridge│  │
│                  │         │  │ DroneController    │  │
│                  │         │  │ RoverController    │  │
└──────────────────┘         │  └────────────────────┘  │
                             └──────────────────────────┘

Data flow:

• RoverController publishes position → Bridge sends to Simulator
• Simulator moves rover visually AND sends back telemetry
• DroneController receives telemetry, publishes commands
• Bridge forwards commands to Simulator

3. Gazebo + ROS 2 Mode (Two Terminals, Linux/WSL2)

Terminal 1                          Terminal 2
┌───────────────────────────┐      ┌──────────────────────────┐
│ ros2 launch ... .launch.py│      │      run_gazebo.py       │
│  ┌─────────────────────┐  │      │  ┌────────────────────┐  │
│  │ Gazebo (ign gazebo) │  │      │  │ GazeboBridge       │  │
│  │  - Drone (vel ctrl) │  │◄────►│  │ DroneController    │  │
│  │  - Rover (vel ctrl) │  │ ROS  │  │ RoverController    │  │
│  ├─────────────────────┤  │      │  └────────────────────┘  │
│  │ ros_gz_bridge       │  │      └──────────────────────────┘
│  └─────────────────────┘  │
└───────────────────────────┘

Data flow:

• RoverController publishes to /rover/cmd_vel → Gazebo moves rover
• Gazebo publishes odometry → GazeboBridge converts to telemetry
• DroneController receives telemetry, publishes to /cmd_vel
• GazeboBridge forwards to /drone/cmd_vel → Gazebo moves drone

4. ArduPilot SITL + Gazebo Mode (Three Terminals, Linux/WSL2)

Terminal 1           Terminal 2              Terminal 3
┌──────────────┐    ┌─────────────────┐     ┌────────────────────────┐
│ Gazebo +     │    │ ArduPilot SITL  │     │   run_ardupilot.py     │
│ ArduPilot    │◄──►│ sim_vehicle.py  │     │  ┌──────────────────┐  │
│ Plugin       │JSON│  + MAVProxy     │◄───►│  │ MAVLinkBridge    │  │
│              │    │                 │ UDP │  │ DroneController  │  │
│ ardupilot_   │    │ Flight Control  │     │  │ RoverController  │  │
│ drone.sdf    │    │ + GCS           │     │  └──────────────────┘  │
└──────────────┘    └─────────────────┘     └────────────────────────┘

Data flow:

• ArduPilot SITL sends motor commands → Gazebo plugin controls drone
• Gazebo plugin sends sensor data → ArduPilot SITL for state estimation
• MAVProxy outputs telemetry → MAVLinkBridge converts to ROS telemetry
• DroneController receives telemetry, publishes velocity commands
• MAVLinkBridge sends MAVLink commands → ArduPilot SITL executes

Key differences from simple Gazebo mode:

• Full ArduPilot flight controller (EKF, stabilization, failsafes)
• Real MAVLink protocol for commands and telemetry
• Support for all ArduPilot flight modes (GUIDED, LAND, etc.)
• Arming checks and safety features
• Compatible with ground control stations (QGroundControl, Mission Planner)

Components

File	Description
config.py	Central configuration (positions, physics, gains)
standalone_simulation.py	All-in-one simulation
simulation_host.py	PyBullet physics server (UDP)
run_bridge.py	PyBullet bridge + controllers
run_gazebo.py	Gazebo bridge + controllers
run_ardupilot.py	ArduPilot SITL + MAVLink bridge
mavlink_bridge.py	MAVLink ↔ ROS 2 bridge
drone_controller.py	Your landing algorithm
rover_controller.py	Moving landing pad
ros_bridge.py	ROS-UDP bridge (used by run_bridge.py)
gazebo_bridge.py	Gazebo-ROS bridge (used by run_gazebo.py)
gazebo/launch/drone_landing.launch.py	ROS 2 launch file for Gazebo
gazebo/launch/ardupilot_drone.launch.py	ROS 2 launch file for ArduPilot
gazebo/worlds/drone_landing.sdf	Gazebo world with simple velocity control
gazebo/worlds/ardupilot_drone.sdf	Gazebo world with ArduPilot plugin

ROS 2 Topics

Topic	Type	Description
/cmd_vel	Twist	Drone commands from DroneController
/drone/cmd_vel	Twist	Drone commands to Gazebo
/drone/telemetry	String	GPS-denied sensor data (JSON)
/rover/cmd_vel	Twist	Rover velocity to simulator
/rover/telemetry	String	Rover position (JSON)

Network Configuration

All components default to 0.0.0.0 for network accessibility.

Remote Setup (PyBullet mode)

Machine 1 (with display):

python simulation_host.py  # Listens on 0.0.0.0:5555

Machine 2 (headless controller):

python run_bridge.py --host 192.168.1.100

UDP Ports

Port	Direction	Content
5555	Bridge → Simulator	Commands (JSON)
5556	Simulator → Bridge	Telemetry (JSON)

GPS-Denied Sensors

All modes provide the same sensor data:

Sensor	Data
IMU	Orientation (roll, pitch, yaw), angular velocity
Altimeter	Altitude above ground, vertical velocity
Velocity	Estimated velocity (x, y, z)
Camera	320x240 downward JPEG (base64)
Landing Pad	Relative position (x, y, distance) when visible

Configuration (config.py)

Section	Parameters
DRONE	mass, size, color, start_position, thrust/torque scales
ROVER	size, color, start_position, default_pattern, default_speed
CAMERA	width, height, fov, jpeg_quality
PHYSICS	gravity, timestep, telemetry_rate
CONTROLLER	Kp_z, Kd_z, Kp_xy, Kd_xy, rate
LANDING	success_distance, success_velocity, height_threshold
NETWORK	host, command_port, telemetry_port

Platform Support

Mode	Ubuntu	Arch	macOS	Windows	WSL2
Standalone	✅	✅	✅	✅	✅
PyBullet+ROS	✅	⚠️	❌	❌	✅
Gazebo+ROS	✅	⚠️	❌	❌	✅