WSL Support
This commit is contained in:
@@ -1,275 +1,369 @@
|
||||
# Installation Guide
|
||||
|
||||
This guide covers installation on Ubuntu, macOS, and Windows.
|
||||
Setup instructions for all supported platforms.
|
||||
|
||||
## Quick Install
|
||||
|
||||
### Ubuntu / Debian
|
||||
| Platform | Command |
|
||||
|----------|---------|
|
||||
| Ubuntu/Debian | `./setup/install_ubuntu.sh` |
|
||||
| Arch Linux | `./setup/install_arch.sh` |
|
||||
| macOS | `./setup/install_macos.sh` |
|
||||
| Windows | `.\setup\install_windows.ps1` |
|
||||
|
||||
After installation:
|
||||
```bash
|
||||
cd simulation
|
||||
chmod +x setup/install_ubuntu.sh
|
||||
./setup/install_ubuntu.sh
|
||||
source activate.sh
|
||||
```
|
||||
source activate.sh # Linux/macOS
|
||||
. .\activate.ps1 # Windows PowerShell
|
||||
|
||||
### macOS
|
||||
|
||||
```bash
|
||||
cd simulation
|
||||
chmod +x setup/install_macos.sh
|
||||
./setup/install_macos.sh
|
||||
source activate.sh
|
||||
```
|
||||
|
||||
### Windows (PowerShell)
|
||||
|
||||
```powershell
|
||||
cd simulation
|
||||
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
.\setup\install_windows.ps1
|
||||
.\activate.bat
|
||||
python standalone_simulation.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What Gets Installed
|
||||
## Platform Compatibility
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| **ROS 2** | Humble (Ubuntu 22.04) or Jazzy (Ubuntu 24.04) |
|
||||
| **Gazebo** | Modern Ignition-based simulator |
|
||||
| **Python venv** | Virtual environment with system site-packages |
|
||||
| **PyBullet** | Lightweight physics engine |
|
||||
| **PyInstaller** | Executable bundler |
|
||||
| **ros_gz_bridge** | ROS 2 ↔ Gazebo topic bridge |
|
||||
| Feature | Ubuntu | Arch | macOS | Windows | WSL2 |
|
||||
|---------|--------|------|-------|---------|------|
|
||||
| **Standalone Simulation** | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| **ROS 2** | ✅ | ⚠️ AUR | ❌ | ❌ | ✅ |
|
||||
| **Gazebo** | ✅ | ⚠️ AUR | ❌ | ❌ | ✅ |
|
||||
| **Full Mode** | ✅ | ⚠️ | ❌ | ❌ | ✅ |
|
||||
| **GUI Support** | ✅ | ✅ | ✅ | ✅ | ✅ WSLg |
|
||||
|
||||
**Legend:**
|
||||
- ✅ Fully supported
|
||||
- ⚠️ Available but requires extra setup
|
||||
- ❌ Not supported
|
||||
|
||||
**Recommendation for Windows users:** Use WSL2 for the full experience (ROS 2 + Gazebo).
|
||||
|
||||
---
|
||||
|
||||
## Ubuntu / Debian
|
||||
|
||||
**Tested on:** Ubuntu 22.04 (Jammy), Ubuntu 24.04 (Noble)
|
||||
|
||||
```bash
|
||||
# Run installer
|
||||
./setup/install_ubuntu.sh
|
||||
|
||||
# Activate environment
|
||||
source activate.sh
|
||||
|
||||
# Run simulation
|
||||
python standalone_simulation.py
|
||||
```
|
||||
|
||||
**Installs:**
|
||||
- ROS 2 (Humble or Jazzy based on Ubuntu version)
|
||||
- Gazebo (ros-gz)
|
||||
- Python packages: pybullet, numpy, pillow, pyinstaller
|
||||
|
||||
---
|
||||
|
||||
## Arch Linux
|
||||
|
||||
**Tested on:** Arch Linux (rolling release)
|
||||
|
||||
```bash
|
||||
# Run installer
|
||||
./setup/install_arch.sh
|
||||
|
||||
# Activate environment
|
||||
source activate.sh
|
||||
|
||||
# Run simulation
|
||||
python standalone_simulation.py
|
||||
```
|
||||
|
||||
**Installs:**
|
||||
- Python packages: pybullet, numpy, pillow, pyinstaller
|
||||
- yay (AUR helper)
|
||||
|
||||
**Optional ROS 2 (from AUR):**
|
||||
```bash
|
||||
yay -S ros-humble-desktop
|
||||
yay -S ros-humble-ros-gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## macOS
|
||||
|
||||
**Tested on:** macOS 12+ (Monterey, Ventura, Sonoma)
|
||||
|
||||
```bash
|
||||
# Run installer
|
||||
./setup/install_macos.sh
|
||||
|
||||
# Activate environment
|
||||
source activate.sh
|
||||
|
||||
# Run simulation
|
||||
python standalone_simulation.py
|
||||
```
|
||||
|
||||
**Installs:**
|
||||
- Homebrew (if not present)
|
||||
- Python 3.11
|
||||
- Python packages: pybullet, numpy, pillow, pyinstaller
|
||||
|
||||
**Note:** ROS 2 and Gazebo are not supported on macOS. Use standalone mode.
|
||||
|
||||
---
|
||||
|
||||
## Windows
|
||||
|
||||
**Tested on:** Windows 10, Windows 11
|
||||
|
||||
```powershell
|
||||
# Open PowerShell as Administrator
|
||||
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
|
||||
# Run installer
|
||||
.\setup\install_windows.ps1
|
||||
|
||||
# Activate environment
|
||||
. .\activate.ps1
|
||||
|
||||
# Run simulation
|
||||
python standalone_simulation.py
|
||||
```
|
||||
|
||||
**Installs:**
|
||||
- Chocolatey (package manager)
|
||||
- Python 3.11
|
||||
- Python packages: pybullet, numpy, pillow, pyinstaller
|
||||
|
||||
**Note:** ROS 2 and Gazebo are not supported natively on Windows. Use standalone mode or WSL2 (below).
|
||||
|
||||
---
|
||||
|
||||
## Windows with WSL2 (Full Linux Experience)
|
||||
|
||||
WSL2 lets you run full Linux on Windows with GUI support. This enables ROS 2 and Gazebo!
|
||||
|
||||
**Requirements:** Windows 10 (build 19041+) or Windows 11
|
||||
|
||||
### Step 1: Install WSL2
|
||||
|
||||
Open PowerShell as Administrator:
|
||||
|
||||
```powershell
|
||||
# Install WSL2 with Ubuntu
|
||||
wsl --install -d Ubuntu-22.04
|
||||
|
||||
# Restart computer when prompted
|
||||
```
|
||||
|
||||
### Step 2: Enable GUI Support (WSLg)
|
||||
|
||||
Windows 11 and recent Windows 10 updates include WSLg (GUI support) automatically.
|
||||
|
||||
Verify by opening Ubuntu and running:
|
||||
```bash
|
||||
# Test GUI (should open a window)
|
||||
sudo apt update
|
||||
sudo apt install x11-apps -y
|
||||
xclock
|
||||
```
|
||||
|
||||
If xclock appears, GUI is working!
|
||||
|
||||
### Step 3: Install Simulation in WSL
|
||||
|
||||
Open Ubuntu from Start menu:
|
||||
|
||||
```bash
|
||||
# Clone or copy your project
|
||||
cd ~
|
||||
git clone <your-repo-url> simulation
|
||||
# OR copy from Windows:
|
||||
# cp -r /mnt/c/Users/YourName/simulation ~/simulation
|
||||
|
||||
cd simulation
|
||||
|
||||
# Run Ubuntu installer
|
||||
./setup/install_ubuntu.sh
|
||||
|
||||
# Activate
|
||||
source activate.sh
|
||||
|
||||
# Run with GUI
|
||||
python standalone_simulation.py
|
||||
```
|
||||
|
||||
### WSL2 Tips
|
||||
|
||||
**Access Windows files:**
|
||||
```bash
|
||||
# Windows C: drive is at /mnt/c/
|
||||
cd /mnt/c/Users/YourName/Documents
|
||||
```
|
||||
|
||||
**Run from Windows Terminal:**
|
||||
```powershell
|
||||
wsl -d Ubuntu-22.04 -e bash -c "cd ~/simulation && source activate.sh && python standalone_simulation.py"
|
||||
```
|
||||
|
||||
**GPU Acceleration (NVIDIA):**
|
||||
|
||||
If you have an NVIDIA GPU:
|
||||
```bash
|
||||
# Check if GPU is available
|
||||
nvidia-smi
|
||||
|
||||
# PyBullet will use hardware rendering automatically
|
||||
```
|
||||
|
||||
**Troubleshooting WSL GUI:**
|
||||
|
||||
If GUI doesn't work:
|
||||
```bash
|
||||
# Update WSL
|
||||
wsl --update
|
||||
|
||||
# Set WSL2 as default
|
||||
wsl --set-default-version 2
|
||||
|
||||
# Reinstall Ubuntu
|
||||
wsl --unregister Ubuntu-22.04
|
||||
wsl --install -d Ubuntu-22.04
|
||||
```
|
||||
|
||||
**Using VcXsrv (older Windows 10):**
|
||||
|
||||
If WSLg isn't available:
|
||||
```powershell
|
||||
# Install VcXsrv
|
||||
choco install vcxsrv -y
|
||||
```
|
||||
|
||||
Then in WSL:
|
||||
```bash
|
||||
# Add to ~/.bashrc
|
||||
export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'):0
|
||||
export LIBGL_ALWAYS_INDIRECT=1
|
||||
|
||||
# Start VcXsrv with "Disable access control" checked
|
||||
# Then run simulation
|
||||
python standalone_simulation.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Manual Installation
|
||||
|
||||
If the scripts don't work, follow these steps manually.
|
||||
If the install scripts don't work, install manually:
|
||||
|
||||
### Step 1: Install ROS 2
|
||||
|
||||
#### Ubuntu 22.04 (Humble)
|
||||
### 1. Python 3.10+
|
||||
|
||||
```bash
|
||||
sudo apt update && sudo apt install -y locales
|
||||
sudo locale-gen en_US en_US.UTF-8
|
||||
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
|
||||
export LANG=en_US.UTF-8
|
||||
# Ubuntu/Debian
|
||||
sudo apt install python3 python3-pip python3-venv
|
||||
|
||||
sudo apt install -y software-properties-common curl
|
||||
sudo add-apt-repository -y universe
|
||||
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key \
|
||||
-o /usr/share/keyrings/ros-archive-keyring.gpg
|
||||
# Arch
|
||||
sudo pacman -S python python-pip python-virtualenv
|
||||
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(. /etc/os-release && echo $UBUNTU_CODENAME) main" \
|
||||
| sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
|
||||
# macOS
|
||||
brew install python@3.11
|
||||
|
||||
sudo apt update
|
||||
sudo apt install -y ros-humble-desktop
|
||||
# Windows
|
||||
# Download from https://python.org
|
||||
```
|
||||
|
||||
#### Ubuntu 24.04 (Jazzy)
|
||||
### 2. Create Virtual Environment
|
||||
|
||||
```bash
|
||||
# Same as above, but install ros-jazzy-desktop
|
||||
sudo apt install -y ros-jazzy-desktop
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate # Linux/macOS
|
||||
# OR
|
||||
.\venv\Scripts\Activate.ps1 # Windows
|
||||
```
|
||||
|
||||
### Step 2: Install Gazebo
|
||||
### 3. Install Python Packages
|
||||
|
||||
```bash
|
||||
# Ubuntu 22.04
|
||||
sudo apt install -y ros-humble-ros-gz ros-humble-ros-gz-bridge
|
||||
|
||||
# Ubuntu 24.04
|
||||
sudo apt install -y ros-jazzy-ros-gz ros-jazzy-ros-gz-bridge
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Step 3: Create Python Virtual Environment
|
||||
|
||||
Or manually:
|
||||
```bash
|
||||
sudo apt install -y python3-venv python3-full
|
||||
|
||||
cd /path/to/simulation
|
||||
python3 -m venv venv --system-site-packages
|
||||
source venv/bin/activate
|
||||
pip install pybullet numpy pillow pyinstaller
|
||||
```
|
||||
|
||||
### Step 4: Install Python Dependencies
|
||||
### 4. Run Simulation
|
||||
|
||||
```bash
|
||||
pip install --upgrade pip
|
||||
pip install pybullet pyinstaller
|
||||
```
|
||||
|
||||
### Step 5: Create Activation Script
|
||||
|
||||
Create `activate.sh`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
# Source ROS 2 (adjust distro as needed)
|
||||
source /opt/ros/humble/setup.bash
|
||||
echo "[OK] ROS 2 sourced"
|
||||
|
||||
# Activate venv
|
||||
source "$SCRIPT_DIR/venv/bin/activate"
|
||||
echo "[OK] Python venv activated"
|
||||
```
|
||||
|
||||
Make executable:
|
||||
|
||||
```bash
|
||||
chmod +x activate.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verifying Installation
|
||||
|
||||
After installation, verify all components:
|
||||
|
||||
```bash
|
||||
source activate.sh
|
||||
|
||||
# Check ROS 2
|
||||
ros2 --version
|
||||
|
||||
# Check PyBullet
|
||||
python3 -c "import pybullet; print('PyBullet OK')"
|
||||
|
||||
# Check rclpy
|
||||
python3 -c "import rclpy; print('rclpy OK')"
|
||||
|
||||
# Check geometry_msgs
|
||||
python3 -c "from geometry_msgs.msg import Twist; print('geometry_msgs OK')"
|
||||
|
||||
# Check Gazebo
|
||||
gz sim --version
|
||||
python standalone_simulation.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "externally-managed-environment" Error
|
||||
### PyBullet fails to install
|
||||
|
||||
This happens on modern Ubuntu/Debian due to PEP 668. Solution: use the virtual environment.
|
||||
Install build tools:
|
||||
|
||||
```bash
|
||||
source activate.sh # Activates venv
|
||||
pip install pybullet # Now works
|
||||
# Ubuntu/Debian
|
||||
sudo apt install build-essential
|
||||
|
||||
# Arch
|
||||
sudo pacman -S base-devel
|
||||
|
||||
# macOS
|
||||
xcode-select --install
|
||||
|
||||
# Windows
|
||||
# Install Visual Studio Build Tools
|
||||
```
|
||||
|
||||
### ROS 2 Packages Not Found
|
||||
### "Cannot connect to X server"
|
||||
|
||||
Ensure ROS 2 is sourced before activating venv:
|
||||
PyBullet GUI requires a display:
|
||||
|
||||
```bash
|
||||
source /opt/ros/humble/setup.bash # or jazzy
|
||||
source venv/bin/activate
|
||||
# Use virtual display
|
||||
sudo apt install xvfb
|
||||
xvfb-run python standalone_simulation.py
|
||||
|
||||
# OR use X11 forwarding
|
||||
ssh -X user@host
|
||||
```
|
||||
|
||||
The `activate.sh` script handles this automatically.
|
||||
|
||||
### Gazebo Not Starting
|
||||
|
||||
Check if Gazebo is properly installed:
|
||||
### Pillow fails to install
|
||||
|
||||
```bash
|
||||
which gz
|
||||
gz sim --version
|
||||
# Ubuntu/Debian
|
||||
sudo apt install libjpeg-dev zlib1g-dev
|
||||
|
||||
# Arch
|
||||
sudo pacman -S libjpeg-turbo zlib
|
||||
|
||||
# macOS
|
||||
brew install libjpeg zlib
|
||||
```
|
||||
|
||||
If missing, install the ROS-Gazebo packages:
|
||||
### Permission denied on Windows
|
||||
|
||||
```bash
|
||||
sudo apt install ros-humble-ros-gz # or jazzy
|
||||
```
|
||||
|
||||
### PyBullet GUI Not Showing
|
||||
|
||||
PyBullet requires a display. Options:
|
||||
|
||||
1. Run on machine with monitor
|
||||
2. Use X11 forwarding: `ssh -X user@host`
|
||||
3. Use virtual display: `xvfb-run python simulation_host.py`
|
||||
|
||||
### Permission Denied on Scripts
|
||||
|
||||
Make scripts executable:
|
||||
|
||||
```bash
|
||||
chmod +x setup/*.sh
|
||||
chmod +x activate.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Notes
|
||||
|
||||
### Ubuntu
|
||||
|
||||
- Full support for both PyBullet and Gazebo
|
||||
- ROS 2 installed via apt packages
|
||||
- Recommended platform
|
||||
|
||||
### macOS
|
||||
|
||||
- PyBullet works well
|
||||
- Gazebo support is limited
|
||||
- ROS 2 installed via Homebrew or binary
|
||||
|
||||
### Windows
|
||||
|
||||
- **PyBullet works fully** - GUI mode with camera
|
||||
- **Gazebo NOT supported** - Linux only
|
||||
- **ROS 2 optional** - Only needed for ros_bridge.py
|
||||
- Use `python simulation_host.py` directly
|
||||
|
||||
**On Windows, the recommended workflow is:**
|
||||
Run PowerShell as Administrator:
|
||||
```powershell
|
||||
. .\activate.ps1
|
||||
python simulation_host.py
|
||||
```
|
||||
|
||||
The PyBullet simulation runs standalone with full GUI - no ROS 2 or Gazebo needed.
|
||||
|
||||
---
|
||||
|
||||
## Updating
|
||||
|
||||
To update the simulation framework:
|
||||
|
||||
```bash
|
||||
cd simulation
|
||||
git pull # If using git
|
||||
|
||||
# Reinstall Python dependencies
|
||||
source activate.sh
|
||||
pip install --upgrade pybullet pyinstaller
|
||||
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Uninstalling
|
||||
## Verification
|
||||
|
||||
### Remove Virtual Environment
|
||||
After installation, verify packages:
|
||||
|
||||
```bash
|
||||
rm -rf venv/
|
||||
rm activate.sh
|
||||
python -c "import pybullet; print('PyBullet OK')"
|
||||
python -c "import numpy; print('NumPy OK')"
|
||||
python -c "from PIL import Image; print('Pillow OK')"
|
||||
```
|
||||
|
||||
### Remove ROS 2 (Ubuntu)
|
||||
|
||||
```bash
|
||||
sudo apt remove ros-humble-* # or jazzy
|
||||
sudo rm /etc/apt/sources.list.d/ros2.list
|
||||
```
|
||||
All should print "OK".
|
||||
|
||||
Reference in New Issue
Block a user