RDC_Simulation/docs/installation.md

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:

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)

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

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

yay -S ros-humble-desktop
yay -S ros-humble-ros-gz

---

macOS

Tested on: macOS 12+ (Monterey, Ventura, Sonoma)

# 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

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

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

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

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

# Windows C: drive is at /mnt/c/
cd /mnt/c/Users/YourName/Documents

Run from Windows Terminal:

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:

# Check if GPU is available
nvidia-smi

# PyBullet will use hardware rendering automatically

Troubleshooting WSL GUI:

If GUI doesn't work:

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

# Install VcXsrv
choco install vcxsrv -y

Then in WSL:

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

# 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

python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# OR
.\venv\Scripts\Activate.ps1  # Windows

3. Install Python Packages

pip install -r requirements.txt

Or manually:

pip install pybullet numpy pillow pyinstaller

4. Run Simulation

python standalone_simulation.py

---

Troubleshooting

PyBullet fails to install

Install build tools:

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

# 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

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

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

---

Verification

After installation, verify packages:

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