search

CWRUbotix / rov-25

Software for the CWRUbotix MATE ROV 2024-25 season
Apache License 2.0
1 stars 0 forks source link
arduino mate-rov python3 robotics ros ros2

readme

MATE ROV 2024-25

Continuous Integration pre-commit.ci status Apache License Ruff

Table of Contents

  1. Setup
    1. Linux
      1. Bare Metal
      2. Docker
    2. Windows
      1. Dual Boot
      2. WSL
      3. Docker
    3. macOS
      1. Docker
      2. UTM
  2. Test Your Environment
  3. Run Our Code
  4. Directory Structure
  5. Documentation Structure

Setup

If you have GitHub Desktop, click the green Code button above, then Open with GitHub Desktop.

If you have the Git CLI, start by opening up a terminal, navigating to where you want the code to be saved, and entering the following command:

git clone --recurse-submodules git@github.com:CWRUbotix/rov-25.git

If you've never contributed to a git repository before, you might receive an error message saying you don't have access. In that case visit this tutorial to set up SSH for local GitHub access.

After cloning the code, we need to set up our IDE: VSCode. If you already have it, great. Otherwise follow this tutorial. We recommend installing the mypy and autoDocstring VSCode extensions. Our autoDocstring settings are Docstring Format: Numpy and Start On New Line: Start docstring on new line.

Now select the guide below that fits your operating system. Some operating systems have multiple options. Here are our recommended installation options:

Once you're finished setting up, go to the Test Your Environment section to confirm everything's working, then Run Our Code!

Linux

Bare Metal (Ubuntu only)

To run the install script, open the repository with VSCode. Then use F1 or ctrl+shift+p to open the command bar and select Tasks: Run Task. Then from the Task selection choose [SETUP] Surface Environment. This will install ROS and all our dependencies.

Docker (all distros, probably)

Start by installing docker engine from here.

Set your permissions based on this guide.

Restart.

Then install the Dev Containers VSCode extension.

To open the container, open the repository with VSCode. Then use F1 or ctrl+shift+p to open the command bar and select Tasks: Run Task. Then from the Task selection choose Docker Rebuild. This will build and run the docker container. Make sure to choose ROV Linux for which type to run (you might have to wait a while for things to download before this option is presented at the top of your screen).

Now you should be in your Docker container in VSCode.

To reopen the container after you close it, go to File > Open Recent > /stuff/rov-25 [Dev Container]

For gui apps run xhost + local:docker before launching docker or add to .bashrc.

Windows

Dual Boot

Creating a dual boot allows you to install two different operating systems to your device. You can then switch between them when your computer boots. Once you have a dual boot set up, this is by far the easiest and most error-free option. You'll also find that many CS courses are easier once you have easy access to a full Linux OS.

This is a guide for creating a dual boot. Note that there a bootable USB drives available in the bay for Ubuntu 24.04, so you can skip to the "How to Install Linux for Dual Boot" section.

You might need to disable secure boot, but try without doing that first. If you get secure boot errors later in the installation, that might be because you chose to install third party drivers.

Once you have Ubuntu set up, follow the Bare Metal (Ubuntu only) instructions in that OS.

WSL

Follow this guide to install WSL.

After WSL has been installed follow this guide to get VSCode and WSL to properly communicate and navigate to the rov-25 folder.

Then run the install script.

To run the install script, open the repository with VSCode. Then use F1 or ctrl+shift+p to open the command bar and select Tasks: Run Task. Then from the Task selection choose [SETUP] Surface Environment. This will install ROS and all our dependencies.

Docker

Start by installing docker from here.

Then install the Dev Containers VSCode extension.

To open the container, open the repository with VSCode. Then use F1 or ctrl+shift+p to open the command bar and select Tasks: Run Task. Then from the Task selection choose Docker Rebuild. This will build and run the docker container. Make sure to choose ROV Windows for which type to run (you might have to wait a while for things to download before this option is presented at the top of your screen).

Now you should be in your Docker container in VSCode.

To reopen the container after you close it, go to File > Open Recent > /stuff/rov-25 [Dev Container]

To add your Git SSH keys into the container follow this guide.

If this doesn't work try running ssh -v git@github.com

