RDC_Simulation/docs/installation.md

# Installation Guide

This guide covers installation on Ubuntu, macOS, and Windows.

## Quick Install

### Ubuntu / Debian

```bash
cd simulation
chmod +x setup/install_ubuntu.sh
./setup/install_ubuntu.sh
source activate.sh
```

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

---

## What Gets Installed

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

---

## Manual Installation

If the scripts don't work, follow these steps manually.

### Step 1: Install ROS 2

#### Ubuntu 22.04 (Humble)

```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

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

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

sudo apt update
sudo apt install -y ros-humble-desktop
```

#### Ubuntu 24.04 (Jazzy)

```bash
# Same as above, but install ros-jazzy-desktop
sudo apt install -y ros-jazzy-desktop
```

### Step 2: Install Gazebo

```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
```

### Step 3: Create Python Virtual Environment

```bash
sudo apt install -y python3-venv python3-full

cd /path/to/simulation
python3 -m venv venv --system-site-packages
source venv/bin/activate
```

### Step 4: Install Python Dependencies

```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
```

---

## Troubleshooting

### "externally-managed-environment" Error

This happens on modern Ubuntu/Debian due to PEP 668. Solution: use the virtual environment.

```bash
source activate.sh  # Activates venv
pip install pybullet  # Now works
```

### ROS 2 Packages Not Found

Ensure ROS 2 is sourced before activating venv:

```bash
source /opt/ros/humble/setup.bash  # or jazzy
source venv/bin/activate
```

The `activate.sh` script handles this automatically.

### Gazebo Not Starting

Check if Gazebo is properly installed:

```bash
which gz
gz sim --version
```

If missing, install the ROS-Gazebo packages:

```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:**
```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
```

---

## Uninstalling

### Remove Virtual Environment

```bash
rm -rf venv/
rm activate.sh
```

### Remove ROS 2 (Ubuntu)

```bash
sudo apt remove ros-humble-*  # or jazzy
sudo rm /etc/apt/sources.list.d/ros2.list
```