💡 Motivation and Features

AutoAPMS is a ROS 2 software development framework offering an end-to-end solution for enabling autonomous robotic operation. It can be applied in any field of robotics as long as the corresponding systems are running ROS 2. Other popular middlewares like PX4 are also supported (they must offer a possibility for bridging internal messages to ROS 2 topics).

Developers of real-time systems benefit from:

• Convenient resource management integrating deeply with CMake
• Modular, plugin-based approach for implementing robotic skills/tasks
• User-friendly behavior design adopting the behavior tree paradigm
• Flexible, highly configurable behavior executor
• Powerful C++ behavior tree builder API
• Straightforward contingency and emergency management concept
• Standardized interfaces and command line tools for running and orchestrating the operation

These features aim to simplify and automate the manual development work. Altogether, they frame a unified toolset for implementing behavior-based systems and make it significantly more user-friendly and less error prone to design and execute robotic applications.

For more information and an extensive how-to guide, feel encouraged to visit the 👉 AutoAPMS Website 👈.

🚀 Setup and Demonstration

AutoAPMS is designed for Linux. The following ROS 2 versions are supported:

ROS 2 Version	OS	Status
Humble Hawksbill	Ubuntu 22.04 (Jammy Jellyfish)
Jazzy Jalisco	Ubuntu 24.04 (Noble Numbat)

The following installation guide helps you getting started with AutoAPMS by building the source code yourself. Finally, you may test your installation by running an example.

Firstly, you have to create a ROS 2 workspace and clone this repository.

mkdir ros2_ws && cd ros2_ws
(mkdir src && cd src && git clone https://github.com/robin-mueller/auto-apms.git)

Afterwards, install all required dependencies. We assume that you already installed ROS 2 on your system.

rosdep init  # Skip this if rosdep has already been initialized
rosdep update
rosdep install --from-paths src --ignore-src -y

# Python packages for simulation (not all are available with rosdep)
python3 -m pip install -r src/auto-apms/auto_apms_simulation/requirements.txt

Then, build and install all of the source packages up to auto_apms_examples.

[!NOTE] We highly recommend building your workspace using the symlink-install option since AutoAPMS extensively utilizes XML and YAML resources. This option installs symbolic links to those non-compiled source files meaning that you don’t need to rebuild again and again when you’re for example tweaking a behavior tree document file. Instead, your changes take effect immediately and you just need to restart your application.

colcon build --packages-up-to auto_apms_examples --symlink-install

Congratulations, you’ve already successfully installed all necessary resources. You may now launch a lightweight simulation that applies the concepts offered by AutoAPMS. This should give you an idea of what’s possible with this framework.

The basic robot behavior can be observed by executing

source install/setup.bash
ros2 launch auto_apms_examples pyrobosim_hogwarts_launch.py
# Press Ctrl+C to quit

The actions of each robot you’ve seen are executed using behavior trees. This functionality is provided by the auto_apms_behavior_tree package. However, each robot is acting independently and they are not aware of their environment. Yet.

Now, we want to make the robots more intelligent and allow them to dynamically adjust their behavior when they encounter other robots inside one of the hallways. This is realized by implementing fallback mechanisms introduced by the auto_apms_mission package. To achieve that, you simply have to specify the following launch argument.

source install/setup.bash
ros2 launch auto_apms_examples pyrobosim_hogwarts_launch.py mission:=true
# Press Ctrl+C to quit

The robots dynamically decide to retreat and wait until the hallway they are about to cross is not occupied anymore. They basically monitor if a certain event occurs and initialize a corresponding sequence of action if applicable. With this, we effectively introduced automatically orchestrated reactive behaviors.

https://github.com/user-attachments/assets/adbb7cab-1a9b-424b-af61-61c351986287

🎓 Documentation

Make sure to visit the User Guide for tutorials and best practices when writing software using AutoAPMS.

We also offer an extensive API Documentation which is created using Doxygen >= 1.10. To generate the documentation run the following from the repository’s root:

doxygen doc/Doxyfile

🌟 Credits

Aside from the core ROS 2 packages, this repository builds upon

• BehaviorTree.CPP by Davide Faconti.

• pyrobosim by Sebastian Castro.

Thanks for all the great work from the maintainers and contributors of the above mentioned projects.

Any contribution that you make to this repository will be under the Apache 2 License, as dictated by that license:

5. Submission of Contributions. Unless You explicitly state otherwise,
   any Contribution intentionally submitted for inclusion in the Work
   by You to the Licensor shall be under the terms and conditions of
   this License, without any additional terms or conditions.
   Notwithstanding the above, nothing herein shall supersede or modify
   the terms of any separate license agreement you may have executed
   with Licensor regarding such Contributions.