If get_agent_identities from the prior command is empty you will likely need to download a newer version of OpenSSH from here. Download the .msi file. Once download double click to update it. You might need to do the previous step again.

To get GUI support inside Docker, download this.

Then run XLaunch from the Windows Start Menu. Make the settings look like this:

Screenshot of the settings for Xlaunch

Then open up Command Prompt and type ipconfig.

Then in the terminal of the docker container use export DISPLAY={IPv4 of WSL}:0.0 where the IPV4 is from the ipconfig command.

macOS

Docker

First, install Docker from here.

Then install the Dev Containers extension inside VSCode.

To get GUI support inside Docker, first install homebrew.

Then, from a terminal, run the following:

brew install socat
brew install xquartz

Next, configure XQuartz with

open -a Xquartz

Go to the settings menu and make the Security section look like this:

image

You can close out of the XQuartz terminal now, but you should always see the XQuartz icon in your dock whenever you want a GUI to display from inside the Docker container.

To open the container, open our repository with VSCode. Then use F1 or command shift p to open the command bar and select Tasks: Run Task. Then from the Task selection choose Docker Rebuild. This will build and run the docker container. Make sure to choose ROV macOS for which type to run (you might have to wait a while for things to download before this option is presented at the top of your screen).

Now you should be in your Docker container in VSCode.

To reopen the container after you close it, go to File > Open Recent > /stuff/rov-25 [Dev Container].

Note for folks who eventually try running the simulation: XQuartz might not be able to support OpenGL applications like our simulation. Apparently there's a flag to enable OpenGL rendering as late at XQuartz 2.7.11, but that version might be too old to run on your Mac.

UTM

BEWARE! We haven't fully tested this option.

UTM is a virtualization software. It allows you to create "virtual machines" (sometimes called "guests") which can run other operating systems. Visit UTM and hit "Download from GitHub" (downloading from the App Store costs money).

As mentioned in this StackExchange, if you have issues getting a network connection with either of these options, try changing the network mode of your virtual machine in its settings menu (the icon with sliders on the top right when the virtual machine is selected).

If you have Apple silicon (an M1, M2, etc.):

If you have a different (i.e. Intel) CPU:

Test Your Environment

After setting up your environment, open a terminal (make sure it's in VSCode if you're using Docker) and run an example publisher node:

ros2 run demo_nodes_cpp talker

Open a second terminal and run an example subscriber node:

ros2 run demo_nodes_py listener

If the listener receives the messages published by the talker, then ROS was successfully installed on your system.

Run Our Code

Perform one of these options in VSCode to build the codebase:

The magic of symlinks should mean you won't need to build again for most things, but you'll need to build every time you change a package's setup.py or anything in the rov_msgs package.

If that works, source your workspace to tell ROS to look for packages in your current workspace:

. install/setup.sh

Then try launching our GUI:

ros2 launch surface_main surface_all_nodes_launch.py

Unit tests

To test, perform one of these options in VSCode:

The runs the tests and pipes the output to the terminal. To test pi_main make sure to type your password into the terminal after doing either option..

Installing the mypy extension should help enforce our linters.

Upgrading Environment

If you are upgrading to a newer ROS version make sure to remove source /opt/ros/$PREVIOUS_ROS_DISTRO/setup.bash. If you are using Docker you can simply build the new container and delete the old one.

Directory Structure

All packages to be installed on the surface computer live in the surface directory.

All packages to be installed on the pi compute module live in the pi directory.

All packages to be installed on the float live in the float directory.

Namespaces

All nodes running on the pi will be in the pi namespace.

All nodes running on the surface will be in the surface namespace.

Any topics or services communicating across will be renamed first into the tether namespace.

Picture of rqt with namespaces

Documentation Structure

Documentation will take place at 3 levels:

def __init__(self, srv_type: SrvType, topic: str, signal: pyqtBoundSignal,
                 timeout: float = 1.0, expected_namespace: str = '/surface/gui'):
        """
        _summary_

        Parameters
        ----------
        srv_type : SrvType
            _description_
        topic : str
            _description_
        signal : pyqtBoundSignal
            _description_
        timeout : float, optional
            _description_, by default 1.0
        expected_namespace : str, optional
            _description_, by default '/surface/gui'
        """

Axis Orientation

For the ROV: