🌊 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 a runtime image for HoloOcean-ROS on the cougars-auv organization's fork. When prompted to run ./build_container.sh, specify the branch nelson/cougars-dev using ./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 to choose a devcontainer.json file, click CoUGARs Dev (GPU).

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

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

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

    cd ~/cougars-dev/ros2_ws && 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 to choose a devcontainer.json file, click CoUGARs Dev.

  • Once the containers load, copy your rosbag2 bag into the bags folder at the root of the repository.

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

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

If you run into crashes or out-of-memory errors while building the workspace, restrict the compiler to a single worker using colcon build --parallel-workers 1.

If not all repositories appear in the Git sidebar in VSCode, open settings (Ctrl + ,), set "Git: Repository Scan Max Depth" to 3, and reload the window.

Documentation

Fleet Assembly

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

Field Operations

• Mission Preparation
• Fleet Deployment
• Post-Mission Analysis

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 and debug your new feature. Test it extensively.

  If you need to add dependencies, update the relevant package.xml files, Dockerfiles under .docker/, cougars.repos, dev.repos, or dependencies.repos. Test building the Docker images locally.

• Sync Frequently: Regularly integrate the latest changes from main into your branches (via rebase or merge) to prevent future conflicts.

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

• Submit Final PR: Before merging the cougars-dev branch, revert the temporary changes to the .repos files. Upon merge to main, GitHub Actions will automatically build and push updated images to Docker Hub.

Releasing

We adhere to the Semantic Versioning (SemVer 2.0.0) standard to release new versions of this repository:

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 dedicated minor release branch (e.g., release/v1.2.x) from main.

  Do not create separate branches for patch versions (e.g., v1.2.0 to v1.2.1). Simply merge fixes into the minor release branch and bump the patch version on a new tag when ready to release.

• Tag Packages: Check the packages listed in cougars.repos and dev.repos. If they have untagged updates, update the <version> in the package.xml files and push new tags (e.g., v2.3.4). Since packages version independently of cougars-dev, you can either use an existing up-to-date tag or create a new one.

• Lock Dependencies: On the release branch, pin all packages in the .repos files to their specific tags (instead of branches like main). Commit these updates.

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

  git tag v1.2.3
  git push origin v1.2.3

  Pushing the tag automatically rebuilds and publishes the Docker images using a <target>-<version> format (e.g., frostlab/cougars:base-v1.2.3) and opens a draft GitHub Release with auto-generated notes.

• Publish a GitHub Release: Review the draft release in GitHub and click Publish.

Citations

Please cite our relevant publications if you find this repository useful for your research:

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}
}