🌊 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 ros2_ws workspace, and select the matching launch configuration with ./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, 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 ros2_ws workspace, and select a bag with ./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.

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.

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