Guppy!

Home to the ROS 2 code that runs Guppy: Palouse RoboSub's 2026 AUV for the international RoboSub competition.

Getting Started

Installation

To install, run the following on a brand new Ubuntu 24.04 installation:

sudo apt install -y curl
curl https://raw.githubusercontent.com/PalouseRobosub/guppy/refs/heads/main/util/bootstrap.sh | bash

This runs the utils/boostrap.sh script. If you do not use the install script, please be sure to clone the repo recursively with --recurse-submodules for all of the vendor packages.

Building

cd ~/guppy
colcon build
source install/setup.bash

Running

# to run on hardware:
ros2 launch guppy hw.xml

# to run simulated codebase:
ros2 launch guppy sim.xml

# to run teleop control software:
ros2 launch guppy teleop.xml

Do not run hw.xml and sim.xml simultaneously. The simulator uses PalouseRobosub/GNCea!

Running in Dev Containers

The included Dockerfile and devcontainer.json allow the guppy repo to be opened inside of a docker container attatched to your IDE of choice. Open guppy in your devcontainer-compatible IDE, and then build the container and relaunch to open in the container. If using VSCode, be sure to install all recommended extensions when prompted.

To interact with the Docker contaner graphically, you can visit localhost:6080/vnc.html, or connect with a VCN client to localhost:5901

Organization

The code is broken up into several ROS 2 packages, in the src/ directory:

• guppy: A metapackage that contains dependencies of all other packages, as well as bringup and launch scripts.
• guppy_can: A CAN bus relay and transciever package, for communicating with our custom circuit boards.
• guppy_control: The main control code for the thrusters and chassis, and the torpedo and arm servos as well.
• guppy_description: Contains the URDF and various descriptive parameters of Guppy.
• guppy_localization: Contains sensor publisher nodes and performs sensor fusion via robot_localization with an Extended Kalman Filter.
• guppy_moveit: MoveIt! config files and nodes.
• guppy_msgs: Custom message/service/action definitions.
• guppy_nav2: Nav2 configuration files.
• guppy_safety: Safety and watchdog monitoring, as well as LED publishing.
• guppy_state: The omnipotent state machine.
• guppy_tasks: Action nodes for each of the tasks in the game. Control will be shifted from Nav2 to the individual task nodes via behavior trees.
• guppy_teleop: Code and nodes for operating the robot with a human operator (for testing and general fun).
• guppy_vision: Object detection, camera publishers, and potentially VSLAM.

Each package has two launch files: hw.xml and core.xml. The hw (hardware) launch file is almost always a superset of the core functionality.

Contributing

To contribute code:

1. Make a new branch with the format name/feature_name such as cole/add_dvl_sensor and make all changes in that branch.
2. Add your GitHub username to the correct section of the CODEOWNERS file.
3. Make a Pull Request to the main branch and request @cole-wilson as a reviewer.
4. Make sure all commits have proper messages starting with feat:, chore:, or fix:
5. Document and comment all of your code!
6. Ensure all checks pass in the GitHub Action attached to the Pull Request.

Contact and Sponsorship

Need to get in touch? Reach out to robosub.vcea@wsu.edu.

We are sponsored by many generous companies and people, including:

• OSH Park PCBs
• Blue Robotics
• Real Digital
• Solidworks
• Vectornav
• JoeScan
• WaterLinked
• LattePanda
• Tektronix
• And many many other personal supporters through their generous donations!

Do you like our work? Consider sponsoring our team!