🌊 CoUGARs: Configurable Underwater Group of Autonomous Robots

CoUGARs is a low-cost, configurable AUV platform designed for multi-agent autonomy research by the Field Robotic Systems Lab (FROST Lab) at Brigham Young University.

Get Started

Prerequisites: 64-bit Linux, 15+ GB of free disk space, and a dedicated NVIDIA GPU (for HoloOcean simulation).

• Install Docker and VSCode Dev Containers.

• Add a GitHub SSH key and clone the cougars-dev repository.

  git clone git@github.com:cougars-auv/cougars-dev.git

• Choose a development workflow:

  Simulation (HoloOcean):

  • Build the runtime image from the cougars-auv fork of HoloOcean-ROS. When prompted to run ./build_container.sh, specify the nelson/cougars-dev branch with ./build_container.sh -b nelson/cougars-dev.

  • Open the cougars-dev repository in VSCode and use the Command Palette (Ctrl + Shift + P) to select "Dev Containers: Reopen in Container." When prompted, click "CoUGARs Dev (NVIDIA)."

  • Once the containers load, open a new terminal window using Ctrl + Alt + Shift + ` and launch a HoloOcean scenario in the cougars-holoocean-ct container using ./holoocean_launch.sh.

    cd ~/cougars-dev/scripts && ./holoocean_launch.sh

  • Open a new terminal, build the workspace, and select the matching launch configuration with ./sim_launch.sh.

    cd ~/cougars-dev && colcon build
    cd ~/cougars-dev/scripts && ./sim_launch.sh

  Simulation (Gazebo):

  This project also contains Gazebo simulations and proof-of-concept code for the 2026 RoboBoat and 2027 URC field robotics competitions.

  • Open the cougars-dev repository in VSCode and use the Command Palette (Ctrl + Shift + P) to select "Dev Containers: Reopen in Container." When prompted, click "CoUGARs Dev" or "CoUGARs Dev (NVIDIA)."

  • Once the containers load, open a new terminal window using Ctrl + Alt + Shift + `, build the workspace, and launch a Gazebo scenario using ./sim_launch.sh.

    cd ~/cougars-dev && colcon build
    cd ~/cougars-dev/scripts && ./sim_launch.sh

  Recorded Data (rosbag2):

  • Open the cougars-dev repository in VSCode and use the Command Palette (Ctrl + Shift + P) to select "Dev Containers: Reopen in Container." When prompted, click "CoUGARs Dev" or "CoUGARs Dev (NVIDIA)."

  • Once the containers load, copy your rosbag2 bag into the repository's bags folder.

  • Open a new terminal window using Ctrl + Alt + Shift + `, build the workspace, and select a bag with ./bag_launch.sh.

    cd ~/cougars-dev && colcon build
    cd ~/cougars-dev/scripts && ./bag_launch.sh

If you run into crashes or out-of-memory errors while building the workspace, limit the build to one package and one compile job at a time using MAKEFLAGS="-j1" colcon build --parallel-workers 1. This is the safest (and slowest) setting, so raise either number as far as your computer's RAM allows.

Documentation

Fleet Assembly

• Bill of Materials
• Assembly Instructions
• Base Station Software Setup
• CougUV Software Setup

Field Operations

• Mission Preparation
• Field Deployment
• Post-Mission Sync

Resources

• Helpful Tutorials

Contributing

For small changes confined to one package, the full cougars-dev branch workflow is unnecessary. Simply create a new package branch and PR.

• Create a Branch: Create a new cougars-dev branch (e.g., nelson/repo-docs).

• Create Package Branches: For each package you plan to modify, create a new branch with the same name. In your new cougars-dev branch, temporarily update the relevant .repos files to reference those branches.

• Make Changes: Develop, debug, and test your changes.

  If you need to add dependencies, update the relevant package.xml files, Dockerfiles under docker/, runtime.repos, dev.repos, and/or dependencies.repos.

• Sync Frequently: Regularly update your branches with the latest main (via rebase or merge).

• Submit Package PRs: Open a pull request for each package branch. Ensure required tests pass, then merge once approved.

• Submit Final PR: After all package PRs have merged, revert the temporary .repos changes in your cougars-dev branch and open a pull request. Ensure required tests pass, then merge once approved.

  Once merged, GitHub Actions will build and push the updated Docker images to Docker Hub under frostlab/cougars:runtime-latest and frostlab/cougars:dev-latest.

• Delete Branches: Remove all the merged branches. Create a new branch from main for any follow-up work.

Releasing

This repository follows the Semantic Versioning (SemVer 2.0.0) standard:

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes
• MINOR version when you add functionality in a backward compatible manner
• PATCH version when you make backward compatible bug fixes

• Create a Release Branch: Create a release branch (e.g., release/v1.2.3) from main.

• Release Packages: Check the packages listed in runtime.repos and dev.repos. For each package with recent untagged updates, release a new version (e.g., v2.3.4) following the "Releasing" section of its README.md. External packages version independently of cougars-dev.

• Lock Dependencies: On the release branch, pin each package in the .repos files to the most recent version.

• Update Package Versions: Before tagging, update the <version> in package.xml for each package in cougars-dev without its own repository. Match the release branch (e.g., 1.2.3). Commit and push your updates.

• Tag and Push: Create and push the new version tag (e.g., v1.2.3) on your release branch:

  git tag v1.2.3
  git push origin v1.2.3

  Pushing the tag will automatically publish a GitHub Release with auto-generated notes, and build and push new Docker images to Docker Hub under frostlab/cougars:runtime-v1.2.3 and frostlab/cougars:dev-v1.2.3.

Citations

If you use this repository in your research, please cite the following publications:

CoUGARs

@misc{durrant2025lowcostmultiagentfleetacoustic,
  title={Low-cost Multi-agent Fleet for Acoustic Cooperative Localization Research},
  author={Nelson Durrant and Braden Meyers and Matthew McMurray and Clayton Smith and Brighton Anderson and Tristan Hodgins and Kalliyan Velasco and Joshua G. Mangelson},
  year={2025},
  eprint={2511.08822},
  archivePrefix={arXiv},
  primaryClass={cs.RO},
  url={https://arxiv.org/abs/2511.08822},
}

HoloOcean-ROS

@misc{meyers2025testingevaluationunderwatervehicle,
  title={Testing and Evaluation of Underwater Vehicle Using Hardware-In-The-Loop Simulation with HoloOcean},
  author={Braden Meyers and Joshua G. Mangelson},
  year={2025},
  eprint={2511.07687},
  archivePrefix={arXiv},
  primaryClass={cs.RO},
  url={https://arxiv.org/abs/2511.07687},
}

HoloOcean

@inproceedings{potokar2022holooceanunderwaterroboticssim,
  author={Easton Potokar and Spencer Ashford and Michael Kaess and Joshua G. Mangelson},
  title={Holo{O}cean: An Underwater Robotics Simulator},
  booktitle={Proc. IEEE Intl. Conf. on Robotics and Automation, ICRA},
  address={Philadelphia, PA, USA},
  month={May},
  year={2022}
}