usu-robosub / submarine

See us on https://gitlab.com/usu-amr

This repository contains the software for the second generation of Poseidon, USU's latest autonomous submarine. This submarine is the third generation of our submarine, built by the mechanical, electrical, and software engineers at Utah State University. The quality of Poseidon sets it apart from previous generations of submarines. Poseidon contains cutting edge hardware, has an easy to maintain design, and cleaner code.

Setup

The setup script is for linux based systems with apt-get. The script also requires sudo privileges to run some commands.

Laptop / Desktop

Just the Source Code

Want to take a look at the project's source code? You won't be able to compile the tests or run the included applications. Run to following command.

git clone https://github.com/USU-Robosub/submarine.git

Development

Want to run all the submarine's code on your laptop? You will need some extra software. Use the following command to download the repository, and setup your development environment automatically.

wget -qO- https://raw.githubusercontent.com/USU-Robosub/submarine/develop/scripts/setup.sh | bash -s -- -rcja

If you already have the repository downloaded, use the following command.

bash submarine/scripts/setup.sh -cja

Development + Vision

Want to test the submarine's vision code? Use the following command to download the repository, and setup your development environment automatically. This will take much longer than a normal development install.

wget -qO- https://raw.githubusercontent.com/USU-Robosub/submarine/develop/scripts/setup.sh | bash -s -- -rcjav amd

If you already have the repository downloaded, use the following command.

bash submarine/scripts/setup.sh -cjav amd

Note: Run the above command as is. Don't use a different path. New directories will be created for some of the dependancies and we don't want them to be created in the repository.

Submarine's On Board Computers

Main Raspberry PI

Use the following commands to setup a Raspberry PI to be used as the main computer.

