Instalação¶

Instale o SDK aqui e depois acrescente o que a missão precisa: drivers de drone, simulação, RealSense e indoor ou Docker. A matriz de plataformas testadas está em Compatibilidade.

Escolha sua instalação¶

Comece pela linha que corresponde à sua máquina:

make setup (ou ./scripts/setup.sh sem args) abre um menu interativo. Entradas:

• Quick setup — deps de sistema + escolha de módulos + build + verify
• Python modules — instala só os módulos que você escolher
• Drone driver — mavros / px4 / px4-dds / crazyflie / bebop
• System packages — pulado quando já instalado
• ROS 2 environment, Build, Verify, RealSense

Depois acrescente o que a missão precisa¶

Detalhes: Drivers de drone (instalar + voar hardware), Simulação e RealSense e 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

Ambiente Python¶

As dependências Python instalam em um único ambiente virtual compartilhado, gerenciado pelo uv, em $WORKSPACE/.venv (p.ex. ~/ros2_ws/.venv). O uv é instalado automaticamente se estiver ausente.

• Criado automaticamente no primeiro make python* / make setup, com --system-site-packages para que o ROS 2 (rclpy, bindings de mensagens, colcon) continue visível dentro dele.
• A ativação é opt-in. Os próprios comandos do SDK (make build, make verify, make python*, make pytorch) usam o venv internamente, então sempre funcionam. No seu shell interativo ele não é forçado — assim não atrapalha outros projetos e workspaces. make ros2-env instala o comando nectar-activate para quando quiser.
• Reutilizado por todo o workspace. Todo pacote sob src/ — o SDK e o seu código de missão/competição — compartilha este venv, então você instala uma vez e faz import nectar de qualquer lugar. Não precisa de venv por projeto.

Entre nele quando precisar (p.ex. para ros2 run nectar <node> ou seus scripts); o prompt mostra (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

Para ativar o env em todo shell novo, acrescente uma linha ao ~/.bashrc:

source ~/ros2_ws/.venv/bin/activate

Sobrescreva o local com NECTAR_VENV=/path (um VIRTUAL_ENV já ativo é respeitado); veja Configuração para o caveat do venv.

Instalar por módulo¶

Instale só os módulos de que precisa (dependências em nectar/pyproject.toml). Cada alvo make é um wrapper fino sobre o script de setup, então as duas colunas fazem o mesmo:

PyTorch (obrigatório para o módulo de IA)¶

Instalado pela integração nativa de PyTorch do uv (--torch-backend), que detecta o driver CUDA e puxa torch mais as wheels nvidia-* CUDA do índice correto em download.pytorch.org:

Um par conhecido torch/torchvision é pinado por padrão em scripts/lib/config.sh para reprodutibilidade; sobrescreva com TORCH_VERSION / TORCHVISION_VERSION (defina os dois juntos). Wheels CUDA grandes em links lentos podem travar — o timeout por request sobe para 600s (UV_HTTP_TIMEOUT); em redes muito instáveis também export UV_CONCURRENT_DOWNLOADS=1. Veja PyTorch Get Started e o guia PyTorch do uv.

Build e verificação¶

A lista completa de comandos está na referência Comandos e Makefile.

Setup de sistema (passos individuais)¶

Solução de problemas¶

ROS 2 não encontrado¶

source /opt/ros/humble/setup.bash

Pacote não encontrado após o build¶

source ~/ros2_ws/install/local_setup.bash

Permissão negada na câmera¶

sudo usermod -a -G video $USER

# Logout and login

Problemas de conexão MAVROS¶

sudo usermod -a -G dialout $USER

# Logout and login