Skip to content

Getting Started

Jump to bottom
Ty edited this page Oct 7, 2026 · 4 revisions

Getting Started

This page covers the basic setup needed to build, run, and begin developing the Snappy2027 software.

Snappy2027 is AUVic's ROS 2 software stack for the 2027 RoboSub competition cycle. The project uses ROS 2 Humble. See the ROS2 page for more information about ROS 2 and how we use it on Snappy.

Development and deployment are handled using Docker so that everyone can work with a consistent ROS 2 environment and dependency setup.

Development Setup

Requirements

For the current development setup you will need:

  • Git
  • Docker
  • Docker Compose

Clone the Repository

Clone Snappy2027:

git clone https://github.com/uvic-auvic/Snappy2027.git

Enter the repository:

cd Snappy2027

Switch to the current development branch:

git checkout dev

You can verify your current branch with:

git branch --show-current

You should see:

dev

Repository Structure

The repository is roughly organized as:

Snappy2027/
├── docker/
├── docs/
├── scripts/
└── src/
    ├── autonomy/
    ├── common/
    ├── control/
    ├── drivers/
    ├── estimation/
    ├── launch/
    └── vision/

The src/ directory contains the ROS 2 packages used by the Snappy software stack.

The main software areas currently include:

  • Autonomy - mission and autonomy logic
  • Control - vehicle control
  • Drivers - sensor and hardware interfaces
  • Estimation - vehicle state estimation
  • Launch - whole-vehicle ROS 2 launch configuration
  • Vision - computer vision
  • Common - shared code used by other parts of the system

See Software Subsystems (Nodes) for more information about each subsystem.

Docker Setup

Snappy2027 uses Docker to provide the ROS 2 development environment.

./scripts/setup_docker.sh

The setup script:

  1. Starts the Snappy development container.
  2. Imports pinned external repositories.
  3. Installs ROS dependencies using rosdep.
  4. Builds the ROS 2 workspace.
  5. Opens a Bash shell inside the container.

Inside the container, the repository is mounted at:

/ros2_ws

This is the root of the ROS 2 workspace.

Entering an Existing Development Container

The best way to re enter the docker container is by running

./scripts/run_docker.sh

This script does the following

starts it with:

docker compose -f docker/docker-compose.yml up -d snappy-dev

Then enters it with:

docker compose -f docker/docker-compose.yml exec snappy-dev bash

Working Inside the Docker Container

Most ROS 2 development commands should be run inside the Docker container.

Once inside the container, move to the workspace root:

cd /ros2_ws

Source ROS 2

ROS 2 Humble can be sourced with:

source /opt/ros/humble/setup.bash

After Snappy has been built, source the Snappy workspace with:

source /ros2_ws/install/setup.bash

Why do I need to source the workspace?

Building a ROS 2 workspace creates an install/ directory containing environment setup files.

Sourcing install/setup.bash tells ROS 2 where to find the packages that were built in the Snappy workspace.

If ROS 2 reports that a Snappy package cannot be found after building, make sure you have sourced:

source install/setup.bash

You generally need to do this again after opening a new shell.

Building Snappy

The initial Docker setup automatically builds Snappy.

For normal development, you can rebuild the entire workspace manually.

Basic Build

From /ros2_ws:

colcon build

After the build finishes:

source install/setup.bash

Build a Single Package

While developing one subsystem, it is often faster to build only the package you are working on.

The general command is:

colcon build --packages-select <package_name>

For example:

colcon build --packages-select snappy_control

After building, source the workspace again:

source install/setup.bash

List Packages in the Workspace

To see the packages detected by colcon:

colcon list

This is useful if you are unsure of the exact package name.

You can also inspect the packages ROS 2 currently knows about with:

ros2 pkg list

To show only Snappy packages:

ros2 pkg list | grep snappy

Cleaning a Build

ROS 2 builds produce three main directories:

build/
install/
log/

In the Docker setup, these are stored using Docker volumes rather than directly in the host checkout.

If you are debugging a build problem, avoid deleting build data unless necessary. A clean build can take significantly longer because all packages must be rebuilt.

Running Snappy

The current whole-vehicle ROS 2 launch package is:

snappy_launch

The current launch file is (More launch files will be made):

snappy_realsense.launch.py

After building and sourcing the workspace:

ros2 launch snappy_launch snappy_realsense.launch.py

Finding Available Launch Files

Launch files for Snappy are currently stored under:

src/launch/launch/

At the moment, the repository contains:

snappy_realsense.launch.py

As the launch system changes, check this directory for the current available launch files.

Common ROS 2 Commands

The following commands are useful when developing or debugging Snappy.

See ROS2 for a more detailed explanation of ROS 2 concepts and commands.

List Running Nodes

ros2 node list

A node is an individual ROS 2 program or component currently running.

This is one of the first commands to run when checking whether the system launched correctly.

Inspect a Node

ros2 node info <node_name>

For example:

ros2 node info /some_node

This shows information such as:

  • Publishers
  • Subscribers
  • Services
  • Actions

List Topics

ros2 topic list

Topics are one of the main ways ROS 2 nodes communicate.

If a sensor or subsystem is expected to be running, checking the topic list can help confirm whether it is publishing data.

View Data From a Topic

ros2 topic echo <topic_name>

For example:

ros2 topic echo /example_topic

Inspect a Topic

ros2 topic info <topic_name>

Current Work in Progress

Some parts of the development workflow are still being improved. The commands on this page reflect the current workflow, but some of them are expected to become simpler over time.

Checkout open Issue to see what we are currently working on!

Next Steps

Once your development environment is working, the following wiki pages provide more detail:

Snappy2027 Wiki

Clone this wiki locally