simulation/docs/architecture.md

Architecture Overview

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         SIMULATION LAYER                         │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐ │
│  │   Gazebo World   │  │  ArduPilot SITL  │  │    MAVROS     │ │
│  │  (Physics, Viz)  │  │   (Autopilot)    │  │  (ROS Bridge) │ │
│  └────────┬─────────┘  └────────┬─────────┘  └───────┬───────┘ │
└───────────┼─────────────────────┼─────────────────────┼─────────┘
            │                     │                     │
            ▼                     ▼                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                         SENSOR LAYER                             │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌──────────┐  │
│  │  Forward   │  │  Downward  │  │    IMU     │  │  Range-  │  │
│  │  Camera    │  │  Camera    │  │            │  │  finder  │  │
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘  └────┬─────┘  │
└────────┼───────────────┼───────────────┼──────────────┼────────┘
         │               │               │              │
         ▼               ▼               ▼              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       PERCEPTION LAYER                           │
│  ┌─────────────────────┐  ┌────────────────┐  ┌──────────────┐  │
│  │   Visual Odometry   │  │  Optical Flow  │  │  Landmark    │  │
│  │  (ORB/SIFT/SURF)    │  │ (Lucas-Kanade) │  │  Detection   │  │
│  └──────────┬──────────┘  └───────┬────────┘  └──────┬───────┘  │
└─────────────┼─────────────────────┼──────────────────┼──────────┘
              │                     │                  │
              ▼                     ▼                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                      LOCALIZATION LAYER                          │
│                    ┌──────────────────────┐                      │
│                    │   Position Estimator │                      │
│                    │   (EKF Sensor Fusion)│                      │
│                    └──────────┬───────────┘                      │
└───────────────────────────────┼─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                       NAVIGATION LAYER                           │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  Local Planner  │  │    Obstacle     │  │    Waypoint     │  │
│  │                 │  │   Avoidance     │  │    Follower     │  │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  │
└───────────┼────────────────────┼────────────────────┼───────────┘
            │                    │                    │
            ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                        CONTROL LAYER                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  UAV Controller │  │  UGV Controller │  │ Mission Planner │  │
│  │                 │  │                 │  │                 │  │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  │
└───────────┼────────────────────┼────────────────────┼───────────┘
            │                    │                    │
            ▼                    ▼                    ▼
┌─────────────────────────────────────────────────────────────────┐
│                        SAFETY LAYER                              │
│  ┌─────────────────────────┐  ┌─────────────────────────────┐   │
│  │   Geofence Monitor      │  │   Failsafe Handler          │   │
│  │   (GPS-based only)      │  │   (Vision loss, battery)    │   │
│  └─────────────────────────┘  └─────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Module Descriptions

Vision Module (src/vision/)

• camera_processor.py: Image preprocessing, undistortion
• visual_odometry.py: Feature-based pose estimation
• optical_flow.py: Velocity from image flow
• object_detector.py: Landmark/obstacle detection
• visual_servoing.py: Vision-based control

Localization Module (src/localization/)

• position_estimator.py: Sensor fusion for position
• ekf_fusion.py: Extended Kalman Filter implementation
• landmark_tracker.py: Track known visual features

Navigation Module (src/navigation/)

• local_planner.py: Path planning in local frame
• obstacle_avoidance.py: Reactive obstacle avoidance
• waypoint_follower.py: Sequential waypoint navigation

Control Module (src/control/)

• uav_controller.py: Quadcopter flight control
• ugv_controller.py: Ground vehicle control
• mission_planner.py: Multi-vehicle coordination

Safety Module (src/safety/)

• geofence_monitor.py: GPS-based boundary checking
• failsafe_handler.py: Emergency procedures

Data Flow

Camera Image → Feature Detection → Feature Matching → 
Essential Matrix → Relative Pose → EKF Update → 
Local Position → Navigation Controller → 
Velocity Commands → MAVROS → ArduPilot

ROS 2 Topics

Sensor Topics

• /uav/camera/forward/image_raw
• /uav/camera/downward/image_raw
• /uav/imu/data
• /uav/rangefinder/range

Perception Topics

• /uav/visual_odometry/pose
• /uav/optical_flow/velocity

Control Topics

• /uav/mavros/setpoint_position/local
• /uav/mavros/setpoint_velocity/cmd_vel
• /ugv/cmd_vel

Safety Topics

• /geofence/status
• /failsafe/active