simulation/docs/wsl_setup_guide.md

# WSL Setup Guide for UAV-UGV Simulation

This guide walks you through setting up the GPS-denied UAV-UGV simulation on **Windows Subsystem for Linux (WSL)**.

---

## 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)

---

## Part 1: Install WSL2 with Ubuntu 22.04

### Step 1.1: Enable WSL

Open **PowerShell as Administrator** and run:

```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.

### Step 1.3: Verify WSL2

```powershell
wsl --list --verbose
```

You should see Ubuntu-22.04 with VERSION 2:

```
  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

1. Download and install [VcXsrv](https://sourceforge.net/projects/vcxsrv/)
2. Launch **XLaunch** with these settings:
   - Display: 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:
```bash
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
```

Windows 11 (WSLg):
```bash
export DISPLAY=:0
```

### Issue 2: Gazebo Black Screen

**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

```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
source activate_venv.sh

# 3. Run simulation
bash scripts/run_simulation.sh
```

---

## Performance Optimization for WSL

### 1. Increase WSL Resources

Edit `C:\Users\YourName\.wslconfig`:

```ini
[wsl2]
memory=12GB
processors=6
swap=8GB
localhostForwarding=true
```

### 2. Enable Systemd

In `.wslconfig`:

```ini
[boot]
systemd=true
```

### 3. Disable Windows Defender for WSL

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
```

---

## 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**.