A Guide to Seawolf8 Software

The North Carolina State University's Underwater robotics team maintains a complex net of software and software tools in order to compete in the RoboSub competition. This document will attempt to create a high level description of this system so that new members can get up and running in our software ecosystem. As with all systems, Seawolf 8 and URC change with time and this guide will need to be updated. While this will certainly be a helpful document, some fine details may have changed without this guide being updated. If something is not working, please look to the README.md files in each software github repository and wiki pages for possibly more updated information.

Prerequisites

Software

The following software packages are needed to develop software for URC

• A system running Ubuntu 20.04 (can be a VM)
• ROS Noetic
• python3
• python-is-python3 (an apt package)
• ros-noetic-mavros
• ros-noetic-pid
• OpenCV 4.2 (with python 3 bindings)

Knowledge

General Skills

A member of the URC software team should have a working knowledge of Python. You do not need to be a Python professional to write Python code, but you will need to understand the syntax.

It is estimated that at a minimum a CSC116 level of programming knowledge will be needed (216 will also be very very helpful). If you have not taken this course yet, do not panic! You can pretty easily learn these skills from online websites. I won't link to anything specific because its probably best for you to look around and pick something that works best for you. The following skills should be learned before starting new member projects.

• variables
• control flow
• loops
• functions
• Object Oriented Programming
  • what a class is
  • classes vs objects
  • members, methods etc
• using libraries (using the standard library will give you a good idea)

If you're looking at this and going "man this seems like really basic stuff" don't worry there is still plenty for you to do with a more advanced knowledge base, this is just what is needed at a minimum to start working with the software system.

If you want to work on the gazebo simulator, you need to have knowledge of modern C++. This can certainly be learned after joining the club, but it is considerably more complicated than learning python. Using the simulator however requires no knowledge of programming at all.

ROS

In order to work on anything in the software stack you must learn ROS. ROS can be learned from the official tutorials, which are really good. Additionally you can check out the video tutorials that Amr Moussa made. We believe they are an easy start to understanding ROS, however they don't cover as much content as the official ones. We would recommend using them along side the official tutorials. The rest of this guide wont make much sense without understanding the basics of ROS.

You should also probably learn about TF2. I have a simple guide on it here. If you want to understand what TF2 is I recommend watching this section of this video (from 9:16 till 10:30).

Brief Hardware Overview

Before we can write code for a robot, we must gain an understanding of how that robot works. Seawolf 8 has several major components that must be kept in mind. The club written code runs on an onboard computer called a Jetson Nano. It uses an ARM architecture and has an integrated Tegra GPU that is helpful for vision processing. It is connected to two depth cameras that point forward and down respectively.

It also connected to a flight controller known as the Pixhawk. The Pixhawk controls the motors of the robot, and is connected to several sensors that it processes (depth and IMU being the most prominent). The pixhawk runs ArduSub, which is a firmware written by the company BlueRobotics.

It is also connected to a microcontroller known as the "Main Electrical Board" (MEB). The MEB currently detects the state of the kill switch, and will grow in functionality over time.

Software Overview

Software that runs on Seawolf 8 (SW8) is distributed as a ROS package with several nested ROS packages. They are as follows:

• wolf_serial
  • Responsible for communicating with other devices that are on the robot. This mainly means the Pixhawk and the MEB.
• wolf_control
  • control loops are handled in this package. The movement system (which will be described in further detail in another section) resides in this package. It is also the current home of the "mission code" which is the code that determines what SW8 will actually do when in the water.
• wolf_vision
  • handles computer vision code
• wolf_bringup
  • contains the launch files for SW8 and its simulators
• wolf_gazebo_plugins
  • contains the simulation software and world files (this is the only current C++ package)

The data flow during the operation of SW8 is as follows. A launch file in wolf_bringup will start up all relevant nodes. Wolf_serial nodes will read in sensor data while wolf_vision reads in vision data. This data is then read by wolf_control nodes. The wolf_control nodes will decide where to go and then issue commands to the movement system. The movement system (which is in wolf_control) will then talk to wolf_serial to drive the motors and actually move the robot.

Hopefully this small breakdown gives you an idea of which code goes where in the software stack. Now lets go into more detail about how each of these systems work.

wolf_serial

The Pixhawk and Jetson communicate over a serial communication protocol known as MAVLINK. This is a complex communication link that you do not need to understand in detail. Instead we use the ROS package "mavros" to handle this communication for us. mavros exposes several topics that contain all the needed sensor data and motor controls. If you are working with pixhawk.py, you should learn more about mavros. This can be done by looking at its official documentation.

Outside of pixhawk.py mavros topics should be avoided. All of the needed topics should be republished by pixhawk.py (or put into TF2 frames) to provide a hardware agnostic interface for the rest of the software.

Importantly pixhawk.py listens to cmd_vel, which tells the bot which direction to move in (relative to its current orientation). It publishes the robots current orientation in the "base_link" TF2 frame. SW8 can only know its rotation and depth in absolute terms, so lateral movement is not kept track of in this frame.

gazebo.py mirrors the functionality of pixhawk.py but provides interfaces for the simulator rather than the real Pixhawk.

wolf_control

The main topic you should know about is "wolf_control/goal"

• Sets a setpoint for the sub to move towards

  • angular x y z are in terms of the subs magnetic compass and setting these will make the pose controller align the sub to this magnetic heading
  • linear z is in terms of depth below surface, and setting it will cause the sub to submerge to the given depth
  • linear x,y act as a speed vectors and exist in terms of "world" coordinates, an absolute reference frame (the "odom" frame in TF2). These values should generally not be set above 0.3, and control the speed and direction the sub travels in.

  mission.py is the current mission code for the robot and contains a simple state machine to go through the RoboSub competition. This will be greatly expanded upon in the coming years.

  monitor.py is a TUI (terminal UI) program that allows you to take manual control of the robot for testing purposes. It shows how to use it upon launching and is fairly self explanatory if you've read the rest of this guide.

wolf_vision

this is under active construction but the idea is there is a node per vision target. The node reads in an image ROS topic from a camera_forwarder node (which takes openCV images and turns them into a ROS topic). It then finds the target on the screen, converts it into some sort of world space coordinates and publishes it as a TF2 frame. This is what gate_detect.py does for the gate target and it can be used as an example of this type of node.

wolf_bringup

This has several launch files that are useful. The ones you should care about are:

• run_seawolf8.launch
  • starts the real robot and runs the mission
• simulate_mission.launch
  • simulates the bot in a RoboSub environment and runs mission code
• simulator_seawolf8.launch
  • simulates the bot with no mission, useful for debugging with monitor.py