robosoft-ai/SMACC2

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

What it is

• 一款开源 C++ 库，让您可以在 ROS 2 之上构建 event-driven, asynchronous（事件驱动、异步）的行为状态机。它针对实时、多组件机器人（移动底座 + 手臂 + 传感器等）而设计。

Why it matters

• ROS 2 在 C++ 方面的 task-level（任务层级）状态机编程原生选项很少。SMACC2 填补了这一空白，提供编译时检查（通过 Boost Statechart）以及一个能与 ROS 2 topics、services 和 actions 完美整合的框架。

Key features

• ROS 2 native – 开箱即用，支持 topics、services 和 actions。
• C++ only – 适合 Python 太过笨重的工业级实时部署场景。
• Orthogonal regions – 让您可以在单个状态机中对机器人的独立并行部分（例如：导航、机械臂控制、传感器处理）进行建模。
• Static validation – 通过编译时验证状态机结构，减少运行时错误。
• Reference library – 一组可直接运行的示例状态机（sm_atomic, sm_three_some, Nav2 demos）供您复制和扩展。
• Client library – 现成的 ROS 2 客户端（Nav2, MoveIt2, timers, keyboard, multi-role sensors）可直接接入状态机框架。
• Extensive Doxygen docs – 附带自动生成的 API 文档与 UML 图表及调用图。
• Runtime Analyzer (RTA) – 一款独立的、学术用途免费的工具，用于可视化和调试运行时状态机执行（闭源，但可从供应商网站下载）。

Repository layout

• smacc2/ – 核心库实现。
• smacc2_client_library/ – ROS 2 客户端封装（Nav2, MoveIt2 等）。
• smacc2_event_generators/, smacc2_msgs/ – 支持性代码和消息定义。
• smacc2_sm_reference_library/ – 示例状态机项目。
• 其他辅助库（smacc2_state_reactor_library, smacc2_performance_tools）。

Getting started (ROS 2 Jazzy example)

1. 安装 ROS 2 Jazzy 和所需工具 (colcon, vcs, pre-commit)。
2. 创建一个 ROS 2 工作空间并 clone SMACC2 仓库。
3. 切换到 jazzy 分支。
4. 使用 vcs import … 拉取 ROS 2 依赖项并通过 rosdep 安装。
5. 使用 colcon build -DCMAKE_BUILD_TYPE=Release 构建工作空间。
6. 从 smacc2_sm_reference_library 挑选一个示例（例如 sm_atomic）并按照其 README 运行状态机。

Typical use cases

• 需要协调移动、底座、机械臂、夹具和多个传感器的复杂移动操作器。
• 需要确定性、编译时检查行为的工业机器人。

Documentation & support

• 针对不同 ROS 版本（例如 https://robosoft-ai.github.io/smacc2_doxygen/foxy/html/）自动生成的 Doxygen 网站。
• Foxy, Humble, Jazzy 的构建状态徽章显示持续集成结果。
• 如有疑问或想贡献，请发送邮件至 techsupport@robosoft.ai。

---

SMACC2 是一款真正的机器人学专注的软件项目，而非通用的 AI/ML 库。它提供的是编排机器人行为的基础设施，而非训练或运行机器学习模型。",