Installing AQUA Stack

Complete installation guide for setting up AQUA Stack on your underwater vehicle.

Prerequisites

Before installing AQUA Stack, ensure you have:

Hardware Requirements

• ✓ Companion computer (Raspberry Pi 4, NVIDIA Jetson Nano, or better)
• ✓ Camera (Stereo camera or monocular + depth sensor)
• ✓ IMU (6-DOF or 9-DOF)
• ✓ ArduSub-compatible autopilot (Pixhawk, Navigator, etc.)
• ✓ Depth sensor (MS5837 or similar)
• ✓ MicroSD card (32GB+ for data logging)

Software Requirements

• Operating System: Ubuntu 20.04 or 22.04 (recommended)
• ROS: ROS Noetic (Ubuntu 20.04) or ROS 2 Humble (Ubuntu 22.04)
• Python: 3.8+
• ArduSub: Latest stable release

Check detailed requirements →

Installation Methods

Choose the installation method that best fits your needs:

Method 1: Quick Install (Recommended)

For standard setups with BlueROV2 or similar vehicles:

# Download installer
wget https://downloads.signalbotics.com/aqua/install.sh

# Run installer
chmod +x install.sh
sudo ./install.sh

# Follow prompts for your vehicle type

Time: ~15 minutes Best for: BlueROV2, standard configurations

Method 2: Docker Install

For isolated environments or development:

# Pull AQUA Stack Docker image
docker pull signalbotics/aqua-stack:latest

# Run container
docker run -it --privileged \
  --network host \
  -v /dev:/dev \
  -v ~/aqua_data:/data \
  signalbotics/aqua-stack:latest

Time: ~5 minutes (after download) Best for: Development, testing, isolated environments

Method 3: Manual Install

For custom configurations or advanced users:

See detailed manual installation →

Quick Install Steps

Step 1: System Preparation

# Update system
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y \
  git curl wget \
  python3-pip \
  build-essential \
  cmake

# Create workspace
mkdir -p ~/aqua_ws/src
cd ~/aqua_ws

Step 2: Install ROS

Ubuntu 20.04 (ROS Noetic)Ubuntu 22.04 (ROS 2 Humble)

# Setup sources
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'

# Setup keys
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -

# Install ROS
sudo apt update
sudo apt install -y ros-noetic-desktop

# Environment setup
echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
source ~/.bashrc

# Setup sources
sudo apt install -y software-properties-common
sudo add-apt-repository universe

# Add ROS 2 apt repository
sudo apt update && sudo apt install -y curl gnupg2 lsb-release
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg

# Install ROS 2
sudo apt update
sudo apt install -y ros-humble-desktop

# Environment setup
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

Step 3: Install AQUA Stack

# Clone AQUA Stack (requires license key)
cd ~/aqua_ws/src
git clone https://gitlab.signalbotics.com/aqua/aqua-stack.git
cd aqua-stack

# Install Python dependencies
pip3 install -r requirements.txt

# Build
cd ~/aqua_ws
catkin_make  # or colcon build for ROS 2

# Source workspace
echo "source ~/aqua_ws/devel/setup.bash" >> ~/.bashrc
source ~/.bashrc

Step 4: Configure License

# Enter your license key
aqua-license --activate YOUR_LICENSE_KEY_HERE

# Verify installation
aqua-stack --version

Step 5: Initial Configuration

# Run configuration wizard
aqua-config

# Select vehicle type:
# 1. BlueROV2 (Heavy)
# 2. BlueROV2 (Standard)
# 3. Custom Vehicle

# Configuration will be saved to:
# ~/.config/aqua/config.yaml

Manual Installation

Install Core Dependencies

# OpenCV
sudo apt install -y \
  libopencv-dev \
  python3-opencv

# Eigen3
sudo apt install -y libeigen3-dev

# Ceres Solver (for optimization)
sudo apt install -y libceres-dev

# gtsam (for SLAM)
sudo apt install -y libgtsam-dev

# MAVLink
pip3 install pymavlink

# Additional Python packages
pip3 install \
  numpy \
  scipy \
  matplotlib \
  pyyaml \
  transforms3d

Install SLAM Backend

# ORB-SLAM3 (recommended)
cd ~/aqua_ws/src
git clone https://github.com/UZ-SLAMLab/ORB_SLAM3.git
cd ORB_SLAM3

# Build
./build.sh

# Install ROS wrapper
cd Examples/ROS/ORB_SLAM3
export ROS_PACKAGE_PATH=$ROS_PACKAGE_PATH:~/aqua_ws/src/ORB_SLAM3/Examples/ROS
./build_ros.sh

