Autonomy Software C++

Autonomous Traversal and Object Detection for Rovers in C++

🚀 Introduction

Welcome to the Autonomy Software repository of the Mars Rover Design Team (MRDT) at Missouri University of Science and Technology (Missouri S&T)! This repository contains the source code, documentation, and other resources for developing autonomy software for our Mars Rover. We aim to compete in the University Rover Challenge (URC) by showcasing advanced autonomous capabilities and robust navigation algorithms.

🗂️ Codebase Layout

Here's the overall layout of the Autonomy Software codebase:

Autonomy_Software Codebase Structure

Directory Structure:

algorithms/: Implements core autonomous navigation and perception logic.
drivers/: Interfaces with the Rover’s hardware systems such as the drive board and navigation board.
handlers/: Manages various functional components such as camera, object detection, and waypoint handling.
interfaces/: Manages communication with external hardware components.
states/: Defines state machine behavior for efficient task execution.
util/: Utility scripts and helper functions for development and debugging.
vision/: Processes visual data for navigation and object recognition.
tests/: Ensures code correctness and reliability.
tools/: Miscellaneous development tools and utilities.
external/: External libraries and dependencies.
examples/: Sample code demonstrating specific functionalities.
docs/: Comprehensive documentation for developers and contributors.
data/: Contains various datasets and configurations for testing and analysis.

📖 API Documentation

Our documentation is automatically generated via Doxygen on each commit to the development branch. Ensure you use the correct documentation templates to keep the documentation consistent.

📚 Click here for full API documentation.

🛠️ Getting Started

Before diving into the installation, ensure that your system meets the following prerequisites.

Prerequisites

To build and run the Autonomy Software, you can either set up the necessary dependencies manually on your local system or use our pre-configured Docker environment where everything is preinstalled.

Option 1: Using the Preinstalled Docker Environment (Recommended)

The easiest way to get started is by using our Docker environment. This environment comes with all the required software and dependencies preinstalled, including:

NVIDIA CUDA Toolkit 12.2
CMake 3.30.2
GCC 10
OpenCV 4.10.0
PyTorch 2.2.2
TensorFlow 2.15.0
ZED SDK 4.1
Quill 7.0.0-pre
Google Test 1.15.2
Abseil 20230802.1
GeographicLib 2.3
Git LFS
And more...

This Docker environment is designed to work seamlessly with NVIDIA GPUs and supports both AMD64 and ARM64 architectures.

Option 2: Setting Up Manually on Your Local System

If you prefer to set up the environment manually, make sure your system has the following hardware and software dependencies installed:

Hardware Requirements:
- NVIDIA Graphics Card with CUDA support (required for running GPU-accelerated vision processing)
- Minimum CUDA version: 12.2 (compatible with the NVIDIA graphics card for GPU computation)
- NVIDIA Jetson Devices (JetPack SDK required for ARM64 platforms)
Operating Systems:
- Ubuntu 22.04 or higher (for AMD64 platforms)
- NVIDIA Jetson Devices with JetPack SDK (required for ARM64 platforms)
Required Software:
- CMake 3.24.3 or higher
- GCC 10 or higher (for compiling C++ code)
- Git 2.25 or higher
- Git LFS (Large File Storage) 2.13.0 or higher (for handling large files)
- Python 3.8 or higher (for scripting and utility purposes)
- Doxygen (for generating documentation)
- OpenCV 4.10.0 or higher (required for vision processing)
- CUDA Toolkit 12.2 or higher (or NVIDIA graphics card support)
- NVIDIA JetPack SDK (required for Jetson platforms)
- ZED SDK 4.1 or higher (for stereolabs cameras)
- PyTorch 2.2.2 or higher (for machine learning tasks)
- TensorFlow 2.15.0 or higher (for deep learning tasks)
- Quill 6.1.2 or higher (for logging)
- Google Test 1.15.2 (for testing)
- Abseil 20230802.1 (for additional utilities)
- GeographicLib 2.3 (for geospatial computations)

Now that your system is set up, you can proceed with the installation and build instructions provided in the INSTALL.md file.

🔧 Build Modes

The Autonomy Software project includes various build modes to cater to different development, testing, and deployment needs.

VSCode Run Buttons (Parallel Jobs Customization)

When using VSCode's CMake integration, you can customize the number of parallel jobs used during the build process through the devcontainer.json file. This allows you to control how many jobs run concurrently during the build, optimizing performance.

We recommend setting the number of parallel jobs to no more than half the number of cores available on your system to avoid overloading resources.

To configure this, edit the devcontainer.json file as follows:

{
  ...
  // CMAKE extension settings.
  "cmake.configureOnOpen": true,
  "cmake.options.statusBarVisibility": "visible",
  "cmake.parallelJobs": 8,                          // EDIT THIS LINE
  ...
}

In this example, the "cmake.parallelJobs" setting is set to 8, which is suitable for a system with 16 cores. Adjust this value based on your hardware, ensuring that you stay within half your system’s core count for optimal performance.

