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

• 需要協調移動、手臂、夾具與多個感測器的複雜移動操作器（mobile manipulators）。
• 需要確定性、編譯時檢查行為的工業機器人。

Documentation & support

• 針對不同 ROS 版本（例如 https://robosoft-ai.github.io/smacc2_doxygen/foxy/html/）自動生成的 Doxygen 網站。
• Foxy, Humble, Jazzy 的建構狀態標籤顯示持續整合結果。
• 如有疑問或想參與貢獻，請寄信至 techsupport@robosoft.ai。

---

SMACC2 是一個真正的機器人學專注於軟體專案，而非通用的 AI/ML 函式庫。它提供的是編排機器人行為的基礎設施，而非訓練或執行機器學習模型。",