AUTONOMY

A modular intelligence framework for autonomous mobile robots

Built with modern C++, Autolink RT, and behavior trees. Designed for production-grade robotics without a ROS runtime dependency.

Documentation · Installation · Quick Start · Architecture · CMake layout

PERCEPTION · LOCALIZATION · MAPPING · PLANNING · CONTROL · ORCHESTRATION

---

Overview

Autonomy is an autonomous software framework for mobile robots operating in indoor and structured environments. It embeds Autolink as its communication runtime and combines unified messages, plugin interfaces, Lua / YAML configuration, and behavior-tree task orchestration. Perception, localization, mapping, planning, control, and hardware integration remain separate modules that can evolve independently.

The framework draws on engineering patterns from Navigation2, Autoware, and Cartographer, while keeping its core runtime independent of ROS / ROS 2. Optional gRPC, Foxglove, and compatible message conventions provide integration points for external ecosystems.

Why Autonomy

Runtime Independent	Modular by Design	Production Oriented
Node, Channel, Service, Action, Parameter, and record / replay without a ROS runtime dependency.	Stable boundaries and plugin interfaces across algorithms, tasks, messages, drivers, simulation, and visualization.	Configuration-driven builds, cross-platform deployment, observability, and hardware abstraction.

Autonomy brings the complete robotics toolchain into one coherent runtime:

• Extend with confidence — planners, controllers, and behavior-tree nodes follow common plugin interfaces.
• Configure consistently — Lua, YAML, and Protobuf cover launch, runtime, and interface definitions.
• Deploy across platforms — Docker and Ansible workflows support x86_64 and ARM64 environments.
• Operate as one system — AutoDriver, AutoSim, AutoViz, evaluation tools, and Foxglove share Autolink RT.

Capabilities

Area	Module	Capabilities
Communication	autolink/	In-process transport, shared memory, optional RTPS, Service, Action, and Parameter
Messages	automsgs/	ROS-style Protobuf messages, services, actions, and C++ / Python code generation
Perception	autonomy/perception/	Object detection and tracking, monocular depth, and person-following perception
Localization	autonomy/localization/	Atlas visual SLAM and Cartographer lidar SLAM
Mapping	autonomy/map/	costmap_2d, grid_map, occupancy grids, and map services
Planning	autonomy/planning/	Global planning with NavFn, Dijkstra, Theta*, and related planners
Control	autonomy/control/	MPPI, Graceful, Pure Pursuit, and controller state checking
Tasks	autonomy/task/	Behavior-tree orchestration for navigation, tracking, mapping, teleoperation, and charging
Audio	autonomy/audio/	Audio capture, inference interfaces, and an optional Sherpa-ONNX backend
Hardware	autodriver/	Camera, LiDAR, IMU, GPS, CAN bus, and chassis HAL
Simulation	autosim/	Habitat-Sim sensor–actuator bridge, simulation clock, ground truth, and teleoperation
Visualization	autoviz/	Native Qt / OpenGL 3D visualization connected directly to Autolink

Module availability depends on build options and locally installed dependencies. Some hardware, inference, and bridge backends are optional.

Architecture

Runtime Architecture

Task and Data Flows

Navigation Task Workflow	Person-Following Data Flow
Goal, planning, recovery, cancellation	RGB, tracks, depth, target path, local grid

Explore the System

The interactive Archify views support route tracing, node focus, light and dark themes, and presentation mode. Select any diagram above or open its definition below.

View	Trace	Definition
Runtime Architecture	Task request → behavior tree → algorithms → hardware	JSON
Navigation Workflow	Goal → planning → recovery → completion or cancellation	JSON
Person-Following Flow	RGB and depth → tracking → target path → local control	JSON

See the system architecture guide for module relationships, configuration pipelines, and runtime data flows.

Quick Start

Prerequisites

• Recommended: Ubuntu 22.04 Docker development environment
• Source build: Ubuntu 22.04, CMake 3.20+, GCC 11+ or Clang, and C++17
• Build system: Ninja

1. Clone

git clone --recurse-submodules https://github.com/quandy2020/autonomy.git
cd autonomy

If the repository was cloned without submodules:

git submodule update --init --recursive

2. Enter the Development Environment

export AUTONOMY_ENV=/path/to/autonomy
python3 docker/run_autonomy.py -p x86_64

3. Configure and Build

cd /workspace/autonomy
cmake -S . -B build -G Ninja
cmake --build build -j"$(nproc)"

Per-module shared libraries (libautonomy_common.so, libautonomy_map.so, …) are aggregated by the INTERFACE target autonomy / autonomy::autonomy. Build a single module from the super-project:

