Installation¶

Install the SDK itself here, then add the pieces your mission needs: drone drivers, simulation, RealSense & indoor, or Docker. The tested platform matrix is on the Compatibility page.

Choose your setup¶

Start from the row that matches your machine:

make setup (or ./scripts/setup.sh with no args) opens an interactive menu. Its entries:

• Quick setup — system deps + pick modules + build + verify
• Python modules — install only the modules you choose
• Drone driver — mavros / px4 / px4-dds / crazyflie / bebop
• System packages — skipped when already installed
• ROS 2 environment, Build, Verify, RealSense

Then add what your mission needs¶

Full details: Drone drivers (install + fly real hardware), Simulation, and RealSense & indoor.

bash <(curl -fsSL https://raw.githubusercontent.com/Black-Bee-Drones/nectar-sdk/main/scripts/bootstrap.sh)

NON_INTERACTIVE=true ROS2_WORKSPACE=~/ros2_ws bash scripts/bootstrap.sh

./scripts/setup.sh

cd ~/ros2_ws/src
git clone git@github.com:Black-Bee-Drones/nectar-sdk.git
cd nectar-sdk
make setup

make docker-build
make docker-run

Python Environment¶

Python dependencies install into a single shared virtual environment, managed by uv, at $WORKSPACE/.venv (e.g. ~/ros2_ws/.venv). uv is installed automatically if missing.

• Created automatically on the first make python* / make setup, with --system-site-packages so ROS 2 (rclpy, message bindings, colcon) stays visible inside it.
• Activation is opt-in. The SDK's own commands (make build, make verify, make python*, make pytorch) use the venv internally, so they always work. For your interactive shell it is not force-activated — that keeps it out of the way of your other projects and workspaces. make ros2-env installs a nectar-activate command for when you want it.
• Reused by the whole workspace. Every package under src/ — the SDK and your own mission/competition code — shares this one venv, so you install once and import nectar from anywhere. No per-project venv needed.

Enter it when you need it (e.g. to run ros2 run nectar <node> or your own scripts); the prompt then shows (nectar):

nectar-activate            # enter the SDK env (command added by `make ros2-env`)
deactivate                 # leave it (shell built-in)
uv pip install <package>   # add a package (fast); plain `pip install` also works

Prefer it always active? Add one line to ~/.bashrc:

source ~/ros2_ws/.venv/bin/activate

Override the location with NECTAR_VENV=/path (an already-active VIRTUAL_ENV is respected); see Configuration for the venv caveat.

Install by Module¶

Install only the modules you need (dependencies defined in nectar/pyproject.toml). Each make target is a thin wrapper over the setup script, so both columns do the same thing:

PyTorch (required for AI module)¶

Installed via uv's native PyTorch integration (--torch-backend), which detects your CUDA driver and pulls torch plus its nvidia-* CUDA wheels from the correct download.pytorch.org index:

A known-good torch/torchvision pair is pinned by default in scripts/lib/config.sh for reproducibility; override with TORCH_VERSION / TORCHVISION_VERSION (set both together). Large CUDA wheels on slow links can stall — the per-request timeout is raised to 600s (UV_HTTP_TIMEOUT); on very flaky networks also export UV_CONCURRENT_DOWNLOADS=1. See PyTorch Get Started and the uv PyTorch guide.

Build & Verify¶

The full command list is on the Commands & Makefile reference.

System Setup (individual steps)¶

Troubleshooting¶

ROS2 not found¶

source /opt/ros/humble/setup.bash

Package not found after build¶

source ~/ros2_ws/install/local_setup.bash

Camera permission denied¶

sudo usermod -a -G video $USER
# Logout and login

MAVROS connection issues¶

sudo usermod -a -G dialout $USER
# Logout and login