Autonomy Software Binder

Central engineering reference and operations manual for the MRDT Autonomy Software.

View the Project on GitHub MissouriMRDT/Autonomy_Software

Return to RoveSoDocs Guides for Today, Tomorrow, and Forever.

Quick Start and Operations Manual

This guide covers the exact steps required to set up, build, test, and run the Autonomy Software, whether developing inside the Dev Container, simulating with Unreal Engine RoveSoSimulator, or deploying directly to physical rover hardware.

1. Setting up the Dev Container Environment

The Autonomy Software project uses Docker and Visual Studio Code Dev Containers to ensure consistent toolchains and dependencies across development machines and the onboard Jetson computers.

Prerequisites

Building and Attaching

  1. Clone the repository recursively to populate submodules (including RoveComm): 
    git clone --recursive https://github.com/MissouriMRDT/Autonomy_Software.git
  2. Open the repository root in VSCode: 
    code Autonomy_Software
  3. When prompted in the lower-right notification, select Reopen in Container.
    • If the prompt does not appear, open the Command Palette (Ctrl + Shift + P or Cmd + Shift + P), type Dev Containers: Rebuild and Reopen in Container, and press Enter.
  4. Docker pulls the preconfigured image and initializes the workspace. First-time initialization may require several minutes to complete.

Container Environment Details

The container environment provides:

[!TIP] Comprehensive Installation & Contribution Documentation

  • Full Installation Guide: For native Linux configuration, bare-metal toolchains, and NVIDIA Jetson deployment steps, refer to INSTALL.md.
  • Contributing & Git Workflow: For branch naming conventions, pull request workflows, review procedures, and C++ code style requirements, see CONTRIBUTING.md.
  • Team Documentation: Broad team-wide architecture guides and subsystem documentation are hosted on the MRDT Documentation Portal and mirrored in the MissouriMRDT/RoveSoDocs repository. Internal packages and datasets are hosted on the MRDT GitLab Organization.

2. Building the Code

The build system is orchestrated using CMake.

[!IMPORTANT] GCC 10.0 is strictly enforced by CMakeLists.txt via gcc -dumpversion. Building with other GCC versions will result in a fatal configuration error.

Standard Build (Release Mode)

Always use Release mode on the rover and during competitive runs for maximum compiler optimization (-O3 equivalent) and loop vectorization:

mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

To limit memory usage during parallel compilation, CMake Unity builds are enabled by default (CMAKE_UNITY_BUILD ON with batch size 8). You can adjust parallel compile jobs via:

make -j4

Simulation Mode Build

When testing without physical rover hardware, compile with BUILD_SIM_MODE=ON:

mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SIM_MODE=ON ..
make -j$(nproc)

In simulation mode:

Unit and Integration Tests Build

To compile the Google Test suites:

mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS_MODE=ON ..
make -j$(nproc)
ctest --output-on-failure

Optional test suites for LiDAR and GeoPlanner require USGS database files and can be enabled with -DENABLE_LIDAR_GEO_UTESTS=ON.

Cleaning the Build Directory

If CMake cache issues occur after switching branches or updating submodules:

rm -rf build/*
cmake -DCMAKE_BUILD_TYPE=Release -B build/
make -C build/ -j$(nproc)

3. Running Autonomy

Executables are written to the build/ directory.

Running on Physical Hardware

cd build
./Autonomy_Software

On launch, the software performs the following initialization sequence:

  1. Initializes the Quill asynchronous loggers and prints the ASCII software header.
  2. Binds RoveComm UDP and TCP sockets (UDP port from manifest, TCP interface IP from constants).
  3. Instantiates board drivers (DriveBoard, MultimediaBoard, NavigationBoard).
  4. Instantiates handlers (WaypointHandler, LiDARHandler, CameraHandler, TagDetectionHandler, ObjectDetectionHandler, StateMachineHandler).
  5. Loads the USGS DuckDB database from constants::LIDAR_HANDLER_DB_PATH.
  6. Instantiates GeoPlanner and starts VisualizationHandler on port 8080.
  7. Starts camera background threads and begins detector pipelines.
  8. Enters the main execution loop in main.cpp.

Running in Simulation

cd build
./Autonomy_Software_Sim

Ensure that the Unreal RoveSoSimulator environment is executing before launching the simulation binary.

4. Interactive Terminal Controls

While Autonomy_Software is executing, the terminal is configured into non-canonical mode, enabling single-keypress diagnostic commands without pressing Enter:

Key Function Output Description
h / H Help Prints the terminal hotkey command summary.
f / F FPS / IPS Stats Prints exact iterations-per-second for all camera, detector, networking, and state machine threads.
p / P Rover Pose Prints current Easting, Northing, Altitude (UTM), and fused compass heading.
s / S Sensor Data Queries the ZED IMU and prints linear acceleration (X, Y, Z), angular velocity, and Euler orientation.
d / D Drive Powers Prints current left and right drive power commands (-1.0 to 1.0).
t / T Tag Detections Dumps total detected ArUco markers, best OpenCV tag ID/distance/yaw, and best Torch tag detection.
m / M Object Detections Dumps total detected props (mallets, bottles, rock picks) with bounding box dimensions, confidence, and classes.
q / Q Graceful Quit Triggers clean shutdown: stops drives, signals state machine abort, saves 3D visualization, joins threads, and exits.

5. Log Management

Text logging is powered by the Quill asynchronous engine, ensuring logging operations never block time-critical control threads.

6. Quick Commands Reference

Action Command
Clean Build Tree rm -rf build/*
Configure Release cmake -DCMAKE_BUILD_TYPE=Release -B build/
Compile All Targets make -C build/ -j$(nproc)
Run Onboard ./build/Autonomy_Software
Run Simulation ./build/Autonomy_Software_Sim
Run Unit Tests cd build && ctest --output-on-failure