Book Layout

This "book" contains documentation from all subteams. It aims to organize known information about all kinds of topics so they are easier to learn about and pass down.

Each section of the book represents a subteam. Members of each team should document important operations, hardware, and topic that they work on.

Sections

Autonomous

The Autonomous subteam works on various different types of procedure for the rover. Implementing these procedures allows the rover to do tasks intelligently.

Mechanical

Electrical

Science

Adding to the Book

Please go ahead and follow the New Page Guide! It'll guide you through getting the book on your computer, creating your page, and putting it online!

New Page Guide

This book is composed of many different pages from a lot of different people!

If you want to contribute, you only need to make a new file and connect it to the book.

Downloading the Book

To contribute to the book, you'll need to download the book. Go to your Documents folder in your terminal, then download its git repository:

~ $ cd Documents

~/Documents $ git clone https://github.com/Sooner-Rover-Team/soro-documentation.git
Cloning into 'soro-documentation'...
remote: Enumerating objects: 269, done.
remote: Counting objects: 100% (269/269), done.
remote: Compressing objects: 100% (161/161), done.
remote: Total 269 (delta 121), reused 217 (delta 85), pack-reused 0
Receiving objects: 100% (269/269), 1.10 MiB | 1002.00 KiB/s, done.
Resolving deltas: 100% (121/121), done.

~/Documents $ cd soro-documentation

~/D/soro-documentation $

Making a New Page

To make a new page, open up a terminal:

~D/soro-handbook $ pwd
~/Documents/soro-handbook/(somewhere)

~D/soro-handbook $ touch new-page-name.md

~D/soro-handbook $ code new-page-name.md
Opening VSCode...

You should now have a new page! Now, let's connect it to the rest of the book with SUMMARY.md:

~ $ cd ~/Documents/soro-handbook

~/D/soro-handbook $ code SUMMARY.md
Opening VSCode...

Now, you just write where your page is!

...
# Autonomous

- [Usage](Autonomous/Usage.md)
- [Hardware](Autonomous/Hardware/README.md)
- [My New Page](new-page-name.md) <!--- new page here -->
...

Submitting Changes

We use git to manage new versions of the book. There's not enough space to teach git here, but you can refer to Git - The Simple Guide and W3's Git Tutorial for some tips.

Please make sure to use a PR (pull request) for significant changes! :)

Usage

Take a look at one of the sections to find what you're looking for. If you can't find something that needs to be documented, complain here until someone does something.

Sections

Software

The software section documents how (and when) to use software. Preferably, it should also link to automatic documentation like rustdoc.

Hardware

In the hardware section, you'll find documentation related to hardware components from the autonomous side of things.

There could be duplicates in other subteam sections, but they may be tailored to different needs.

Guides

Here, you'll find general guides about how to do useful things. They don't have to be related to your projects - just something that's helpful to share.

Hardware

Autonomous hardware often has to do with making the Rover do new things! For example, by using special cameras that reflect human vision, we can more accurately determine location and navigate the world!

Documenting new hardware is easy! Just do the following:

  1. Research something you want!
  2. Make a new page!
  3. Go ahead and fill in some reasons why you want to use this! Give some information about the device and some links to resources about it.
  4. If it links to ROS, tell Tyler so he can be excited

GPS-RTK2

The GPS-RTK2, sometimes called the ZED-F9P after its receiver chip, is a GNSS (global navigation satellite system) board that works to provide wide locational data. It supports RTK for error-correction, allowing it to pinpoint location down to around 10mm of accuracy.

Setup

To use the board, you'll need to connect up an antenna. Currently, we're using a Swift GPS500 to receive our GPS data, but it may or may not work correctly. Sparkfun's Hookup Guide is pretty good, so take a look there!

Software

While you can use proprietary software to view the information given by the board, it's probably a better idea to stick to modern, open source software instead.

In particular, using gpsd in the background along with gpsmon to display the data graphically in your terminal will help you see how things are working.

To install gpsd and gpsmon, use your package manager to install its package(s).

Fedora, CentOS, and RHEL: sudo dnf install gpsd

Ubuntu, Debian, and Pop!_OS: sudo apt install gpsd

macOS: brew install gpsd

Windows: Use WSL, bud. I suggest either Fedora or Ubuntu like above :)

Connecting

To connect to the RTK2 with gpsd, run these commands:

$ sudo gpsd /dev/ttyACM0 -F /var/run/gpsd.sock
# it probably won't say anything
$ sudo gpsmon /dev/ttyACM0
# and it'll go into a little terminal ui

You may have to replace /dev/ttyACM0 with /dev/ttyUSB0, or something else...

Jetson Nano

Summary

The Jetson Nano is a small computer designed by Nvidia for AI and machine learning applications. Its a low power usage machine meaning that our battery systems are well established. We are already employing this machine as of 2/27/23.

Technical Specifications

All technical specifications can be found here at: JetsonSpecs

Software

Software

Autonomous software usually has to do with controlling and linking different parts of the Rover to work together!

If you make a new application, please consider documenting it in a new page here! Just follow the New Page Guide.

Sender-Grabber Protocol (SGP)

The Sender-Grabber Protocol is a list of Promises1 that the Rover (sender) and RoverGUI (grabber) must keep when exchanging commands and information.

While the Protocol works as a way to transmit information like commands, it isn't expected to be used with a video stream itself. Please encode images/video in freely-available formats which are well-designed already, like WebP and AV1.

What's going on?

Promises describe the details of how data should be sent and recieved, with each Call acting as a direct implementation of a certain Promise. In other words, you write the code to keep your promises!

Each Call must be compatible on both ends of the tunnel. Finally, the Background represents additional details of the protocol.

Prototyping

Before we settle on any Promises, we need to take into consideration that our needs will change in the future. For this reason, the Background details should be loose. You can see a full list of some important considerations here.

Initial Goals

However, just keep in mind some initial goals for now. We need Promises for:

  • Changing the FPS
  • Stopping a camera
  • Starting a camera
  • Changing cameras
  • Encoding/quality options (oh boy)

Keep in mind that having these options up here require documenting them as you add them into your programs. If you change the way encoding works, and it's not compatible with the protocol, you'll need to document your changes and make the protocol aware of that.

I highly suggest researching libraries first, then sticking to your choices.

Future Ideas

Some other useful ideas could be around:

  • The internet connection
  • Remaining battery
  • Current operation/modes
  • Settings
  • User profiles
  • Connected devices (controller status)
  • Error logging

It's not a good idea to implement these yet, but it'd be nice to get some brainstorming going.

Versioning

To keep everything simple, we're just going to use Semantic Versioning. If you're new to this, npm has a great guide which is super easy to read and understand!

In general, the Versioning information only stands to disallow older programs from talking to the Rover and returns an error when we try.

This should help to avoid a lot of confusion down the line. Always aim to keep both the Python and Rust implementations up-to-date with each other.

Calls

// TODO :)

Environment

// TODO :)

Changelog

  • 0.0.0: Nothing
    • The base release of the protocol.
    • Nothing has been added, and there is no protocol!
      • Very simple release

Footnotes

1

Promises in SGP are not related to those in Javascript or other languages. They're "promises" in the everyday sense of the word. ex: "I promise that I will change cameras."

Guides