504 lines
9.5 KiB
Markdown
504 lines
9.5 KiB
Markdown
# Installation Guide
|
|
|
|
Setup instructions for all supported platforms.
|
|
|
|
## Quick Install
|
|
|
|
| Platform | Command |
|
|
|----------|---------|
|
|
| Ubuntu/Debian | `./setup/install_ubuntu.sh` |
|
|
| Ubuntu + ArduPilot | `./setup/install_ubuntu.sh --with-ardupilot` |
|
|
| 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 | ❌ | ❌ | ✅ |
|
|
| **ArduPilot SITL** | ✅ | ⚠️ Manual | ❌ | ❌ | ✅ |
|
|
| **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, pymavlink
|
|
|
|
**With ArduPilot SITL (full flight controller):**
|
|
```bash
|
|
# Run installer with ArduPilot
|
|
./setup/install_ubuntu.sh --with-ardupilot
|
|
|
|
# This will also install:
|
|
# - ArduPilot SITL (~15-20 min build)
|
|
# - ArduPilot Gazebo plugin
|
|
# - MAVProxy
|
|
```
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
**Gazebo GPU Issues in WSL2:**
|
|
|
|
If Gazebo crashes with GPU/OpenGL errors, try:
|
|
|
|
```bash
|
|
# Option 1: Run in server mode (no GUI)
|
|
ign gazebo -s gazebo/worlds/drone_landing.sdf
|
|
|
|
# Option 2: Fix permissions and restart WSL
|
|
sudo usermod -aG render $USER
|
|
chmod 700 /run/user/1000
|
|
# Then in PowerShell: wsl --shutdown
|
|
|
|
# Option 3: Force software rendering
|
|
export LIBGL_ALWAYS_SOFTWARE=1
|
|
ign gazebo gazebo/worlds/drone_landing.sdf
|
|
|
|
# Option 4: Just use PyBullet (more reliable on WSL2)
|
|
python standalone_simulation.py
|
|
```
|
|
|
|
**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')"
|
|
python -c "from pymavlink import mavutil; print('pymavlink OK')"
|
|
```
|
|
|
|
All should print "OK".
|
|
|
|
---
|
|
|
|
## ArduPilot SITL Manual Setup
|
|
|
|
If you want to install ArduPilot SITL manually (without the install script):
|
|
|
|
### 1. Install ArduPilot
|
|
|
|
```bash
|
|
# Clone ArduPilot
|
|
git clone --recurse-submodules https://github.com/ArduPilot/ardupilot.git ~/ardupilot
|
|
cd ~/ardupilot
|
|
|
|
# Install prerequisites (Ubuntu)
|
|
Tools/environment_install/install-prereqs-ubuntu.sh -y
|
|
|
|
# Reload profile
|
|
. ~/.profile
|
|
|
|
# Build ArduCopter SITL
|
|
./waf configure --board sitl
|
|
./waf copter
|
|
```
|
|
|
|
### 2. Install ArduPilot Gazebo Plugin
|
|
|
|
```bash
|
|
# Clone plugin
|
|
git clone https://github.com/ArduPilot/ardupilot_gazebo.git ~/ardupilot_gazebo
|
|
cd ~/ardupilot_gazebo
|
|
|
|
# Build
|
|
mkdir build && cd build
|
|
cmake .. -DCMAKE_BUILD_TYPE=Release
|
|
make -j$(nproc)
|
|
```
|
|
|
|
### 3. Set Environment Variables
|
|
|
|
Add to `~/.bashrc`:
|
|
|
|
```bash
|
|
# ArduPilot
|
|
export ARDUPILOT_HOME=$HOME/ardupilot
|
|
export PATH=$PATH:$ARDUPILOT_HOME/Tools/autotest
|
|
|
|
# ArduPilot Gazebo Plugin
|
|
export GZ_SIM_SYSTEM_PLUGIN_PATH=$HOME/ardupilot_gazebo/build:$GZ_SIM_SYSTEM_PLUGIN_PATH
|
|
export GZ_SIM_RESOURCE_PATH=$HOME/ardupilot_gazebo/models:$HOME/ardupilot_gazebo/worlds:$GZ_SIM_RESOURCE_PATH
|
|
```
|
|
|
|
### 4. Test SITL
|
|
|
|
```bash
|
|
# Test ArduCopter SITL
|
|
cd ~/ardupilot
|
|
sim_vehicle.py -v ArduCopter --console --map
|
|
```
|
|
|
|
### 5. Run with Gazebo
|
|
|
|
```bash
|
|
# Terminal 1: Launch Gazebo
|
|
ros2 launch gazebo/launch/ardupilot_drone.launch.py
|
|
|
|
# Terminal 2: Start SITL
|
|
cd ~/ardupilot
|
|
sim_vehicle.py -v ArduCopter -f gazebo-iris --model JSON --console
|
|
|
|
# Terminal 3: Run controllers
|
|
cd ~/simulation
|
|
source activate.sh
|
|
python run_ardupilot.py --no-sitl --pattern circular
|
|
```
|
|
|
|
For more details, see [ArduPilot Guide](ardupilot.md).
|