robosoft-ai/SMACC2

SMACC2 – A C++ State‑Machine Library for ROS 2

What it is

• An open‑source C++ library that lets you build event‑driven, asynchronous behavioral state machines on top of ROS 2. It is aimed at real‑time, multi‑component robots (mobile base + arm + sensors, etc.).

Why it matters

• ROS 2 has few native options for task‑level state‑machine programming in C++. SMACC2 fills that gap, giving you compile‑time checks (via Boost Statechart) and a framework that integrates cleanly with ROS 2 topics, services and actions.

Key features

• ROS 2 native – works with topics, services, actions out of the box.
• C++ only – suitable for industrial, real‑time deployments where Python is too heavyweight.
• Orthogonal regions – lets you model independent concurrent parts of a robot (e.g., navigation, arm control, sensor handling) in a single state machine.
• Static validation – compile‑time verification of state‑machine structure reduces runtime bugs.
• Reference library – a collection of ready‑to‑run example state machines (sm_atomic, sm_three_some, Nav2 demos) that can be copied and extended.
• Client library – ready‑made ROS 2 clients (Nav2, MoveIt2, timers, keyboard, multi‑role sensors) that plug into the state‑machine framework.
• Extensive Doxygen docs – auto‑generated API docs with UML diagrams and call graphs.
• Runtime Analyzer (RTA) – a separate, free‑for‑academic tool for visualising and debugging state‑machine execution (closed source but downloadable from the vendor site).

Repository layout

• smacc2/ – core library implementation.
• smacc2_client_library/ – ROS 2 client wrappers (Nav2, MoveIt2, etc.).
• smacc2_event_generators/, smacc2_msgs/ – supporting code and message definitions.
• smacc2_sm_reference_library/ – example state‑machine projects.
• Additional helper libraries (smacc2_state_reactor_library, smacc2_performance_tools).

Getting started (ROS 2 Jazzy example)

1. Install ROS 2 Jazzy and required tools (colcon, vcs, pre‑commit).
2. Create a ROS 2 workspace and clone the SMACC2 repo.
3. Checkout the jazzy branch.
4. Pull the ROS 2 dependencies with vcs import … and install them via rosdep.
5. Build the workspace with colcon build -DCMAKE_BUILD_TYPE=Release.
6. Pick an example from smacc2_sm_reference_library (e.g., sm_atomic) and follow its README to run the state machine.

Typical use cases

• Complex mobile manipulators that need coordinated control of locomotion, arm, gripper, and multiple sensors.
• Industrial robots where deterministic, compile‑time‑checked behavior is required.
• Research prototypes that combine navigation (Nav2) and manipulation (MoveIt2) within a single, maintainable state‑machine architecture.

Documentation & support

• Auto‑generated Doxygen site per ROS distro (e.g., https://robosoft-ai.github.io/smacc2_doxygen/foxy/html/).
• Build status badges for Foxy, Humble, Jazzy show continuous integration results.
• For questions or contributions, email techsupport@robosoft.ai.

---

SMACC2 is a genuine robotics‑focused software project, not a generic AI/ML library. It provides the infrastructure to orchestrate robot behaviours rather than to train or run machine‑learning models.