Duke Robotics Club - RoboSub ROS

We are a Duke University club competing in the RoboSub Competition. Check out our website.

Our codebase is split into two repositories:

1. This repo contains all of the code required for running and testing our robots.
2. The documentation repo contains introductory projects, tutorials, and miscellaneous docs.

Our code is Dockerized, making it straightforward to set up and run. See Running Our Docker Images.

Once the containers are up and running, go to Running Our Code.

Software Stack

Our stack is split into two workspaces -- onboard and landside -- each with corresponding Docker containers of the same name. Onboard consists of the code that runs on the robot's internal computer. Landside consists of the code that should be run on your local machine. The corresponding containers are connected via a local network and are configured to share ROS messages. For an in-depth explanation of the containers, see docker.

Our codebase is powered by the Robot Operating System (ROS), and written primarily in Python.

The following components make up our software stack:

• Onboard:
  • Acoustics - Handles the task of locating an underwater hydrophone pinger.
  • AVT Camera - Drives our ethernet cameras and publishes a live video feed.
  • Controls - Determines thruster outputs given a current and desired state.
  • Computer Vision - Locates objects (goals/obstacles) via camera input and machine learning.
  • Data Pub - Collects and parses data from sensors and publishes it for use by other packages.
  • Execute - Houses launch files that simplify starting and stopping our stack.
  • Offboard Comms - Allows communication between ROS code and the onboard Arduino.
  • RoboSub Description - Contains files to describe and display our robot.
  • Sensor Fusion - Interprets sensor data and publishes an estimation of the current robot state.
  • Static Transforms - Makes static transforms available for other packages.
  • System Utils - Contains system helpers for evaluating performance and interacting with hardware.
  • Task Planning - Plans the tasks and motion of the robot by synthesizing inputs.
• Landside:
  • Camera View - Package that allows for viewing, saving, and loading videos to simulate camera input.
  • Joystick - Allows manual joystick control for testing.
  • Simulation - Physics-enabled simulation that can be used for local testing.

Flow

The general flow of information between components is shown in the diagram below, from top to bottom:

        sensors (IMU, DVL, etc.)                cameras
            \                                     / \
             \                                   /   \
              v                                 /     v
            Data Pub                           /   Camera View
                \                             /
 Simulation ---> \          Acoustics        /
                  v             |            v
                Sensor Fusion   |      Computer Vision
                    \           |         /
                     \          |        /
                      v         v       v
                         Task Planning
                               |
                               |
                               v
              Joystick ---> Controls
                               |
                               | ---> Simulation
                               v
                         Offboard Comms
                               |
                               |
                               v
                    thrusters, actuators, etc.

Running Our Docker Images

Required Software

1. Download and install the appropriate Docker client.

   • Mac
   • Windows (Home)
   • Windows (Pro, Education, etc.)
     ℹ️ Which Windows do I have? Settings > System > About > look at "Edition"

2. If you want graphics forwarding over SSH:

   • Mac: XQuartz
   • Windows: MobaXterm
     ⚠️ Open MobaXterm > click on Settings > go the X11 tab > uncheck RANDR. This allows us to use rviz over SSH.

Pool Testing

Use these instructions when running code on the robot itself.

1. Connect your computer to the robot via Ethernet. Then SSH into the robot's onboard computer.

   ssh [email protected]

2. There, make sure the latest code from this repo is pulled. Then, run the onboard container if it's not already running.

   docker run -td --privileged --net=host -e ROBOT_NAME=oogway -v /home/robot/robosub-ros:/root/dev/robosub-ros -v /dev:/dev dukerobotics/robosub-ros:onboard

3. Clone this repo on your local computer. In the newly-created directory (robosub-ros), run the landside container. If on Windows, use PowerShell.

   docker run -td -p 2201:2201 -v ${PWD}:/root/dev/robosub-ros dukerobotics/robosub-ros:landside

4. SSH into the onboard container. Password is robotics.

   ssh -p 2200 [email protected]

5. SSH into the landside container. Password is robotics.

   ssh -XY -p 2201 root@localhost

6. Now go to Running Our Code.

Local Testing

Use these instructions to test code on your computer by simulating the robot's execution. For all docker compose commands, replace <robot name here> with the robot name (cthulhu or oogway).

1. To run the containers, clone this repo. In the newly-created directory (robosub-ros), execute

   docker compose -f docker-compose-<robot name here>.yml up -d

   This will pull the images if you don't have them, create a new network that simulates the network we use on our robot, mount the code, and start the containers.

   To update the images, or to just pull them without running them, use docker compose -f docker-compose-<robot name here>.yml pull.

2. SSH into the onboard container. Password is robotics.

   ssh -p 2200 root@localhost

3. In a new tab, SSH into the landside container. Password is robotics.

   ssh -XY -p 2201 root@localhost

4. Now go to Running Our Code. Also set up our simulation.

5. To stop and delete both containers and their network, in the robosub-ros directory, execute

   docker compose -f docker-compose-<robot name here>.yml down

Running Our Code

⚠️ All commands should be run inside of a Docker container.

Building and Sourcing

The following needs to be done once at the beginning, and then later only when making larger structural changes to the workspace (such as adding a package).

Executing Build Script

We use a custom build script that simplifies the process of building and overlaying catkin workspaces.

To build our workspaces for ROS, in the ~/dev/robosub-ros directory, execute

./build.sh <workspace>

where <workspace> is the workspace to build, either onboard or landside.

Sourcing Setup File

Once the build script has finished executing, source the setup file using

source <workspace>/catkin_ws/devel/setup.bash

where <workspace> is the workspace you just built. This will also be the last line that is printed from the build script, so you can also just copy and execute that.

You should now be ready to use our packages and ROS.

Running Launch Files

Here are some common launch configurations for both pool and local testing.

• Test controls using test_state_publisher.py

  roslaunch execute motion.launch
  rosrun controls test_state_publisher.py
  rosservice call /enable_controls true

  but change the first line for local testing in the simulation

  roslaunch execute motion.launch sim:=true

• Pool testing with joystick (see Joystick Documentation)

• Useful commands for testing

  • Stop all thrusters

    rosservice call /enable_controls false

  • Echo current state

    rostopic echo /state

  • Reset state to zero

    rosservice call /set_pose  # tab complete, then change w from 0.0 to 1.0

    or here's the full command for copy-pasting:

    rosservice call /set_pose "pose:
    header:
    seq: 0
    stamp:
    secs: 0
    nsecs: 0
    frame_id: ''
    pose:
    pose:
    position: {x: 0.0, y: 0.0, z: 0.0}
    orientation: {x: 0.0, y: 0.0, z: 0.0, w: 1.0}
    covariance: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]"

Cleaning Build

To clean the build outputs from a workspace (build, devel, and logs folders), in the ~/dev/robosub-ros directory, execute

./build.sh clean <workspace>

where <workspace> is either onboard or landside. If you would like to clean all workspaces, then you may simply execute

./build.sh clean

Contributing

To contribute to this repository, see CONTRIBUTING.md.