cmake --build build --target autonomy_map -j"$(nproc)"
cmake --build build --target autonomy.planning -j"$(nproc)"

Standalone module configure (requires an installed prefix with prior modules):

cmake -S autonomy/map -B build-map -DCMAKE_PREFIX_PATH=<prefix>
cmake --build build-map -j"$(nproc)"

See the Docker installation guide for image, GPU, and ARM64 configuration.

Build Directly on the Host

cd scripts
python3 -m install_deps
cd ..

cmake -S . -B build -G Ninja
cmake --build build -j"$(nproc)"

4. Run the Multi-Process Stack

After building, launch the recommended multi-process autonomy stack:

export PATH="$PWD/build/bin:$PATH"
export AUTOLINK_LAUNCH_PATH="$PWD/autonomy/system/launch"
export AUTONOMY_BT_PLUGIN_PATH="$PWD/build/lib"
export GLOG_logtostderr=1

autolink_launch autonomy.launch

Send navigation goals via Bridge or an autolink Action client. Map assets live under autonomy/map/conf/. See Quick Run and Troubleshooting.

Project Structure

autonomy/
├── autonomy/      # Per-module shared libs (autonomy_common, autonomy_map, …)
│                  # + INTERFACE umbrella target `autonomy` / `autonomy::autonomy`
│                  # Module conf under autonomy/<mod>/conf/
├── autolink/      # Communication runtime (Git submodule)
├── automsgs/      # Protobuf messages, services, and actions
├── autodriver/    # Sensor and chassis hardware abstraction
├── autosim/       # Habitat-Sim bridge
├── autoviz/       # Native 3D visualization
├── docker/        # Development images and dependency installation
├── ansible/       # Bare-metal and fleet deployment
├── docs/          # Sphinx documentation and architecture assets
├── scripts/       # Dependency, formatting, and packaging tools
└── CMakeLists.txt # Super-project: deps + add_subdirectory(autonomy/<mod>)

Component Guides

• Autolink — communication runtime
• AutoMsgs — messages and code generation
• AutoDriver — hardware abstraction layer
• AutoSim — simulation bridge
• AutoViz — native visualization
• Ansible — build and fleet deployment
• Scripts — development and CI tools

Common CMake Options

CMake option	Default	Description
BUILD_TEST	ON	Build unit tests
BUILD_TOOLS	ON	Build command-line and validation tools
BUILD_DOCS	ON	Build Sphinx documentation
BUILD_GRPC	ON	Build the gRPC Bridge
BUILD_AUTODRIVER	ON	Embed AutoDriver in the root build
BUILD_AUTOVIZ	ON	Build AutoViz
BUILD_AUTOSIM	ON	Install and integrate AutoSim
BUILD_ONNXRUNTIME	ON	Enable the ONNX Runtime perception backend
BUILD_TENSORRT	ON	Enable the TensorRT perception backend
BUILD_SHERPA_ONNX	OFF	Enable the Sherpa-ONNX speech-recognition backend
BUILD_PROMETHEUS	OFF	Enable Prometheus monitoring support

Example:

cmake -S . -B build -G Ninja \
  -DBUILD_DOCS=OFF \
  -DBUILD_AUTOVIZ=OFF \
  -DBUILD_TENSORRT=OFF

Deployment

Ansible workflows cover bare-metal installation, artifact distribution, configuration updates, and service restarts:

cd ansible
pip install "ansible>=8,<10"

./deploy.sh check robots
./deploy.sh deploy robots -e autonomy_artifact_path="$PWD/../dist/autonomy.tar.gz"

Configure robot addresses and SSH access in ansible/inventory/robots/hosts.yml before deployment. See the Ansible deployment guide for the complete workflow.

Documentation

Topic	Guide
Installation and dependencies	Installation
Communication	Communication
Building and running	Running
Localization and SLAM	Localization
Mapping	Map
Planning	Planning
Control	Control
Perception	Perception
Simulation	Simulation
Visualization	Visualization
Task system	Tasks
Frequently asked questions	FAQs

Full documentation: autonomy.readthedocs.io

Contributing

Issues, documentation improvements, and pull requests are welcome. Before modifying a module, read its local README and preserve the existing interface, configuration, and test boundaries.

See the existing module guides for ownership boundaries and validation instructions before submitting a change.

License

This project is licensed under the Apache License 2.0.

Acknowledgments

Autonomy builds on ideas and components from the following open-source projects:

• Autoware Universe
• Cartographer
• Navigation2
• ROS 2
• BehaviorTree.CPP

---

Autonomy — engineered for modular, observable, and deployable robot intelligence. Copyright © Autonomy Contributors