wsl guide

2026-02-09 03:43:10 +00:00
parent a756be4bf7
commit e8d83f5638
1 changed files with 660 additions and 0 deletions
--- a/docs/wsl_setup_guide.md
+++ b/docs/wsl_setup_guide.md
@@ -0,0 +1,660 @@
+# 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**.