Initial Attempt
This commit is contained in:
267
docs/installation.md
Normal file
267
docs/installation.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# 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 in GUI mode
|
||||
- Gazebo not officially supported
|
||||
- ROS 2 requires Windows-specific binaries
|
||||
- Consider WSL2 for full Linux experience
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
```
|
||||
Reference in New Issue
Block a user