RDC_Simulation/docs/installation.md

Installation Guide

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

Quick Install

Ubuntu / Debian

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

macOS

cd simulation
chmod +x setup/install_macos.sh
./setup/install_macos.sh
source activate.sh

Windows (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)

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)

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

Step 2: Install Gazebo

# 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

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

pip install --upgrade pip
pip install pybullet pyinstaller

Step 5: Create Activation Script

Create activate.sh:

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

chmod +x activate.sh

---

Verifying Installation

After installation, verify all components:

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.

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

ROS 2 Packages Not Found

Ensure ROS 2 is sourced before activating venv:

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:

which gz
gz sim --version

If missing, install the ROS-Gazebo packages:

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:

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:

. .\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:

cd simulation
git pull  # If using git

# Reinstall Python dependencies
source activate.sh
pip install --upgrade pybullet pyinstaller

---

Uninstalling

Remove Virtual Environment

rm -rf venv/
rm activate.sh

Remove ROS 2 (Ubuntu)

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