Install Navigation Stack

cd ~/aqua_ws/src

# Navigation packages
sudo apt install -y \
  ros-$ROS_DISTRO-navigation \
  ros-$ROS_DISTRO-move-base \
  ros-$ROS_DISTRO-global-planner \
  ros-$ROS_DISTRO-base-local-planner

# Behavior trees
git clone https://github.com/BehaviorTree/BehaviorTree.CPP.git
cd BehaviorTree.CPP
mkdir build && cd build
cmake ..
make -j4
sudo make install

Build AQUA Stack

cd ~/aqua_ws
catkin_make -j4  # or colcon build --parallel-workers 4

# Source
source devel/setup.bash

Hardware Setup

Camera Configuration

For Stereo Camera (e.g., Intel RealSense)

# Install RealSense SDK
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-key F6E65AC044F831AC80A06380C8B3A55A6F3EFCDE
sudo add-apt-repository "deb https://librealsense.intel.com/Debian/apt-repo $(lsb_release -cs) main"
sudo apt update
sudo apt install -y librealsense2-devel librealsense2-utils

# Test camera
realsense-viewer

# Install ROS wrapper
sudo apt install -y ros-$ROS_DISTRO-realsense2-camera

For USB Camera

# Install v4l utils
sudo apt install -y v4l-utils

# List cameras
v4l2-ctl --list-devices

# Test camera
cheese  # or use ROS: rosrun usb_cam usb_cam_node

ArduSub Connection

Via Serial (Direct)

# Add user to dialout group
sudo usermod -a -G dialout $USER

# Reboot for changes to take effect
sudo reboot

Via Network (Companion Computer)

# Configure MAVLink bridge
# Edit: ~/.config/aqua/config.yaml

mavlink:
  connection: udpin:0.0.0.0:14550
  baud: 115200
  system_id: 1
  component_id: 191

Verification

Test Installation

# Check ROS environment
echo $ROS_PACKAGE_PATH

# Test AQUA Stack launch
roslaunch aqua_stack test_system.launch

# Expected output:
# ✓ SLAM node started
# ✓ Navigation node started
# ✓ Control node started
# ✓ MAVLink connection established
# ✓ Camera stream active
# ✓ IMU data received

Run Diagnostics

# System diagnostics
aqua-diagnostics

# Output should show:
# [OK] License valid
# [OK] ROS environment configured
# [OK] SLAM backend available
# [OK] Navigation stack ready
# [OK] Camera detected
# [OK] IMU detected
# [OK] MAVLink connection
# [WARN] DVL not detected (optional)
# [OK] All critical systems operational

Troubleshooting Installation

Common Issues

License Activation Failed

# Check internet connection
ping license.signalbotics.com

# Verify license key
aqua-license --check

# Contact support if persistent:
# support@signalbotics.com

ROS Build Failures

# Clean workspace
cd ~/aqua_ws
rm -rf build devel

# Rebuild with verbose output
catkin_make -DCMAKE_BUILD_TYPE=Release -j2

# Check for missing dependencies
rosdep install --from-paths src --ignore-src -r -y

Camera Not Detected

# Check USB connection
lsusb

# Check permissions
ls -l /dev/video*

# Add user to video group if needed
sudo usermod -a -G video $USER

ArduSub Connection Failed

# Check serial port
ls -l /dev/ttyACM* /dev/ttyUSB*

# Test MAVLink connection
mavproxy.py --master=/dev/ttyACM0 --baudrate 115200

# Check firewall (for network connection)
sudo ufw allow 14550/udp

Updating AQUA Stack

Check for Updates

# Check current version
aqua-stack --version

# Check available updates
aqua-update --check

Update to Latest Version

# Backup configuration
cp ~/.config/aqua/config.yaml ~/aqua_config_backup.yaml

# Update
cd ~/aqua_ws/src/aqua-stack
git pull origin main

# Rebuild
cd ~/aqua_ws
catkin_make

# Restore configuration if needed
cp ~/aqua_config_backup.yaml ~/.config/aqua/config.yaml

Next Steps

✓ Installation complete! Now:

1. Configure for your vehicle - Set up AQUA Stack for your specific hardware
2. Run simulation - Test in simulation before deployment
3. First mission - Complete tutorial for your first mission

Getting Help

• Documentation: docs.signalbotics.com
• Email Support: support@signalbotics.com
• Emergency: +1-XXX-XXX-XXXX (license holders only)

---

Next: Quick Start Guide →