392 lines
7.0 KiB
Markdown
392 lines
7.0 KiB
Markdown
# Installation Guide
|
|
|
|
Setup instructions for all supported platforms.
|
|
|
|
## Quick Install
|
|
|
|
| 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
|
|
source activate.sh # Linux/macOS
|
|
. .\activate.ps1 # Windows PowerShell
|
|
|
|
python standalone_simulation.py
|
|
```
|
|
|
|
---
|
|
|
|
## Platform Compatibility
|
|
|
|
| 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
|
|
|
|
# set the user name and password
|
|
# Then update the system
|
|
sudo apt update
|
|
sudo apt upgrade
|
|
|
|
# Restart computer if 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
|
|
```
|
|
|
|
**Install Gazebo (optional):**
|
|
|
|
If you want to use Gazebo simulation:
|
|
```bash
|
|
# Install ros-gz bridge
|
|
sudo apt install ros-humble-ros-gz
|
|
|
|
# Install Gazebo Fortress (provides 'ign' command)
|
|
sudo apt install gz-fortress
|
|
|
|
# Verify - one of these should work:
|
|
gz sim --version # Newer Gazebo
|
|
ign gazebo --version # Fortress (ROS 2 Humble)
|
|
```
|
|
|
|
**Note:** ROS 2 Humble uses Gazebo Fortress, which uses `ign gazebo` command instead of `gz sim`. The launch file auto-detects which command is available.
|
|
|
|
**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 install scripts don't work, install manually:
|
|
|
|
### 1. Python 3.10+
|
|
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt install python3 python3-pip python3-venv
|
|
|
|
# Arch
|
|
sudo pacman -S python python-pip python-virtualenv
|
|
|
|
# macOS
|
|
brew install python@3.11
|
|
|
|
# Windows
|
|
# Download from https://python.org
|
|
```
|
|
|
|
### 2. Create Virtual Environment
|
|
|
|
```bash
|
|
python3 -m venv venv
|
|
source venv/bin/activate # Linux/macOS
|
|
# OR
|
|
.\venv\Scripts\Activate.ps1 # Windows
|
|
```
|
|
|
|
### 3. Install Python Packages
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
Or manually:
|
|
```bash
|
|
pip install pybullet numpy pillow pyinstaller
|
|
```
|
|
|
|
### 4. Run Simulation
|
|
|
|
```bash
|
|
python standalone_simulation.py
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### PyBullet fails to install
|
|
|
|
Install build tools:
|
|
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt install build-essential
|
|
|
|
# Arch
|
|
sudo pacman -S base-devel
|
|
|
|
# macOS
|
|
xcode-select --install
|
|
|
|
# Windows
|
|
# Install Visual Studio Build Tools
|
|
```
|
|
|
|
### "Cannot connect to X server"
|
|
|
|
PyBullet GUI requires a display:
|
|
|
|
```bash
|
|
# Use virtual display
|
|
sudo apt install xvfb
|
|
xvfb-run python standalone_simulation.py
|
|
|
|
# OR use X11 forwarding
|
|
ssh -X user@host
|
|
```
|
|
|
|
### Pillow fails to install
|
|
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt install libjpeg-dev zlib1g-dev
|
|
|
|
# Arch
|
|
sudo pacman -S libjpeg-turbo zlib
|
|
|
|
# macOS
|
|
brew install libjpeg zlib
|
|
```
|
|
|
|
### Permission denied on Windows
|
|
|
|
Run PowerShell as Administrator:
|
|
```powershell
|
|
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
|
|
```
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
After installation, verify packages:
|
|
|
|
```bash
|
|
python -c "import pybullet; print('PyBullet OK')"
|
|
python -c "import numpy; print('NumPy OK')"
|
|
python -c "from PIL import Image; print('Pillow OK')"
|
|
```
|
|
|
|
All should print "OK".
|