auv

auv is the vehicle abstraction library for JHU/APL's Waterbear AUV, which includes code for actuators, sensors, navigation, and flight control loops. It is expected that this project would be used as a dependency for developing higher-level mission code and/or autonomy for AUVs.

This library is generally decoupled from the initial vehicle hull it was developed on, and should be largely adaptable to other autonomous underwater vehicles.

The following is example code for running the vehicle at a specified depth and heading.

use auv::config::AuvConfig;
use auv::auv::{Auv, Active};
use std::time::Duration;

fn main() -> Result<(), auv::Error> {

    let mut auv: Auv<Active> = AuvConfig::from_toml("Auv.toml").build()?.enable()?;

    // Manually set the duty cycle on the motor (could also use `Speed::Measured` or `Speed::Estimated` modes)
    auv.controller().speed().setpoint(Speed::RawDutyCycle(0.0));
    // Set the target heading to 45 degrees in the compass' reference frame
    auv.controller().yaw().setpoint(45.0);
    // Set the target depth to be 1.0 meters below the surface
    auv.controller().depth().setpoint(1.0);
    // Run the vehicle for 30 seconds while the internal flight controller maintains the specified setpoints
    auv.navigate(Duration::from_secs(30));
    // Vehicle hardware will gracefully shutdown upon program completion (due to `Drop` impl on hardware interfaces)
    Ok(())
}

Development Builds

Building this code requires a Rust nightly toolchain. First, install Rust. Then, after following the instructions to update the PATH variable in your shell, you can install the nightly toolchain via:

$ rustup toolchain install nightly
$ rustup default nightly # Actually activate the nightly toolchain

Once the nightly toolchain is installed, this code can be built using:

$ cargo build --all

In addition, a general code quality Continuous Integration (CI) run should be run prior to each commit via

$ cargo run -p ci

This will do checks on code formatting, documentation, build all examples, run tests, etc.

Complete developer documentation can be built and viewed via

$ cargo doc --open
# Documentation coverage can be calculated using the following command
$ RUSTDOCFLAGS='-Z unstable-options '--show-coverage cargo doc --no-deps

Device Feature Conditional Compilation

This library supports conditional compilation for various optional device payloads such as the Blue Robotics Ping2 echosounder. Please refer to the Cargo.toml file to see what devices are available on what features.

$ cargo build # Only use default features
$ cargo build --features ping # Compile with specific support for the example Ping2 echosounder
$ cargo build --all-features # Compile with support for all optional devices

Cross-Compile/Deployment Builds

Waterbear vehicles use the Odroid-C4 single-board computer as an onboard computer. For cross-compiling to the Odroid-C4, use the cross tool (requires container engine such as Docker or Podman), which can be installed using

$ cargo install cross

Specific example binaries can be built for the aarch64 target specified in this project's Cross.toml file using and copied to the deployment target using

$ cross build --release --example <example-name>
$ rsync -auv --progress target/aarch64-unknown-linux-gnu/release/examples/<binary-name> odroid@<ip>:~ 
# If developing with local external deps, `cross` maybe become a bit unhappy but was solved in # https://github.com/cross-rs/cross/pull/684
# w/example workspace at https://github.com/cross-rs/test-workspace
$ cd ../ # Or wherever your out-of-`auv`-workspace package is located, since `cross` needs to have ownership of that path
# Then explicitly point out the location of the `auv` manifest (`Cargo.toml`)
$ cross build --manifest-path ./auv/Cargo.toml

If you haven't logged into the vehicle before, you may need to copy an ssh key before performing rsync commands:

$ ssh-copy-id auv@<ip>

Logs and Post-Processing

By default, logs will be written to a logs/ directory in the form of a <timestamp>.sled file containing all values that have been published on the vehicle message bus. A utility for helping to post-process these logs has been made available under tools/log-processing, and can be run by copying those logs onto the host machine and running

$ cargo run --release -p log-processing -- <log-directory>

which should result in a new <timestamp> directory (i.e. a directory with the base timestamp name, but without the .sled suffix) being created that contains CSV files for supported topics.

Preliminary support for tracing has been made available, with example code available under the actuators2 binary supporting JSON message output. However, outside of major warnings, most data available under LogLevel::INFO and LogLevel::TRACE does not appear to be of much value at the moment, as only the Postcard-serialized data packets are currently available to be viewed via meadow's logging spans.

Software Bill of Materials & Auditing

A Software Bill of Materials ("SBoM") for this library can be generated using the Rust CycloneDX plugin for Cargo via

$ cargo install cargo-cyclonedx
$ cargo cyclonedx

Scripts

Several convenience scripts for managing deploying artifacts to remote hosts (typically vehicle flight computers) and pulling/post-processing logs following mission runs are available under scripts/. It's expected that some customization may be required to adapt these scripts for new vehicles.

License

auv is licensed under the Mozilla Public License, Version 2.0 (MPL-2.0).