wget -qO- https://raw.githubusercontent.com/USU-Robosub/submarine/develop/scripts/setup.sh | bash -s -- -rcjap9
bash submarine/scripts/add_cloud9_to_pm2.sh
bash submarine/scripts/add_[submarine's name]_to_pm2.sh

Vision Raspberry PI

Use the following commands to setup a Raspberry PI to be used for vision processing.

wget -qO- https://raw.githubusercontent.com/USU-Robosub/submarine/develop/scripts/setup.sh | bash -s -- -rcp9v pi
bash submarine/scripts/add_cloud9_to_pm2.sh
bash submarine/scripts/add_[submarine's name]_vision_to_pm2.sh

submarine's Issues

Generic Sensor Interfaces (C++)

Interfaces should be created for generic sensors e.g. accelerator, gyroscope, vision (template matching). This includes what units the sensors should be in e.g. template matching: position of object [-1, 1] width and height centered in the middle.

Requirements

[explain the concrete changes to the project needed for your feature, example below]

• Add a "Delete" button to the dataset management page.
• Non concrete change: Create system for showing messages to user.
• Add delete function to dataset interface.

Other thoughts

[explain any other ideas or thoughts you have about this feature.]

Hub blocks when excessive data is in buffer

Bug report

There is a possible/likely situation where the Hub class can freeze.

Context

utils/cpp/Comm::Hub

Process

1. Continually send data to port that the hub is attached to.
2. Run hub.poll()
3. The hub will freeze as the bridge attempts to generate a very large queue of messages.

Expected result

The hub should only process a set number of messages per call to hub.poll(). This will allow other operations to be done between updates.

Current result

The hub will not process any messages until the data stream has paused or stopped.

Possible Fix

Add a limit to the number of messages a bridge will return on a call to bridge.receive(). This should be a part of the Bridge interface. Preferably is would be passed to the bridge.receive() function.

OpenCV Template Matcher (C++)

Create object that wraps the OpenCV template match function. This object should not load images from cameras or disk. Images will be provided to the object on a continual basis.

Requirements

[explain the concrete changes to the project needed for your feature, example below]

• Add a "Delete" button to the dataset management page.
• Non concrete change: Create system for showing messages to user.
• Add delete function to dataset interface.

Other thoughts

[explain any other ideas or thoughts you have about this feature.]

Serial port disconnect on leaving scope

New feature request

Currently the Comm::Serial::Port class does not close the Linux serial port when it is destroyed.

Requirements

• Serial port is closed when an object is destroyed.

Basic Hub on Arduino

New feature request

The Arduino needs a basic hub to receive messages over serial.

Requirements

• Add a Hub class to the Arduino project.

The Hub class

• has the method void Hub.poll() that reads a single event from serial and executes the corresponding controller. This should block.
• the Hub.poll() method checks that the first long read from serial is 0000. If it is not the message has been corrupted and the hub should execute the controllers[0] controller to perform a buffer purge.
• has the method void Hub.emit(long name, long* data, long length) that writes the data to serial.
• should have a constructor that accepts an array of Controller.

Other thoughts

Hub interface:

class Hub{
public:
  Hub(Controller* controllers);
  void poll();
  void emit(long name, long* data long length);
private:
  long readOneLong();
  writeOneLong(long value);
} ;

Controller interface:

class Controller{
public:
  virtual void execute(Hub* hub, long* data, long length);
} ;

Event message protocol reference:

[null] [name] [length] [data #1] [data #2] [data #3] ...
0000 001A 0003 04A8 1321 8765

Javascript TCP Hub

The utils/javascript project needs a TCP Hub. The hub should be based of the design of the C++ TCP hub.

Requirements

• Hub object added to utils/javascript project
• Hub allows sending events over TCP
• Unit tests added

Other thoughts

Hub does not need to be a JavaScript class.

IMU Device (C++)

Create an object that communicates with the Arduino 9-axis IMU (using a Hub). The object should implement the generic sensor interfaces it supports.

Requirements

[explain the concrete changes to the project needed for your feature, example below]

• Add a "Delete" button to the dataset management page.
• Non concrete change: Create system for showing messages to user.
• Add delete function to dataset interface.

Other thoughts

[explain any other ideas or thoughts you have about this feature.]

TCP stream strange on embedded

Bug report

Strange behavior on embedded devices.

Context

feature/tcp
utils/cpp/Comm::TCP::Stream

Process

1. bash test.sh

Expected result

Tests pass on Travis-CI.

Current result

Raspberry PI

/home/pi/submarine/utils/cpp/src/Comm/TCP/Stream.spec.cpp:58: FAILED:
  REQUIRE( buffer == std::string("a,abc,") )
with expansion:
  "a,abc,▒~a,abc," == "a,abc,"

Beaglebone

/home/debian/submarine/utils/cpp/src/Comm/TCP/Stream.spec.cpp:23: FAILED:
  REQUIRE( buffer == std::string("a|abc|") )
with expansion:
  "a|abc|" == "a|abc|"

/home/debian/submarine/utils/cpp/src/Comm/TCP/Stream.spec.cpp:58: FAILED:
  REQUIRE( buffer == std::string("a,abc,") )
with expansion:
  "a,abc,▒" == "a,abc,"

Possible Fix

Unkown

Arduino code needs to be split into a utils project

All Arduino code not directly associated with Poseidon should be moved to a utils/arduino project.

Requirements

• Move generic code to new project.
• poseidon/arduino includes the moved code.
• poseidon/arduino still builds correctly.

Other thoughts

The new project does not need to be a PlatformIO library.

Kill Switch Controller (Arduino)

Requirements

• add void enable() to controller interface (this should allow movement)
• add void disable() to controller interface (this should stop any movement)
• added to submarine/utils/arduino/Hub/src/Controllers
• implements the Controller interface
• ignores all execute commands
• attaches an interrupt handler
• when an interrupt is called, an event should be sent to the interrupt handler using the provided hub
• the event should be [ 3 /* interrupt id */, 1 /* new state */ ]
• call disable() on all controllers when interrupt is disabled
• call enable() on all controllers when interrupt is enabled
• send an event on start

Other thoughts

#define BUTTON_1 8 // arduino pin numbers

#define INTERRUPT_HANDLER 10 // c++ system to send it to

auto controller = new Controllers::KillSwitch(BUTTON_1, INTERRUPT_HANDLER, controllersToStop);

// create Hub

controller.use(hub);

Drive Train (C++)

Create an object that connects to the Arduino (using a Hub). The object should have methods to move forward, turn, and dive. Motor powers should be between [-1, 1].

Requirements

[explain the concrete changes to the project needed for your feature, example below]

• Add a "Delete" button to the dataset management page.
• Non concrete change: Create system for showing messages to user.
• Add delete function to dataset interface.

Other thoughts

[explain any other ideas or thoughts you have about this feature.]

Web App

The utils/javascript project needs to provide a web app that can be used by different robots.

Requirements

• A web app can be spawned
• The web app allows controlling the robot using commands

Other thoughts

The robot will need to provide a list of commands that the web app can run.
Sokect.IO is recommended for communication between the web app and the robot.
Web app should be able to create new commands/scripts.

IMU Controller (Arduino)

Create IMU controller object for our 9-axis IMU. Should support magnetometer, accelerometer, gyroscope, temperature sensor, and pressure sensor.

9-axis IMU = MPU-6050

The value of the sensors should be cached

Requirements

[explain the concrete changes to the project needed for your feature, example below]

• Add a "Delete" button to the dataset management page.
• Non concrete change: Create system for showing messages to user.
• Add delete function to dataset interface.

Other thoughts

[explain any other ideas or thoughts you have about this feature.]

Kill Switch Object (JavaScript)

Requirements

• listens to a Hub for an interrupt event
• provides a callback creator on(callback)

Other thoughts

killSwitch(hub).on(function(enabled){
  if(enabled){
    // kill switch has been enabled
  }else{
    // kill switch has been disabled
  }
})

Remote (JavaScript)

Create an object with the following interface:

(void function(["", "", "", ...])) Remote.set("[target]")
This function should send a request to the attached Hub.


(promise function(["", "", "", ...])) Remote.get("[target]")
This function should send a request to the attached Hub. It should also attache a handler to the hub that license to a return value.

Requirements

[explain the concrete changes to the project needed for your feature, example below]

• Add a "Delete" button to the dataset management page.
• Non concrete change: Create system for showing messages to user.
• Add delete function to dataset interface.

Other thoughts

[explain any other ideas or thoughts you have about this feature.]

Bridge can split messages

Bug report

The Bridges can fail to read a message if it lands on a buffer boundary.

[0|message name|]...[3|data|test|message|] -> [0, message name, undefined/0]

Context

utils/cpp/comm and utils/javascript/comm

Process

1. Use a Hub to send a large message
2. Receive the message with a very low buffer size on the Port
3. The Stream will correctly wait for entire strings to be completed
4. The Bridge will only read part of the message, and error on the rest

Expected result

The Bridge should wait for the entire message to be received.

Current result

The Bridge will only read part of a message if it lands on a buffer boundary.

Kill Switch Subsystem (C++ System)

Requirements

• listens to serial hub for interrupt message (see #37)
• when an event is received send it to the JavaScript using a TCP hub
• send the event [ "killSwitch", "1" /* state */ ]
• has a property to check state of kill switch bool enabled()

Other thoughts

auto subsystem = new KillSwitch(serialHub, tcpHub);
if(subsytem.enabled()){
  // kill switch is enabled
}

TCP port does not guarantee that all data is written

Bug report

The TCP port can lose data.

Context

Utils/cpp/Comm::TCP::Port

Expected result

A call to push(buffer, length) is expected to completely send all the data in the buffer to the length provided.

Current result

Calls can result in only a partial amount of data being sent.

Possible Fix

Use the return sizes from write(...) to continue to send data.

Serial port does not use the value returned from writes and reads

New feature request

The Serial::Port class does not use the values returned from the POSIX read and write calls. There can be a problem were the incorrect number of bytes are read.

Requirements

• Added loop to keep asking for more bytes until requested limit reached.
• Use error code to put serial port into an error/disconnect state.

Motors need to be switched to new communication stack

New feature request

The motors/thrusters were originally set to use the original communication stack. Then they were changed to an observable communication stack. However, that was scrapped for the current minimal stack.

Context

utils/cpp/Device::Motor

Requirements

• The Thruster class is not needed, and should be removed.

The Motor class

• is designed to use a Comm::Hub<int> for setting motor speed.

• has the method void Motor.speed(double) to set the speed of the motor.

• bounds the speed to be between the Math::Range passed in to the constructor. Math::bound(...) should be used

• maps the speed from [-1, 1] to be between the Math::Range passed in to the constructor. Math::map(...) should be used.

• emits an event on the given Comm::Hub<int> with the name int provided to the constructor, and contains just the mapped and bounded motor speed as data.

• has the method double Motor.speed() to get the speed of the motor.

Example of a possible Device::Motor constructor.

Device::Motor::Motor(Comm::Hub<int>* hub, int name, Math::Range range);

Add OpenCV to Raspberry PI

OpenCV needs to be added to the poseidon/raspberryPI project.

Requirements

• OpenCV added to cmake.
• #include <opencv2/opencv.hpp> can be used to include OpenCV components.
• OpenCV install added to Travis-CI poseidon/raspberyPI build.