simulation/docs/wsl_setup_guide.md

WSL Setup Guide

Overview

This guide covers running the UAV-UGV simulation on Windows Subsystem for Linux (WSL2).

Requirements

• Windows 10 (21H2+) or Windows 11
• WSL2 with Ubuntu 22.04
• 16GB RAM minimum
• Optional: NVIDIA GPU with WSL drivers
• ffmpeg, x11-utils, xdotool (installed via setup.sh or apt)

WSL2 Installation

1. Enable WSL2

Open PowerShell as Administrator:

wsl --install

2. Install Ubuntu

wsl --install -d Ubuntu-22.04

3. Set WSL2 as Default

wsl --set-default-version 2

Graphics Setup

Option A: WSLg (Windows 11 - Recommended)

WSLg is built into Windows 11 and works automatically.

Verify:

echo $DISPLAY
# Should show something like :0

Option B: VcXsrv (Windows 10)

1. Download VcXsrv: https://sourceforge.net/projects/vcxsrv/
2. Launch with "Disable access control" checked
3. In WSL:

export DISPLAY=$(grep nameserver /etc/resolv.conf | awk '{print $2}'):0
echo "export DISPLAY=$(grep nameserver /etc/resolv.conf | awk '{print $2}'):0" >> ~/.bashrc

GPU Support

NVIDIA GPU (Optional)

1. Install NVIDIA drivers for WSL: https://developer.nvidia.com/cuda/wsl
2. Verify in WSL:

nvidia-smi

If working, you can use hardware acceleration.

Software Rendering (No GPU)

Most reliable for WSL:

export LIBGL_ALWAYS_SOFTWARE=1
export GALLIUM_DRIVER=llvmpipe

Installation

Same as native Ubuntu:

cd ~/sim/uav_ugv_simulation
bash setup.sh

Running Simulation

Always use software rendering on WSL:

source activate_venv.sh
bash scripts/run_autonomous.sh --software-render --search spiral

Performance Tips

1. Allocate More Memory

Create/edit %USERPROFILE%\.wslconfig:

[wsl2]
memory=12GB
processors=4
swap=8GB

Restart WSL:

wsl --shutdown

2. Use Fast Storage

Run simulation from Windows filesystem only if needed:

# Faster (Linux filesystem)
cd ~/sim/uav_ugv_simulation

# Slower (Windows filesystem)
cd /mnt/c/Projects/simulation

3. Disable Unnecessary Visuals

In software rendering mode, Gazebo is slower. Consider:

• Running headless: --headless flag
• Reducing physics rate
• Simpler world files

Troubleshooting

"cannot open display"

# For WSLg
export DISPLAY=:0

# For VcXsrv
export DISPLAY=$(grep nameserver /etc/resolv.conf | awk '{print $2}'):0

Graphics freeze/crash

# Always use software rendering
export LIBGL_ALWAYS_SOFTWARE=1
export GALLIUM_DRIVER=llvmpipe
bash scripts/run_autonomous.sh --software-render

Slow performance

• Increase WSL memory (see Performance Tips)
• Use software rendering
• Close other applications

Network issues

# If MAVLink connection fails
# Check Windows firewall allows WSL traffic

Quick Start Commands

# 1. Open Ubuntu terminal

# 2. Navigate to project
cd ~/sim/uav_ugv_simulation

# 3. Activate environment
source activate_venv.sh

# 4. Run with software rendering
bash scripts/run_autonomous.sh --software-render --search spiral

Related

• Setup Guide
• Troubleshooting