From 79f748d35da7c8fbdb886665694db27723e75c9d Mon Sep 17 00:00:00 2001 From: default Date: Mon, 9 Feb 2026 04:52:32 +0000 Subject: [PATCH] Scripts Update --- README.md | 182 +++------ docs/architecture.md | 210 +++++----- docs/gps_denied_navigation.md | 268 +++++-------- docs/setup_guide.md | 156 ++++---- docs/troubleshooting.md | 348 ++++++++++------- docs/usage.md | 211 +++++----- docs/wsl_setup_guide.md | 697 ++++------------------------------ scripts/run_simulation.sh | 2 +- scripts/uninstall.sh | 150 ++++++++ setup.sh | 13 +- 10 files changed, 861 insertions(+), 1376 deletions(-) create mode 100755 scripts/uninstall.sh diff --git a/README.md b/README.md index 0bdcb7e..bed181d 100644 --- a/README.md +++ b/README.md @@ -1,185 +1,103 @@ -# UAV-UGV Gazebo SITL Simulation -## GPS-Denied Navigation with Geofencing +# UAV-UGV Simulation -A production-ready simulation environment for UAV (drone) and UGV (ground vehicle) development using **GPS-denied navigation** with vision-based localization, while maintaining GPS-based geofencing for safety. +GPS-Denied Navigation with Geofencing -## Key Feature: GPS-Denied Navigation +A simulation environment for UAV and UGV development using GPS-denied navigation with vision-based localization, while maintaining GPS-based geofencing for safety. -**Navigation Mode**: All vehicles navigate using **relative positioning** only: +## GPS-Denied Navigation + +**Navigation**: All vehicles navigate using relative positioning only: - Visual odometry from cameras - Optical flow sensors - IMU integration -- Visual landmark tracking - Local coordinate frames -**GPS Usage**: GPS is ONLY used for: -- Geofencing (safety boundaries) -- NOT used for waypoint navigation -- NOT used for position control +**GPS Usage**: GPS is ONLY used for geofencing (safety boundaries), NOT for navigation or position control. -## System Requirements +## Requirements -- **Ubuntu 22.04 LTS** (or 24.04) -- **16GB RAM** recommended (8GB minimum) -- **50GB disk space** (for ArduPilot + Gazebo) -- NVIDIA GPU recommended but not required +- Ubuntu 22.04 or 24.04 (WSL2 supported) +- 16GB RAM recommended +- 50GB disk space -### Supported Platforms -- Native Ubuntu Linux -- Windows WSL2 with Ubuntu 22.04 - -## Installation (One Command) +## Installation ```bash -# Clone the repository git clone https://git.sirblob.co/SirBlob/simulation.git cd simulation - -# Run the complete setup (installs everything) bash setup.sh ``` -The setup script installs: -- ROS 2 Humble -- Gazebo 11 -- ArduPilot SITL -- ardupilot_gazebo plugin -- MAVROS -- Python dependencies - -**Note**: Full installation takes 20-40 minutes depending on your internet speed. +Installation takes 20-40 minutes (builds ArduPilot from source). ## Quick Start ```bash -# Navigate to project -cd ~/simulation # or wherever you cloned it - -# Activate environment (sets up ROS 2, Gazebo, ArduPilot, Python) +cd ~/simulation source activate_venv.sh - -# Run simulation bash scripts/run_simulation.sh +``` -# For WSL (if graphics issues): +For WSL with graphics issues: +```bash bash scripts/run_simulation.sh --software-render ``` ## Controlling the UAV -Once the simulation is running, control via ROS 2: +Once the simulation is running, use MAVProxy commands in the console: + +``` +mode guided # Switch to GUIDED mode +arm throttle # Arm the drone +takeoff 5 # Takeoff to 5 meters +guided 10 5 -10 # Fly to position (North, East, Down) +rtl # Return to launch +land # Land +``` + +Or via ROS 2: ```bash -# Arm the drone +# Arm ros2 service call /mavros/cmd/arming mavros_msgs/srv/CommandBool "{value: true}" -# Set GUIDED mode (allows position control) -ros2 service call /mavros/set_mode mavros_msgs/srv/SetMode "{custom_mode: 'GUIDED'}" - -# Takeoff to 5 meters +# Takeoff ros2 service call /mavros/cmd/takeoff mavros_msgs/srv/CommandTOL "{altitude: 5}" -# Fly to position (LOCAL coordinates - no GPS!) +# Fly to position (local coordinates) ros2 topic pub /mavros/setpoint_position/local geometry_msgs/PoseStamped \ "{header: {frame_id: 'map'}, pose: {position: {x: 10, y: 5, z: 5}}}" - -# Land -ros2 service call /mavros/cmd/land mavros_msgs/srv/CommandTOL "{}" ``` -## Features - -- **Iris quadcopter** with dual cameras (forward + downward) -- **Ground vehicle (UGV)** with vision sensors -- **Visual odometry** - camera-based position estimation -- **Optical flow** - velocity estimation from downward camera -- **GPS geofencing** - safety boundaries only -- **ArduPilot SITL** - real flight controller firmware -- **MAVROS** - ROS 2 interface for MAVLink -- **Multiple worlds** - indoor warehouse, urban canyon - -## GPS-Denied Navigation Architecture - -``` -┌─────────────────────────────────────────────────────┐ -│ Vision Sensors │ -│ Forward Camera + Downward Camera + Optical Flow │ -└─────────────────┬───────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ Visual Odometry & Feature Tracking │ -│ Estimates relative position from camera motion │ -└─────────────────┬───────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ Position Estimator (EKF Fusion) │ -│ Fuses: Visual Odom + Optical Flow + IMU │ -│ Output: Local position estimate (relative) │ -└─────────────────┬───────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────┐ -│ ArduPilot Flight Controller │ -│ Receives position via MAVROS (external nav) │ -│ Controls motors based on local setpoints │ -└─────────────────────────────────────────────────────┘ -``` - -## Project Structure - -``` -simulation/ -├── setup.sh # One-command installation -├── activate_venv.sh # Environment activation -├── scripts/ -│ ├── run_simulation.sh # Launch full simulation -│ └── kill_simulation.sh # Stop all processes -├── worlds/ # Gazebo world files -├── models/ # UAV and UGV models -├── src/ -│ ├── vision/ # Visual odometry, optical flow -│ ├── localization/ # EKF sensor fusion -│ ├── navigation/ # Path planning -│ ├── control/ # UAV/UGV controllers -│ └── safety/ # Geofencing -├── config/ # Configuration files -└── docs/ # Documentation -``` - -## Documentation - -- [Setup Guide](docs/setup_guide.md) - Detailed installation -- [WSL Setup Guide](docs/wsl_setup_guide.md) - Windows WSL2 -- [Usage Guide](docs/usage.md) - How to use -- [Architecture](docs/architecture.md) - System design -- [GPS-Denied Navigation](docs/gps_denied_navigation.md) - Navigation approach -- [Troubleshooting](docs/troubleshooting.md) - Common issues - ## Simulation Options ```bash -# Default (ArduPilot Iris world) +# Default bash scripts/run_simulation.sh # Custom world -bash scripts/run_simulation.sh --world worlds/indoor_warehouse.world +bash scripts/run_simulation.sh --world iris_runway # Rover instead of copter -bash scripts/run_simulation.sh --vehicle rover +bash scripts/run_simulation.sh --vehicle Rover -# Software rendering (WSL/no GPU) +# Software rendering (WSL) bash scripts/run_simulation.sh --software-render ``` -## Key Differences from GPS Navigation +## Uninstall -| Aspect | GPS Navigation | This Project (GPS-Denied) | -|--------|---------------|---------------------------| -| Position Source | GPS satellites | Visual odometry + sensors | -| Waypoint Type | GPS coordinates | Relative coordinates (x,y,z) | -| Reference Frame | Global (lat/lon) | Local (relative to start) | -| Indoor Capability | No | Yes | -| Drift | Minimal | Accumulates over time | -| Geofencing | GPS-based | GPS-based (safety only) | +```bash +bash scripts/uninstall.sh # Remove ArduPilot and plugin +bash scripts/uninstall.sh --all # Remove everything +``` + +## Documentation + +- [Setup Guide](docs/setup_guide.md) +- [WSL Setup Guide](docs/wsl_setup_guide.md) +- [Usage Guide](docs/usage.md) +- [Architecture](docs/architecture.md) +- [GPS-Denied Navigation](docs/gps_denied_navigation.md) +- [Troubleshooting](docs/troubleshooting.md) diff --git a/docs/architecture.md b/docs/architecture.md index 83df69c..17e36fc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,126 +1,120 @@ -# Architecture Overview +# Architecture -## System Architecture +System architecture for GPS-denied UAV/UGV navigation. + +## Overview + +The system uses vision-based navigation with GPS reserved only for geofencing. ``` -┌─────────────────────────────────────────────────────────────────┐ -│ 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) │ │ -│ └─────────────────────────┘ └─────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ +Vision Sensors (Cameras) + | + v +Visual Odometry & Optical Flow + | + v +Position Estimator (EKF) + | + v +ArduPilot Flight Controller + | + v +Motor Control ``` -## Module Descriptions +## Components -### 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 +### Perception -### 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 +- **Forward Camera**: Visual odometry, feature tracking +- **Downward Camera**: Optical flow, ground plane detection +- **IMU**: Angular velocity, acceleration -### Navigation Module (`src/navigation/`) -- **local_planner.py**: Path planning in local frame -- **obstacle_avoidance.py**: Reactive obstacle avoidance -- **waypoint_follower.py**: Sequential waypoint navigation +### Localization -### Control Module (`src/control/`) -- **uav_controller.py**: Quadcopter flight control -- **ugv_controller.py**: Ground vehicle control -- **mission_planner.py**: Multi-vehicle coordination +- **Visual Odometry**: Estimates motion from camera images +- **Optical Flow**: Velocity estimation from downward camera +- **EKF Fusion**: Combines all sensor inputs into position estimate -### Safety Module (`src/safety/`) -- **geofence_monitor.py**: GPS-based boundary checking -- **failsafe_handler.py**: Emergency procedures +### Navigation + +- **Waypoint Navigation**: Relative coordinates (meters from origin) +- **Path Planning**: Collision-free paths using local map +- **Position Hold**: Maintain position using vision + +### Control + +- **ArduPilot**: Flight controller firmware +- **MAVROS**: ROS interface to ArduPilot +- **Velocity/Position Control**: Low-level motor commands + +### Safety + +- **Geofencing**: GPS-based boundary checking (safety only) +- **Altitude Limits**: Maximum flight ceiling +- **Failsafe**: RTL on signal loss or boundary breach + +## Coordinate Frames + +| Frame | Description | +|-------|-------------| +| body | Attached to vehicle, X forward, Y right, Z down | +| odom | Origin at takeoff, accumulates drift | +| map | Fixed world frame (may be corrected) | + +All navigation commands use local coordinates relative to takeoff point. ## Data Flow ``` -Camera Image → Feature Detection → Feature Matching → -Essential Matrix → Relative Pose → EKF Update → -Local Position → Navigation Controller → -Velocity Commands → MAVROS → ArduPilot +Camera Images + | + v +Feature Detection (ORB/SIFT) + | + v +Feature Matching (frame to frame) + | + v +Motion Estimation (Essential Matrix) + | + v +EKF Update (fuse with IMU) + | + v +Position Estimate (x, y, z, roll, pitch, yaw) + | + v +ArduPilot (external position input) + | + v +PID Control -> Motor PWM ``` +## ArduPilot Integration + +ArduPilot receives external position via MAVLink: + +1. Visual odometry → `VISION_POSITION_ESTIMATE` +2. EKF uses external source (EK3_SRC1_POSXY=6) +3. GPS disabled for navigation (GPS_TYPE=0 or EK3_SRC1_POSXY!=1) + +## Geofencing + +GPS is only used for safety boundaries: + +1. GPS position → lat/lon +2. Check against polygon/circle boundary +3. If outside: trigger RTL or LAND + +Navigation continues using vision regardless of GPS status. + ## 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` - +| Topic | Type | Description | +|-------|------|-------------| +| /uav/camera/forward/image_raw | sensor_msgs/Image | Forward camera | +| /uav/camera/downward/image_raw | sensor_msgs/Image | Downward camera | +| /mavros/local_position/pose | geometry_msgs/PoseStamped | Current position | +| /mavros/setpoint_position/local | geometry_msgs/PoseStamped | Target position | +| /mavros/imu/data | sensor_msgs/Imu | IMU data | diff --git a/docs/gps_denied_navigation.md b/docs/gps_denied_navigation.md index 073b05b..f12eac1 100644 --- a/docs/gps_denied_navigation.md +++ b/docs/gps_denied_navigation.md @@ -1,198 +1,128 @@ # GPS-Denied Navigation -## Overview +How the system navigates without GPS. -This project implements **GPS-denied navigation** for UAV and UGV vehicles. Instead of relying on GPS for position estimation and waypoint navigation, the system uses vision-based sensors and local coordinate frames. +## Principle -## Why GPS-Denied? +All navigation uses relative positioning from visual sensors. GPS is only used for geofencing (safety boundaries). -GPS-denied navigation is critical for scenarios where GPS is: +| Function | GPS Used? | +|----------|-----------| +| Position estimation | No - visual odometry | +| Waypoint navigation | No - local coordinates | +| Velocity control | No - optical flow | +| Geofencing | Yes - safety only | -1. **Unavailable**: Indoor environments, underground, tunnels -2. **Unreliable**: Urban canyons with multipath errors -3. **Jammed/Spoofed**: Electronic warfare, contested environments -4. **Degraded**: Under bridges, heavy foliage, near tall structures +## Position Estimation -## Navigation Architecture +### Visual Odometry + +1. Detect features in camera image (ORB, SIFT) +2. Match features between consecutive frames +3. Estimate camera motion from feature displacement +4. Accumulate motion into position estimate + +### Optical Flow + +1. Capture ground images from downward camera +2. Measure pixel displacement between frames +3. Convert to velocity using altitude +4. Integrate for position + +### Sensor Fusion + +Extended Kalman Filter combines: +- Visual odometry (position) +- Optical flow (velocity) +- IMU (acceleration, rotation) +- Barometer (altitude) + +Output: Full 6-DOF pose estimate + +## ArduPilot Configuration + +Key parameters for GPS-denied operation: ``` -┌─────────────────────────────────────────────────┐ -│ VISION SENSORS │ -│ • Forward Camera (640x480, 30Hz) │ -│ • Downward Camera (320x240, 30Hz) │ -│ • Optional: Depth Camera, LiDAR │ -└───────────────────┬─────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────┐ -│ VISUAL ODOMETRY MODULE │ -│ • Feature detection (ORB/SIFT/SURF) │ -│ • Feature matching between frames │ -│ • Essential matrix estimation │ -│ • Relative pose computation │ -└───────────────────┬─────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────┐ -│ OPTICAL FLOW MODULE │ -│ • Lucas-Kanade optical flow │ -│ • Velocity estimation from flow vectors │ -│ • Height compensation using rangefinder │ -└───────────────────┬─────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────┐ -│ POSITION ESTIMATOR (EKF) │ -│ Fuses: │ -│ • Visual odometry (weight: 0.6) │ -│ • Optical flow (weight: 0.3) │ -│ • IMU integration (weight: 0.1) │ -│ Output: Local position/velocity estimate │ -└───────────────────┬─────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────┐ -│ NAVIGATION CONTROLLER │ -│ • Waypoints in LOCAL frame (x, y, z meters) │ -│ • Path planning using relative coordinates │ -│ • Obstacle avoidance using depth/camera │ -└─────────────────────────────────────────────────┘ +# EKF Source Configuration +EK3_SRC1_POSXY = 6 # External Nav for position +EK3_SRC1_VELXY = 6 # External Nav for velocity +EK3_SRC1_POSZ = 1 # Barometer for altitude + +# Disable GPS for navigation +GPS_TYPE = 0 # No GPS (or keep for geofence) + +# Enable external navigation +VISO_TYPE = 1 # Enable visual odometry input + +# Arming checks +ARMING_CHECK = 0 # Disable pre-arm checks (for testing) ``` -## Coordinate Frames +See `config/ardupilot_gps_denied.parm` for complete parameters. -### LOCAL_NED Frame -- **Origin**: Vehicle starting position -- **X**: North (forward) -- **Y**: East (right) -- **Z**: Down +## Sending Position to ArduPilot -### Body Frame -- **X**: Forward -- **Y**: Right -- **Z**: Down +Visual odometry sends position via MAVLink: -## GPS Usage: Geofencing Only +```python +# VISION_POSITION_ESTIMATE message +msg = mavutil.mavlink.MAVLink_vision_position_estimate_message( + usec=timestamp_us, + x=position_x, # meters, NED frame + y=position_y, + z=position_z, + roll=roll, # radians + pitch=pitch, + yaw=yaw +) +``` -While navigation is GPS-denied, GPS is still used for **geofencing** (safety boundaries): +## Drift Mitigation + +Visual odometry accumulates drift over time. Strategies: + +1. **Loop Closure**: Recognize previously visited locations +2. **Landmark Matching**: Use known visual markers +3. **Multi-Sensor Fusion**: Weight sensors by confidence +4. **Periodic Reset**: Return to known position + +## Geofencing + +GPS is only used for safety boundaries: ```yaml geofence: enabled: true - use_gps: true # GPS ONLY for geofence check - - polygon_points: - - {lat: 47.397742, lon: 8.545594} - - {lat: 47.398242, lon: 8.545594} - - {lat: 47.398242, lon: 8.546094} - - {lat: 47.397742, lon: 8.546094} - - action_on_breach: "RTL" # Return to LOCAL origin + use_gps: true + fence_type: polygon + action: RTL + max_altitude: 50 ``` -## Example: Relative Waypoint Mission +If drone crosses boundary, triggers return-to-launch. +## Coordinate System + +All waypoints use local NED coordinates: +- X: North (meters from origin) +- Y: East (meters from origin) +- Z: Down (negative for altitude) + +Example mission: ```python -# All waypoints are in LOCAL frame (meters from origin) waypoints = [ - {"x": 0, "y": 0, "z": 5}, # Takeoff to 5m - {"x": 10, "y": 0, "z": 5}, # 10m forward - {"x": 10, "y": 10, "z": 5}, # 10m right - {"x": 0, "y": 0, "z": 5}, # Return to origin + {"x": 0, "y": 0, "z": -5}, # Takeoff to 5m + {"x": 10, "y": 0, "z": -5}, # 10m north + {"x": 10, "y": 10, "z": -5}, # 10m east + {"x": 0, "y": 0, "z": -5}, # Return {"x": 0, "y": 0, "z": 0}, # Land ] ``` -## Sensor Fusion Details - -### Extended Kalman Filter State - -``` -State vector x = [px, py, pz, vx, vy, vz, ax, ay, az] - -Where: -- px, py, pz = position (meters) -- vx, vy, vz = velocity (m/s) -- ax, ay, az = acceleration (m/s²) -``` - -### Measurement Sources - -| Source | Measures | Update Rate | Noise | -|-----------------|----------------|-------------|-------| -| Visual Odometry | Position | 30 Hz | 0.05m | -| Optical Flow | Velocity | 60 Hz | 0.1m/s| -| IMU | Acceleration | 200 Hz | 0.2m/s²| -| Rangefinder | Altitude | 30 Hz | 0.02m | - -## Drift Mitigation - -GPS-denied navigation accumulates drift over time. Mitigation strategies: - -1. **Visual Landmarks**: Detect and track known markers (ArUco) -2. **Loop Closure**: Recognize previously visited locations -3. **Ground Truth Reset**: Periodic reset in simulation -4. **Multi-Sensor Fusion**: Reduce individual sensor drift - -## Configuration Parameters - -### Visual Odometry - -```yaml -visual_odometry: - method: "ORB" # or "SIFT", "SURF" - min_features: 100 - max_features: 500 - feature_quality: 0.01 -``` - -### Optical Flow - -```yaml -optical_flow: - method: "Lucas-Kanade" - window_size: 15 - max_level: 3 - min_altitude: 0.3 # meters -``` - -### Position Estimator - -```yaml -position_estimator: - fusion_method: "EKF" - weights: - visual_odometry: 0.6 - optical_flow: 0.3 - imu: 0.1 -``` - -## Testing GPS-Denied Navigation - -### Indoor Warehouse World -```bash -bash scripts/run_simulation.sh worlds/indoor_warehouse.world -``` - -### Urban Canyon World -```bash -bash scripts/run_simulation.sh worlds/urban_canyon.world -``` - -## Troubleshooting - -### High Position Drift -- Check camera exposure/focus -- Ensure sufficient visual features in environment -- Increase feature count in visual odometry -- Add visual markers to environment - -### Vision Loss -- The failsafe handler triggers after 5 seconds of no visual odometry -- Action: HOLD (hover in place) by default -- Configure with `action_on_vision_loss` parameter - -### Geofence Breach -- Vehicle returns to LOCAL origin (not GPS home) -- RTL uses the same local coordinate system +## Limitations +- Drift accumulates over distance/time +- Requires visual features (fails in featureless environments) +- Requires sufficient lighting +- Performance degrades with fast motion or blur diff --git a/docs/setup_guide.md b/docs/setup_guide.md index ff7d88c..3166a84 100644 --- a/docs/setup_guide.md +++ b/docs/setup_guide.md @@ -1,144 +1,116 @@ # Setup Guide -## System Requirements +Complete installation for Ubuntu 22.04/24.04 and WSL2. -- **OS**: Ubuntu 22.04 LTS (Jammy Jellyfish) -- **Python**: 3.10.x (native to Ubuntu 22.04) -- **ROS 2**: Humble Hawksbill -- **Gazebo**: Classic 11 -- **RAM**: 8GB minimum, 16GB recommended -- **GPU**: NVIDIA GPU recommended for better performance +## One-Command Installation -## Installation Steps +```bash +git clone https://git.sirblob.co/SirBlob/simulation.git +cd simulation +bash setup.sh +``` -### 1. Install ROS 2 Humble +The script installs: +- ROS 2 (Humble or Jazzy) +- Gazebo Harmonic +- ArduPilot SITL +- ardupilot_gazebo plugin +- Python dependencies + +Installation takes 20-40 minutes. + +## Manual Installation + +If you prefer to install components separately: + +### 1. ROS 2 ```bash # Add ROS 2 repository -sudo apt update && sudo apt install curl gnupg lsb-release -sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg -echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null +sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \ + -o /usr/share/keyrings/ros-archive-keyring.gpg + +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] \ + http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | \ + sudo tee /etc/apt/sources.list.d/ros2.list -# Install ROS 2 Humble sudo apt update -sudo apt install ros-humble-desktop - -# Source ROS 2 -echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc -source ~/.bashrc +sudo apt install ros-humble-ros-base ros-humble-ros-gz ``` -### 2. Install Gazebo Classic +### 2. Gazebo Harmonic ```bash -sudo apt install gazebo11 libgazebo11-dev ros-humble-gazebo-ros-pkgs +sudo wget https://packages.osrfoundation.org/gazebo.gpg \ + -O /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg + +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] \ + http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | \ + sudo tee /etc/apt/sources.list.d/gazebo-stable.list + +sudo apt update +sudo apt install gz-harmonic libgz-cmake3-dev libgz-sim8-dev ``` -### 3. Install ArduPilot SITL +### 3. ArduPilot SITL ```bash -# Clone ArduPilot -cd ~ -git clone https://github.com/ArduPilot/ardupilot.git -cd ardupilot -git submodule update --init --recursive - -# Install dependencies +git clone --recurse-submodules https://github.com/ArduPilot/ardupilot.git ~/ardupilot +cd ~/ardupilot Tools/environment_install/install-prereqs-ubuntu.sh -y . ~/.profile - -# Build SITL ./waf configure --board sitl ./waf copter ``` -### 4. Install ardupilot_gazebo Plugin +### 4. ardupilot_gazebo Plugin ```bash -cd ~ -git clone https://github.com/ArduPilot/ardupilot_gazebo.git -cd ardupilot_gazebo +git clone https://github.com/ArduPilot/ardupilot_gazebo.git ~/ardupilot_gazebo +cd ~/ardupilot_gazebo mkdir build && cd build -cmake .. -make -j4 -sudo make install - -# Add to environment -echo 'export GAZEBO_MODEL_PATH=$HOME/ardupilot_gazebo/models:$GAZEBO_MODEL_PATH' >> ~/.bashrc -echo 'export GAZEBO_RESOURCE_PATH=$HOME/ardupilot_gazebo/worlds:$GAZEBO_RESOURCE_PATH' >> ~/.bashrc -source ~/.bashrc +cmake .. -DCMAKE_BUILD_TYPE=Release +make -j$(nproc) ``` -### 5. Setup This Project +### 5. Python Environment ```bash -# Clone to ROS 2 workspace -cd ~/ros2_ws/src -git clone uav_ugv_simulation -cd uav_ugv_simulation - -# Run automated setup -bash setup.sh - -# Reload environment -source ~/.bashrc +cd ~/simulation +python3 -m venv venv +source venv/bin/activate +pip install -r requirements.txt ``` -## Verification +## Verify Installation -### Test ROS 2 ```bash -ros2 topic list -``` +# Check Gazebo +gz sim --version -### Test Gazebo -```bash -gazebo --verbose -``` +# Check ArduPilot +sim_vehicle.py --help -### Test ArduPilot SITL -```bash -cd ~/ardupilot/ArduCopter -sim_vehicle.py -v ArduCopter -f gazebo-iris --console --map -``` - -### Test Python Environment -```bash -cd ~/ros2_ws/src/uav_ugv_simulation -source activate_venv.sh -python -c "import cv2; import numpy; import rclpy; print('OK')" +# Check plugin +ls ~/ardupilot_gazebo/build/libArduPilotPlugin.so ``` ## Running the Simulation ```bash -cd ~/ros2_ws/src/uav_ugv_simulation +cd ~/simulation source activate_venv.sh bash scripts/run_simulation.sh ``` -## NVIDIA GPU Setup (Optional) - -For better Gazebo performance with NVIDIA GPU: +## Uninstall ```bash -bash scripts/setup_gazebo_nvidia.sh +bash scripts/uninstall.sh # ArduPilot and plugin only +bash scripts/uninstall.sh --all # Everything including project ``` -## Troubleshooting - -### "Package not found" error +To remove ROS 2 and Gazebo: ```bash -cd ~/ros2_ws -colcon build --packages-select uav_ugv_simulation -source install/setup.bash +sudo apt remove ros-humble-* gz-harmonic ``` - -### Gazebo crashes -- Check GPU drivers: `nvidia-smi` -- Try software rendering: `export LIBGL_ALWAYS_SOFTWARE=1` - -### MAVROS connection failed -- Ensure ArduPilot SITL is running first -- Check port availability: `lsof -i :14550` - diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index cf455c2..d75adea 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,178 +1,236 @@ -# Troubleshooting Guide +# Troubleshooting -## Common Issues +Common issues and solutions. -### 1. Gazebo Won't Start +## Installation Issues -**Symptoms**: Gazebo window doesn't open, or crashes immediately +### ROS 2 packages not found -**Solutions**: +``` +E: Unable to locate package ros-humble-ros-base +``` + +Check Ubuntu version matches ROS distro: +- Ubuntu 22.04 → ROS 2 Humble +- Ubuntu 24.04 → ROS 2 Jazzy + +Re-run setup: ```bash -# Kill any existing Gazebo processes -killall gzserver gzclient +bash setup.sh +``` -# Check for port conflicts -lsof -i :11345 +### Gazebo cmake error (gz-cmake3 not found) -# Try software rendering +``` +Could not find a package configuration file provided by "gz-cmake3" +``` + +Install Gazebo development packages: +```bash +sudo apt install libgz-cmake3-dev libgz-sim8-dev libgz-plugin2-dev +``` + +### ArduPilot build fails + +```bash +cd ~/ardupilot +./waf clean +./waf configure --board sitl +./waf copter +``` + +### ardupilot_gazebo build fails + +Ensure Gazebo dev packages are installed: +```bash +sudo apt install gz-harmonic libgz-cmake3-dev libgz-sim8-dev \ + libgz-plugin2-dev libgz-common5-dev libgz-physics7-dev \ + libgz-sensors8-dev rapidjson-dev +``` + +Rebuild: +```bash +cd ~/ardupilot_gazebo +rm -rf build +mkdir build && cd build +cmake .. -DCMAKE_BUILD_TYPE=Release +make -j$(nproc) +``` + +## Runtime Issues + +### Gazebo won't start + +Check Gazebo installation: +```bash +gz sim --version +``` + +Check plugin path: +```bash +echo $GZ_SIM_SYSTEM_PLUGIN_PATH +ls ~/ardupilot_gazebo/build/libArduPilotPlugin.so +``` + +### Black screen in Gazebo (WSL) + +Use software rendering: +```bash export LIBGL_ALWAYS_SOFTWARE=1 -gazebo +bash scripts/run_simulation.sh ``` -### 2. ArduPilot SITL Connection Failed - -**Symptoms**: MAVROS can't connect to ArduPilot - -**Solutions**: +Or use the flag: ```bash -# Check if SITL is running -ps aux | grep ArduCopter - -# Check port availability -lsof -i :14550 - -# Start SITL manually first -cd ~/ardupilot/ArduCopter -sim_vehicle.py -v ArduCopter -f gazebo-iris --console - -# Then start MAVROS -ros2 run mavros mavros_node --ros-args -p fcu_url:=udp://:14550@127.0.0.1:14555 +bash scripts/run_simulation.sh --software-render ``` -### 3. Visual Odometry Not Working +### Gazebo crashes with OpenGL error -**Symptoms**: No pose output, high drift - -**Solutions**: -- Ensure camera is publishing: - ```bash - ros2 topic hz /uav/camera/forward/image_raw - ``` -- Check for sufficient visual features in scene -- Adjust feature detection parameters in `config/uav_params.yaml` -- Add visual markers to the world - -### 4. Vehicle Won't Arm - -**Symptoms**: Arm command fails - -**Solutions**: ```bash -# Check MAVROS state -ros2 topic echo /uav/mavros/state - -# Check for prearm errors -ros2 topic echo /uav/mavros/statustext/recv - -# Force arm (use with caution) -ros2 service call /uav/mavros/cmd/arming mavros_msgs/srv/CommandBool "{value: true}" +export MESA_GL_VERSION_OVERRIDE=3.3 +export MESA_GLSL_VERSION_OVERRIDE=330 +export LIBGL_ALWAYS_SOFTWARE=1 ``` -### 5. Geofence Immediately Triggers +### sim_vehicle.py not found -**Symptoms**: Vehicle triggers geofence breach on startup - -**Solutions**: -- Check GPS coordinates in `config/geofence_params.yaml` -- Ensure Gazebo world has correct `spherical_coordinates` -- Verify MAVROS is receiving GPS: - ```bash - ros2 topic echo /uav/mavros/global_position/global - ``` - -### 6. High CPU/Memory Usage - -**Symptoms**: System becomes slow during simulation - -**Solutions**: -- Reduce camera resolution in model SDF files -- Lower Gazebo real-time factor -- Disable unnecessary visualizations -- Use headless mode: - ```bash - gazebo --headless - ``` - -### 7. ROS 2 Package Not Found - -**Symptoms**: `Package 'uav_ugv_simulation' not found` - -**Solutions**: ```bash -# Rebuild the package -cd ~/ros2_ws -colcon build --packages-select uav_ugv_simulation - -# Source the workspace -source install/setup.bash - -# Verify installation -ros2 pkg list | grep uav_ugv +export PATH=$PATH:$HOME/ardupilot/Tools/autotest ``` -### 8. Python Import Errors - -**Symptoms**: `ModuleNotFoundError: No module named 'xxx'` - -**Solutions**: +Or source the activation script: ```bash -# Activate virtual environment source activate_venv.sh - -# Reinstall requirements -pip install -r requirements.txt ``` -### 9. Camera Images Are Black - -**Symptoms**: Camera topic publishes but images are empty - -**Solutions**: -- Check lighting in Gazebo world -- Verify camera plugin is loaded: - ```bash - ros2 topic info /uav/camera/forward/image_raw - ``` -- Check camera is within clip range - -### 10. Vehicle Drifts Excessively - -**Symptoms**: Position estimate diverges from actual position - -**Solutions**: -- Increase visual features in environment -- Add ArUco markers for landmark tracking -- Tune EKF covariances in `config/uav_params.yaml` -- Check optical flow height compensation - -## Debug Commands +### MAVProxy not found ```bash -# View all ROS nodes -ros2 node list - -# Check topic connections -ros2 topic info /topic_name - -# View parameter values -ros2 param dump /node_name - -# Echo topic data -ros2 topic echo /topic_name --once - -# View TF tree -ros2 run tf2_tools view_frames +pip3 install --user mavproxy pymavlink +export PATH=$PATH:$HOME/.local/bin ``` -## Log Files +### Drone doesn't respond to commands -- Gazebo: `~/.gazebo/log/` -- ROS 2: `~/.ros/log/` -- ArduPilot: Check console window +1. Check ArduPilot is running: +```bash +ps aux | grep arducopter +``` -## Getting Help +2. Check connection: +``` +# In MAVProxy console +status +``` -1. Check ROS 2 logs: `ros2 launch --debug ...` -2. Enable verbose Gazebo: `gazebo --verbose` -3. Check ArduPilot parameters: Use MAVProxy console +3. Ensure GUIDED mode: +``` +mode guided +``` +4. Arm the drone: +``` +arm throttle +``` + +### Drone immediately disarms + +Usually means pre-arm checks failing: +``` +# In MAVProxy console +arm check +``` + +Common fixes: +``` +# Disable GPS check for GPS-denied operation +param set ARMING_CHECK 0 +``` + +### Drone drifts or flips on takeoff + +Check EKF is using vision/external nav: +``` +# In MAVProxy console +param show EK3_SRC* +``` + +## WSL-Specific Issues + +### DISPLAY not set + +For WSLg (Windows 11): +```bash +export DISPLAY=:0 +``` + +For VcXsrv (Windows 10): +```bash +export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0 +``` + +### VcXsrv connection refused + +1. Ensure XLaunch is running +2. Disable access control in XLaunch +3. Check Windows Firewall allows VcXsrv + +### Slow graphics performance + +```bash +# Use software rendering +bash scripts/run_simulation.sh --software-render + +# Or set environment +export LIBGL_ALWAYS_SOFTWARE=1 +``` + +## Logs and Debugging + +### Gazebo verbose output + +```bash +gz sim -v4 ~/ardupilot_gazebo/worlds/iris_runway.sdf +``` + +### ArduPilot logs + +Logs are saved in: +``` +~/ardupilot/logs/ +``` + +### Check ROS topics + +```bash +source activate_venv.sh +ros2 topic list +ros2 topic echo /mavros/state +``` + +## Reset Everything + +```bash +# Stop all processes +bash scripts/kill_simulation.sh + +# Clean rebuild of ArduPilot +cd ~/ardupilot +./waf clean +./waf copter + +# Clean rebuild of plugin +cd ~/ardupilot_gazebo +rm -rf build +mkdir build && cd build +cmake .. +make -j$(nproc) +``` + +## Full Reinstall + +```bash +bash scripts/uninstall.sh +bash setup.sh +``` diff --git a/docs/usage.md b/docs/usage.md index 73930a1..3a81195 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,151 +1,136 @@ # Usage Guide -## Quick Start +How to run and control the simulation. + +## Starting the Simulation ```bash -# 1. Navigate to project -cd ~/ros2_ws/src/uav_ugv_simulation - -# 2. Activate environment +cd ~/simulation source activate_venv.sh - -# 3. Run simulation bash scripts/run_simulation.sh ``` -## Launch Options +This launches: +1. Gazebo with the drone model +2. ArduPilot SITL (flight controller) +3. MAVProxy console (for commands) + +## Simulation Options -### Full Simulation (UAV + UGV) ```bash -ros2 launch uav_ugv_simulation full_simulation.launch.py +# Default (iris_runway world) +bash scripts/run_simulation.sh + +# Specific world +bash scripts/run_simulation.sh --world iris_runway + +# Rover instead of copter +bash scripts/run_simulation.sh --vehicle Rover + +# Software rendering (for WSL or no GPU) +bash scripts/run_simulation.sh --software-render + +# Show available options +bash scripts/run_simulation.sh --help ``` -### UAV Only -```bash -ros2 launch uav_ugv_simulation uav_only.launch.py +## Controlling the UAV + +### MAVProxy Console + +The simulation opens a MAVProxy console. Commands: + +``` +mode guided # Switch to GUIDED mode (required for commands) +arm throttle # Arm motors +takeoff 5 # Takeoff to 5 meters altitude + +# Fly to position (North, East, Down in meters) +guided 10 0 -5 # 10m north, 0m east, 5m altitude +guided 10 10 -5 # 10m north, 10m east, 5m altitude +guided 0 0 -5 # Return to origin at 5m altitude + +rtl # Return to launch +land # Land at current position +disarm # Disarm motors (after landing) ``` -### UGV Only +### ROS 2 Interface + +If MAVROS is running, control via ROS 2: + ```bash -ros2 launch uav_ugv_simulation ugv_only.launch.py -``` +# Arm +ros2 service call /mavros/cmd/arming mavros_msgs/srv/CommandBool "{value: true}" -### Different Worlds -```bash -# Indoor warehouse (GPS-denied) -bash scripts/run_simulation.sh worlds/indoor_warehouse.world - -# Urban canyon (GPS-degraded) -bash scripts/run_simulation.sh worlds/urban_canyon.world -``` - -## Interacting with Vehicles - -### UAV Commands -```bash -# Arm the vehicle -ros2 topic pub /uav/controller/command std_msgs/String "data: 'arm'" +# Set GUIDED mode +ros2 service call /mavros/set_mode mavros_msgs/srv/SetMode "{custom_mode: 'GUIDED'}" # Takeoff -ros2 topic pub /uav/controller/command std_msgs/String "data: 'takeoff'" +ros2 service call /mavros/cmd/takeoff mavros_msgs/srv/CommandTOL "{altitude: 5}" -# Go to waypoint (local coordinates) -ros2 topic pub /uav/setpoint_position geometry_msgs/PoseStamped \ - "{header: {frame_id: 'odom'}, pose: {position: {x: 10.0, y: 5.0, z: 5.0}}}" +# Fly to position (local frame, meters) +ros2 topic pub /mavros/setpoint_position/local geometry_msgs/PoseStamped \ + "{header: {frame_id: 'map'}, pose: {position: {x: 10, y: 5, z: 5}}}" # Land -ros2 topic pub /uav/controller/command std_msgs/String "data: 'land'" +ros2 service call /mavros/cmd/land mavros_msgs/srv/CommandTOL "{}" ``` -### UGV Commands +### Monitoring + ```bash -# Go to goal (local coordinates) -ros2 topic pub /ugv/goal_pose geometry_msgs/PoseStamped \ - "{header: {frame_id: 'odom'}, pose: {position: {x: 5.0, y: 3.0, z: 0.0}}}" - -# Stop -ros2 topic pub /ugv/controller/command std_msgs/String "data: 'stop'" -``` - -## Mission Planner - -### Load Demo Mission -```bash -ros2 topic pub /mission/command std_msgs/String "data: 'load'" -``` - -### Start Mission -```bash -ros2 topic pub /mission/command std_msgs/String "data: 'start'" -``` - -### Pause/Resume -```bash -ros2 topic pub /mission/command std_msgs/String "data: 'pause'" -ros2 topic pub /mission/command std_msgs/String "data: 'resume'" -``` - -## Monitoring - -### View Topics -```bash -# List all topics +# List topics ros2 topic list -# UAV status -ros2 topic echo /uav/controller/status +# View position +ros2 topic echo /mavros/local_position/pose -# Visual odometry pose -ros2 topic echo /uav/visual_odometry/pose +# View velocity +ros2 topic echo /mavros/local_position/velocity_local -# Geofence status -ros2 topic echo /geofence/status +# View IMU +ros2 topic echo /mavros/imu/data ``` -### View Camera Feeds -```bash -# Using rqt_image_view -ros2 run rqt_image_view rqt_image_view +## Flight Modes -# Select topics: -# /uav/camera/forward/image_raw -# /uav/camera/downward/image_raw -``` - -### Visualization -```bash -# RViz -rviz2 - -# Add displays for: -# - TF -# - Camera -# - Path -# - Marker (geofence) -``` - -## Configuration - -### Modify Parameters - -Edit YAML files in `config/` directory: - -- `uav_params.yaml` - UAV settings -- `geofence_params.yaml` - Safety boundaries -- `mavros_params.yaml` - MAVROS connection - -### Runtime Parameter Changes -```bash -ros2 param set /uav/visual_odom_node max_features 500 -``` +| Mode | Description | +|------|-------------| +| STABILIZE | Manual control with attitude stabilization | +| ALT_HOLD | Maintain altitude, manual position | +| LOITER | Hold position and altitude | +| GUIDED | Accept position commands | +| AUTO | Follow pre-planned mission | +| RTL | Return to launch point | +| LAND | Controlled descent and landing | ## Stopping the Simulation -```bash -# Graceful shutdown -Ctrl+C +Press `Ctrl+C` in the terminal running the simulation. -# Force kill all processes +Or run: +```bash bash scripts/kill_simulation.sh ``` +## Camera Topics + +The UAV has two cameras: + +```bash +# Forward camera (visual odometry) +ros2 topic echo /uav/camera/forward/image_raw + +# Downward camera (optical flow) +ros2 topic echo /uav/camera/downward/image_raw +``` + +## GPS-Denied Navigation + +All position commands use local coordinates (meters from takeoff point): +- X: North +- Y: East +- Z: Up (or Down for NED frame) + +GPS is only used for geofencing boundaries, not for navigation. diff --git a/docs/wsl_setup_guide.md b/docs/wsl_setup_guide.md index a2e7280..8f0c05e 100644 --- a/docs/wsl_setup_guide.md +++ b/docs/wsl_setup_guide.md @@ -1,660 +1,129 @@ -# WSL Setup Guide for UAV-UGV Simulation +# WSL Setup Guide -This guide walks you through setting up the GPS-denied UAV-UGV simulation on **Windows Subsystem for Linux (WSL)**. - ---- +Setup guide for Windows Subsystem for Linux (WSL2). ## Prerequisites -- Windows 10 version 2004+ (Build 19041+) or Windows 11 -- Administrator access to Windows -- At least 16GB RAM (8GB minimum) -- 50GB free disk space -- NVIDIA GPU (optional, for hardware acceleration) +- Windows 10 (version 21H2+) or Windows 11 +- WSL2 with Ubuntu 22.04 ---- +### Install WSL2 -## Part 1: Install WSL2 with Ubuntu 22.04 - -### Step 1.1: Enable WSL - -Open **PowerShell as Administrator** and run: +Open PowerShell as Administrator: ```powershell -# Enable WSL and Virtual Machine Platform -wsl --install - -# Or if already installed, update to WSL2 -wsl --set-default-version 2 -``` - -**Restart your computer** after this step. - -### Step 1.2: Install Ubuntu 22.04 - -```powershell -# List available distributions -wsl --list --online - -# Install Ubuntu 22.04 wsl --install -d Ubuntu-22.04 ``` -When prompted, create a username and password for your Ubuntu installation. +Restart your computer, then open Ubuntu from the Start menu. -### Step 1.3: Verify WSL2 +## GUI Support -```powershell -wsl --list --verbose -``` +### Windows 11 (WSLg) -You should see Ubuntu-22.04 with VERSION 2: +GUI works automatically. No additional setup needed. -``` - NAME STATE VERSION -* Ubuntu-22.04 Running 2 -``` - -If it shows VERSION 1, upgrade it: - -```powershell -wsl --set-version Ubuntu-22.04 2 -``` - -### Step 1.4: Configure WSL Memory - -Create or edit `%USERPROFILE%\.wslconfig` (Windows path: `C:\Users\YourName\.wslconfig`): - -```ini -[wsl2] -# Allocate memory (adjust based on your system) -memory=8GB -processors=4 - -# Swap file -swap=4GB - -# Enable systemd (required for ROS 2) -[boot] -systemd=true -``` - -**Restart WSL** after creating this file: - -```powershell -wsl --shutdown -``` - ---- - -## Part 2: Setup GUI Support for Gazebo - -WSL2 supports GUI applications through **WSLg** (Windows 11) or **X11 forwarding** (Windows 10). - -### Option A: WSLg (Windows 11 - Recommended) - -**WSLg is built-in to Windows 11.** No additional setup needed! GUI apps work out of the box. - -Verify WSLg is working: - -```bash -# Inside WSL Ubuntu -sudo apt update -sudo apt install -y x11-apps -xcalc # Should open a calculator window -``` - -### Option B: X11 Server (Windows 10) - -#### Install VcXsrv +### Windows 10 (VcXsrv) 1. Download and install [VcXsrv](https://sourceforge.net/projects/vcxsrv/) -2. Launch **XLaunch** with these settings: - - Display: Multiple windows +2. Run XLaunch with these settings: + - Multiple windows - Start no client - - **Check**: Disable access control - - Save configuration for future use - -#### Configure WSL to use X Server - -Add to `~/.bashrc` in WSL: - -```bash -# X11 forwarding for WSL1/WSL2 (Windows 10) -export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0 -export LIBGL_ALWAYS_INDIRECT=1 -``` - -Apply changes: - -```bash -source ~/.bashrc -``` - -Test X11: - -```bash -sudo apt install -y x11-apps -xcalc # Should open a calculator -``` - ---- - -## Part 3: Install ROS 2 Humble - -### Step 3.1: Setup ROS 2 Repository - -```bash -# Update system -sudo apt update && sudo apt upgrade -y - -# Install prerequisites -sudo apt install -y software-properties-common -sudo add-apt-repository universe - -# Add ROS 2 GPG key -sudo apt install -y curl gnupg lsb-release -sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \ - -o /usr/share/keyrings/ros-archive-keyring.gpg - -# Add repository -echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] \ - http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | \ - sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null -``` - -### Step 3.2: Install ROS 2 Humble - -```bash -# Update package list -sudo apt update - -# Install ROS 2 Desktop (includes RViz, demos, tutorials) -sudo apt install -y ros-humble-desktop - -# Install development tools -sudo apt install -y \ - ros-dev-tools \ - python3-colcon-common-extensions \ - python3-rosdep -``` - -### Step 3.3: Initialize rosdep - -```bash -sudo rosdep init -rosdep update -``` - -### Step 3.4: Setup Environment - -Add to `~/.bashrc`: - -```bash -# ROS 2 Humble -source /opt/ros/humble/setup.bash - -# Optional: Auto-source workspace -if [ -f ~/ros2_ws/install/setup.bash ]; then - source ~/ros2_ws/install/setup.bash -fi -``` - -Apply changes: - -```bash -source ~/.bashrc -``` - -### Step 3.5: Verify ROS 2 - -```bash -ros2 --version -# Should output: ros2 cli version: 0.x.x - -# Test with a demo (optional) -ros2 run demo_nodes_cpp talker -# Press Ctrl+C to stop -``` - ---- - -## Part 4: Install Gazebo Classic 11 - -```bash -# Install Gazebo Classic -sudo apt install -y gazebo11 libgazebo11-dev - -# Install ROS 2 Gazebo packages -sudo apt install -y \ - ros-humble-gazebo-ros-pkgs \ - ros-humble-gazebo-plugins -``` - -### Test Gazebo - -```bash -gazebo --verbose -``` - -A Gazebo window should open. **Note**: First launch may be slow. - -**Common Issues:** - -- **Black screen**: Wait 30-60 seconds for Gazebo to fully initialize -- **Slow performance**: Use software rendering (see below) -- **Crashes**: Check GPU drivers and memory allocation in `.wslconfig` - -### Performance Tweaks - -If Gazebo is slow, force software rendering: - -```bash -export LIBGL_ALWAYS_SOFTWARE=1 -gazebo -``` - -Add to `~/.bashrc` to make permanent: - -```bash -echo "export LIBGL_ALWAYS_SOFTWARE=1" >> ~/.bashrc -``` - ---- - -## Part 5: Install ArduPilot SITL - -### Step 5.1: Install Dependencies - -```bash -sudo apt install -y \ - git \ - gitk \ - git-gui \ - python3-dev \ - python3-opencv \ - python3-wxgtk4.0 \ - python3-pip \ - python3-matplotlib \ - python3-lxml \ - python3-pygame \ - libxml2-dev \ - libxslt1-dev \ - python3-scipy -``` - -### Step 5.2: Clone ArduPilot - -```bash -cd ~ -git clone https://github.com/ArduPilot/ardupilot.git -cd ardupilot -git submodule update --init --recursive -``` - -### Step 5.3: Install ArduPilot Prerequisites - -```bash -cd ~/ardupilot -Tools/environment_install/install-prereqs-ubuntu.sh -y -``` - -**Reload your shell:** - -```bash -. ~/.profile -``` - -### Step 5.4: Build ArduCopter SITL - -```bash -cd ~/ardupilot -./waf configure --board sitl -./waf copter -``` - -### Step 5.5: Test ArduPilot SITL - -```bash -cd ~/ardupilot/ArduCopter -sim_vehicle.py --console --map -``` - -You should see MAVProxy console and a map window. Press Ctrl+C to exit. - ---- - -## Part 6: Install ardupilot_gazebo Plugin - -```bash -# Clone the plugin -cd ~ -git clone https://github.com/ArduPilot/ardupilot_gazebo.git -cd ardupilot_gazebo - -# Build -mkdir build && cd build -cmake .. -make -j4 -sudo make install -``` - -### Configure Gazebo Paths - -Add to `~/.bashrc`: - -```bash -# ArduPilot Gazebo -export GAZEBO_MODEL_PATH=$HOME/ardupilot_gazebo/models:$GAZEBO_MODEL_PATH -export GAZEBO_RESOURCE_PATH=$HOME/ardupilot_gazebo/worlds:$GAZEBO_RESOURCE_PATH -``` - -Apply changes: - -```bash -source ~/.bashrc -``` - ---- - -## Part 7: Install MAVROS - -```bash -sudo apt install -y \ - ros-humble-mavros \ - ros-humble-mavros-extras -``` - -### Install GeographicLib Datasets - -```bash -sudo /opt/ros/humble/lib/mavros/install_geographiclib_datasets.sh -``` - ---- - -## Part 8: Setup UAV-UGV Simulation Project - -### Step 8.1: Create ROS 2 Workspace - -```bash -mkdir -p ~/ros2_ws/src -cd ~/ros2_ws/src -``` - -### Step 8.2: Clone Project - -```bash -# Replace with your repository URL -git clone https://git.sirblob.co/SirBlob/simulation.git uav_ugv_simulation -cd uav_ugv_simulation -``` - -### Step 8.3: Install Python Dependencies - -```bash -# Install system Python packages -sudo apt install -y \ - python3-pip \ - python3-venv \ - python3-opencv \ - libopencv-dev - -# Install additional ROS packages -sudo apt install -y \ - ros-humble-cv-bridge \ - ros-humble-image-transport \ - ros-humble-tf2 \ - ros-humble-tf2-ros \ - ros-humble-tf2-geometry-msgs - -# Create virtual environment -python3 -m venv venv -source venv/bin/activate - -# Install Python packages -pip install --upgrade pip -pip install -r requirements.txt -``` - -### Step 8.4: Build ROS Package - -```bash -cd ~/ros2_ws -colcon build --packages-select uav_ugv_simulation --symlink-install -source install/setup.bash -``` - -### Step 8.5: Make Scripts Executable - -```bash -cd ~/ros2_ws/src/uav_ugv_simulation -chmod +x scripts/*.sh -chmod +x setup.sh -chmod +x activate_venv.sh -``` - ---- - -## Part 9: Test the Installation - -### Test 1: Gazebo - -```bash -gazebo --verbose -``` - -### Test 2: ROS 2 - -```bash -ros2 topic list -``` - -### Test 3: ArduPilot SITL - -```bash -cd ~/ardupilot/ArduCopter -sim_vehicle.py -v ArduCopter -f gazebo-iris --console --map -``` - -### Test 4: Complete Simulation (Final Test) - -**Terminal 1 - Gazebo:** -```bash -cd ~/ros2_ws/src/uav_ugv_simulation -source activate_venv.sh -gazebo --verbose worlds/empty_custom.world -``` - -**Terminal 2 - ArduPilot:** -```bash -cd ~/ardupilot/ArduCopter -sim_vehicle.py -v ArduCopter -f gazebo-iris --console --map -I0 -``` - -**Terminal 3 - MAVROS & Nodes:** -```bash -cd ~/ros2_ws/src/uav_ugv_simulation -source activate_venv.sh -ros2 launch uav_ugv_simulation uav_only.launch.py -``` - ---- - -## WSL-Specific Issues & Solutions - -### Issue 1: "Cannot open display" - -**Solution:** - -Windows 10: + - Disable access control (checked) +3. In WSL, set DISPLAY: ```bash export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0 ``` -Windows 11 (WSLg): +## Installation + ```bash -export DISPLAY=:0 +git clone https://git.sirblob.co/SirBlob/simulation.git +cd simulation +bash setup.sh ``` -### Issue 2: Gazebo Black Screen +The setup script automatically: +- Detects WSL environment +- Installs GUI support packages +- Creates WSL environment file +- Configures DISPLAY variable -**Solutions:** - -1. Wait 30-60 seconds for initialization -2. Use software rendering: - ```bash - export LIBGL_ALWAYS_SOFTWARE=1 - ``` -3. Increase WSL memory in `.wslconfig` - -### Issue 3: GPU Acceleration Not Working - -**For NVIDIA GPUs in WSL2:** - -1. Install NVIDIA drivers on **Windows** (not in WSL) -2. Install CUDA in WSL: - ```bash - sudo apt install -y nvidia-cuda-toolkit - ``` -3. Verify: - ```bash - nvidia-smi - ``` - -### Issue 4: "Permission denied" on Serial Ports +## Running the Simulation ```bash -sudo usermod -aG dialout $USER -# Logout and login again -``` - -### Issue 5: Slow Performance - -1. Increase memory in `.wslconfig` -2. Close unnecessary Windows applications -3. Use software rendering for Gazebo -4. Reduce Gazebo real-time factor: - ```bash - gazebo --verbose -u # Start paused - ``` - -### Issue 6: Network Issues (MAVROS connection) - -Ensure localhost is working: - -```bash -# Test connection -nc -zv 127.0.0.1 14550 - -# If fails, check WSL networking -cat /etc/resolv.conf -``` - ---- - -## Quick Start After Installation - -```bash -# 1. Navigate to project -cd ~/ros2_ws/src/uav_ugv_simulation - -# 2. Activate environment +cd ~/simulation source activate_venv.sh - -# 3. Run simulation bash scripts/run_simulation.sh ``` ---- +If graphics are slow or Gazebo crashes: +```bash +bash scripts/run_simulation.sh --software-render +``` -## Performance Optimization for WSL +## Troubleshooting -### 1. Increase WSL Resources +### Black screen or no display -Edit `C:\Users\YourName\.wslconfig`: +Check DISPLAY variable: +```bash +echo $DISPLAY +``` +For WSLg (Windows 11), should be `:0` +For VcXsrv (Windows 10), should be `:0` + +Test with: +```bash +xcalc +``` + +### Gazebo crashes immediately + +Use software rendering: +```bash +export LIBGL_ALWAYS_SOFTWARE=1 +bash scripts/run_simulation.sh +``` + +### OpenGL errors + +```bash +export MESA_GL_VERSION_OVERRIDE=3.3 +export MESA_GLSL_VERSION_OVERRIDE=330 +``` + +### VcXsrv connection refused + +1. Check Windows Firewall allows VcXsrv +2. Ensure XLaunch is running +3. Disable access control in XLaunch settings + +### Slow performance + +- Close unnecessary Windows applications +- Allocate more RAM to WSL in `.wslconfig`: ```ini [wsl2] -memory=12GB -processors=6 -swap=8GB -localhostForwarding=true +memory=8GB +processors=4 ``` -### 2. Enable Systemd +- Use software rendering flag -In `.wslconfig`: +## Environment Variables -```ini -[boot] -systemd=true +The `activate_venv.sh` script sets these automatically: + +```bash +export DISPLAY=:0 # or IP:0 for VcXsrv +export LIBGL_ALWAYS_INDIRECT=0 +export MESA_GL_VERSION_OVERRIDE=3.3 ``` -### 3. Disable Windows Defender for WSL +## Uninstall -Add exclusion in Windows Security: -- Path: `C:\Users\YourName\AppData\Local\Packages\CanonicalGroupLimited*` - -### 4. Use Fast SSD - -Move WSL to SSD if on HDD: - -```powershell -wsl --export Ubuntu-22.04 ubuntu-backup.tar -wsl --unregister Ubuntu-22.04 -wsl --import Ubuntu-22.04 D:\WSL\Ubuntu ubuntu-backup.tar +```bash +bash scripts/uninstall.sh --all ``` - ---- - -## Useful WSL Commands - -```powershell -# List WSL distributions -wsl --list --verbose - -# Shutdown WSL (free resources) -wsl --shutdown - -# Access WSL files from Windows -\\wsl$\Ubuntu-22.04\home\youruser - -# Run Linux command from Windows -wsl ls -la - -# Set default WSL distribution -wsl --set-default Ubuntu-22.04 -``` - ---- - -## Troubleshooting Resources - -- **WSL Issues**: https://github.com/microsoft/WSL/issues -- **Gazebo WSL**: https://classic.gazebosim.org/tutorials?tut=wsl -- **ROS 2 WSL**: https://docs.ros.org/en/humble/How-To-Guides/Installing-on-Raspberry-Pi.html -- **ArduPilot Forums**: https://discuss.ardupilot.org/ - ---- - -## Next Steps - -After successful installation: - -1. Read the [Usage Guide](usage.md) -2. Understand [GPS-Denied Navigation](gps_denied_navigation.md) -3. Review [Architecture](architecture.md) -4. Try example missions in `docs/usage.md` - ---- - -## Known Limitations in WSL - -1. **Performance**: ~70% of native Linux performance -2. **GPU**: Limited DirectX translation in WSLg -3. **Real-time**: WSL2 is not real-time capable -4. **USB**: Direct USB forwarding requires usbipd-win -5. **GUI**: Some OpenGL features may not work perfectly - -For production work, consider **dual-boot Ubuntu 22.04** or a **native Linux installation**. diff --git a/scripts/run_simulation.sh b/scripts/run_simulation.sh index 72b3191..5402e4d 100755 --- a/scripts/run_simulation.sh +++ b/scripts/run_simulation.sh @@ -200,7 +200,7 @@ echo -e "${GREEN}Gazebo running (PID: $GZ_PID)${NC}" echo -e "${GREEN}Starting ArduPilot SITL...${NC}" cd "$ARDUPILOT_HOME" -export PATH=$PATH:$ARDUPILOT_HOME/Tools/autotest:$HOME/.local/bin +export PATH=$PATH:$ARDUPILOT_HOME/Tools/autotest:$HOME/.local/bin:$HOME/.local/pipx/venvs/mavproxy/bin sim_vehicle.py \ -v $VEHICLE \ diff --git a/scripts/uninstall.sh b/scripts/uninstall.sh new file mode 100755 index 0000000..fa35139 --- /dev/null +++ b/scripts/uninstall.sh @@ -0,0 +1,150 @@ +#!/bin/bash +# ============================================================================= +# UAV-UGV Simulation - Uninstall Script +# ============================================================================= +# Removes ArduPilot, ardupilot_gazebo, and project files +# Does NOT remove ROS 2 or Gazebo (system packages) +# +# Usage: +# ./scripts/uninstall.sh # Remove ArduPilot and plugin only +# ./scripts/uninstall.sh --all # Remove everything including project +# ============================================================================= + +set -e + +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_DIR="$(dirname "$SCRIPT_DIR")" + +ARDUPILOT_HOME="$HOME/ardupilot" +ARDUPILOT_GZ="$HOME/ardupilot_gazebo" + +echo -e "${BLUE}==========================================${NC}" +echo -e "${BLUE} UAV-UGV Simulation - Uninstall${NC}" +echo -e "${BLUE}==========================================${NC}" +echo "" + +# Parse arguments +REMOVE_ALL=false +FORCE=false + +for arg in "$@"; do + case $arg in + --all) + REMOVE_ALL=true + ;; + --force|-f) + FORCE=true + ;; + --help) + echo "Usage: $0 [OPTIONS]" + echo "" + echo "Options:" + echo " --all Remove everything (ArduPilot, plugin, project, venv)" + echo " --force Skip confirmation prompts" + echo " --help Show this help" + echo "" + echo "Note: ROS 2 and Gazebo are NOT removed (use apt to remove)" + exit 0 + ;; + esac +done + +# Confirmation +if [ "$FORCE" = false ]; then + echo "This will remove:" + echo " - ArduPilot SITL ($ARDUPILOT_HOME)" + echo " - ardupilot_gazebo ($ARDUPILOT_GZ)" + echo " - Python virtual environment ($PROJECT_DIR/venv)" + if [ "$REMOVE_ALL" = true ]; then + echo " - Project directory ($PROJECT_DIR)" + fi + echo "" + echo "ROS 2 and Gazebo will NOT be removed." + echo "" + read -p "Continue? (y/N): " confirm + if [[ ! "$confirm" =~ ^[Yy]$ ]]; then + echo "Cancelled." + exit 0 + fi +fi + +echo "" + +# Kill running processes +echo -e "${YELLOW}Stopping running processes...${NC}" +pkill -f "sim_vehicle.py" 2>/dev/null || true +pkill -f "mavproxy" 2>/dev/null || true +pkill -f "arducopter" 2>/dev/null || true +pkill -f "ardurover" 2>/dev/null || true +pkill -f "gz sim" 2>/dev/null || true +pkill -f "gzserver" 2>/dev/null || true +pkill -f "gzclient" 2>/dev/null || true +sleep 1 + +# Remove ArduPilot +if [ -d "$ARDUPILOT_HOME" ]; then + echo -e "${YELLOW}Removing ArduPilot ($ARDUPILOT_HOME)...${NC}" + rm -rf "$ARDUPILOT_HOME" + echo -e "${GREEN}Removed ArduPilot${NC}" +else + echo "ArduPilot not found at $ARDUPILOT_HOME" +fi + +# Remove ardupilot_gazebo +if [ -d "$ARDUPILOT_GZ" ]; then + echo -e "${YELLOW}Removing ardupilot_gazebo ($ARDUPILOT_GZ)...${NC}" + rm -rf "$ARDUPILOT_GZ" + echo -e "${GREEN}Removed ardupilot_gazebo${NC}" +else + echo "ardupilot_gazebo not found at $ARDUPILOT_GZ" +fi + +# Remove Python venv +if [ -d "$PROJECT_DIR/venv" ]; then + echo -e "${YELLOW}Removing Python virtual environment...${NC}" + rm -rf "$PROJECT_DIR/venv" + echo -e "${GREEN}Removed venv${NC}" +fi + +# Remove generated files +rm -f "$PROJECT_DIR/activate_venv.sh" 2>/dev/null || true +rm -f "$PROJECT_DIR/wsl_env.sh" 2>/dev/null || true + +# Remove ArduPilot environment files +rm -f "$HOME/.ardupilot_env" 2>/dev/null || true + +# Remove pip user packages +echo -e "${YELLOW}Removing user pip packages (mavproxy, pymavlink)...${NC}" +pip3 uninstall -y mavproxy pymavlink pexpect 2>/dev/null || true + +# Remove project directory if --all +if [ "$REMOVE_ALL" = true ]; then + echo -e "${YELLOW}Removing project directory ($PROJECT_DIR)...${NC}" + cd "$HOME" + rm -rf "$PROJECT_DIR" + echo -e "${GREEN}Removed project directory${NC}" +fi + +echo "" +echo -e "${GREEN}==========================================${NC}" +echo -e "${GREEN} Uninstall Complete${NC}" +echo -e "${GREEN}==========================================${NC}" +echo "" +echo "Removed:" +echo " - ArduPilot SITL" +echo " - ardupilot_gazebo plugin" +echo " - Python virtual environment" +if [ "$REMOVE_ALL" = true ]; then + echo " - Project directory" +fi +echo "" +echo "NOT removed (use apt if needed):" +echo " - ROS 2: sudo apt remove ros-*" +echo " - Gazebo: sudo apt remove gz-*" +echo "" diff --git a/setup.sh b/setup.sh index 45554ce..9afd255 100755 --- a/setup.sh +++ b/setup.sh @@ -140,12 +140,15 @@ sudo apt-get install -y \ python3-dev \ python3-pip \ python3-venv \ + python3-full \ + python3-pexpect \ python3-opencv \ python3-matplotlib \ python3-lxml \ python3-yaml \ python3-scipy \ python3-future \ + pipx \ libopencv-dev \ libxml2-dev \ libxslt1-dev \ @@ -445,8 +448,14 @@ if [ "$INSTALL_ARDUPILOT" = true ]; then print_info "ArduPilot Gazebo plugin built" - # Install MAVProxy - pip3 install --user pymavlink mavproxy pexpect + # Install MAVProxy using pipx (required for Ubuntu 23.04+ PEP 668) + print_info "Installing MAVProxy..." + pipx install MAVProxy --include-deps || { + # Fallback: try pip with --break-system-packages + pip3 install --user --break-system-packages pymavlink mavproxy 2>/dev/null || \ + pip3 install --user pymavlink mavproxy 2>/dev/null || \ + print_warning "MAVProxy installation failed - install manually" + } ((STEP++)) # ========================================================================