Simulation Mode

Simulation mode enables the software to be compiled with simulation-specific features. This mode is disabled by default and is currently configured for integration in the Webots Robot Simulator.

To enable Simulation Mode:

mkdir -p <Autonomy Install Location>/build
cd <Autonomy Install Location>/build
cmake -DBUILD_SIM_MODE=ON ..
make
./Autonomy_Software_Sim

Code Coverage Mode

Code coverage mode compiles the software with flags that enable coverage reporting. This mode is disabled by default.

To enable Code Coverage Mode:

mkdir -p <Autonomy Install Location>/build
cd <Autonomy Install Location>/build
cmake -DBUILD_CODE_COVERAGE=ON ..
make
./Autonomy_Software

Verbose Makefile Mode

Verbose mode provides detailed output during the build process, useful for debugging build issues. This mode is disabled by default.

To enable Verbose Makefile Mode:

mkdir -p <Autonomy Install Location>/build
cd <Autonomy Install Location>/build
cmake -DBUILD_VERBOSE_MODE=ON ..
make

Install Mode

Install mode enables the packaging of the executable for installation. This mode is disabled by default.

To enable Install Mode and package the executable:

mkdir -p <Autonomy Install Location>/build
cd <Autonomy Install Location>/build
cmake -DBUILD_INSTALL_MODE=ON ..
make
sudo make install

Tests Mode

Tests mode enables the compilation and execution of unit and integration tests. This mode is disabled by default.

To enable Tests Mode and run the tests:

mkdir -p <Autonomy Install Location>/build
cd <Autonomy Install Location>/build
cmake -DBUILD_TESTS_MODE=ON ..
make
ctest

If tests are available, they will be compiled into separate executables for unit and integration tests. These tests can be run individually or using CTest.

🗒️ Third-Party Libraries

This project makes use of several open-source libraries and tools that help us achieve our autonomy goals. We would like to acknowledge and thank the developers of the following libraries:

OpenCV - Computer vision library for real-time image and video processing.
OpenCV GitHub
License: BSD-3-Clause License
PyTorch - A deep learning framework for building and training neural networks.
PyTorch GitHub
License: BSD-3-Clause License
TensorFlow Lite - Lightweight version of TensorFlow for running machine learning models on mobile and embedded devices.
TensorFlow Lite
License: Apache License 2.0
Libedgetpu - Library for accessing Google’s Edge TPU for hardware-accelerated machine learning inference on embedded devices.
Libedgetpu
License: Apache License 2.0
ZED SDK - Software development kit for Stereolabs ZED cameras.
Stereolabs ZED SDK
License: ZED SDK License
Quill - Fast, low-latency logging library.
Quill GitHub
License: MIT License
Google Test - C++ testing framework used for unit tests.
Google Test GitHub
License: BSD-3-Clause License
Abseil - Collection of C++ libraries designed for performance and ease of use.
Abseil GitHub
License: Apache License 2.0
GeographicLib - C++ library for geodesic and geographic computations.
GeographicLib GitHub
License: MIT License
Eigen - A high-performance C++ library for linear algebra, matrix, and vector operations.
Eigen GitHub
License: MPL2 License
CMake - Cross-platform tool for managing the build process of software.
CMake GitHub
License: BSD-3-Clause License
CUDA Toolkit - Parallel computing platform and programming model by NVIDIA.
NVIDIA CUDA Toolkit
License: NVIDIA CUDA EULA
Git LFS - Git extension for versioning large files.
Git LFS GitHub
License: MIT License
Doxygen - Tool for generating documentation from annotated C++ sources.
Doxygen GitHub
License: GPL-2.0 License

📦 Submodule Libraries

This project also uses the following submodules, which are included as part of the repository:

Thread Pool - A lightweight and efficient C++17 thread pool implementation.
Thread Pool GitHub
License: MIT License
RoveComm_CPP - A C++ implementation of the RoveComm communication protocol for MRDT systems.
RoveComm_CPP GitHub
License: MIT License

🙌 A Special Thanks to Our Contributors

The success of the Mars Rover Design Team's Autonomy Software wouldn’t be possible without the dedication, passion, and hard work of our amazing contributors. Every commit, every idea, and every effort brings us one step closer to reaching new heights in the University Rover Challenge.

Thank you to:

The Software Team for their commitment to building robust and cutting-edge autonomy algorithms.
The Mechanical, Electrical, and Science Subteams for providing the rover with the hardware and instrumentation it needs to achieve autonomy.
The R&D Subteam for pushing the boundaries of our capabilities with innovation and forward-thinking.
The Public Relations Subteam for keeping our community informed and excited about our journey.

We also extend our gratitude to the countless alumni, mentors, and supporters who have provided invaluable guidance and resources over the years.

Every contributor, from newcomers to veterans, plays a critical role in the continued success of the team. Your hard work is what makes Mars Rover Design Team the exceptional organization that it is today.

Let’s keep roving hard! 🚀