recovery_core/docs/ARCHITECTURE.md

Kiến Trúc recovery_core

Vị trí trong stack

recovery_core nằm ở tầng Navigations/Libraries, cạnh robot_clear_costmap_recovery. Nó giữ vai trò interface tương tự robot_nav_core::RecoveryBehavior cho các recovery cần trả về output (path/vận tốc), đồng thời vẫn dùng global path/costmap/tf như bản gốc.

Các thành phần

• RecoveryBehavior (interface): initialize (mirror nav_core) + runBehavior (one-shot) + computeCommand (per-cycle) + status.
• RecoveryResult / RecoveryStatus / RecoveryOutputType: hợp đồng output hợp nhất 3 họ.
• RecoveryConfig: param chung (control_frequency, timeout) + validate + đọc từ NodeHandle.
• Plugin mẫu:
  • ClearCostmapRecovery: clear layer costmap theo tên, trả no-output status.
  • RotateRecovery: sinh Twist.angular.z theo chu kỳ tới khi đủ góc.
  • BackUpRecovery: sinh Twist.linear.x < 0 theo chu kỳ tới khi đủ khoảng lùi.
  • RegenPathRecovery: trả lại robot_nav_msgs::Path từ global_path hiện tại.

Luồng runtime

initialize(name, tf, global_path, global, local)   // 1 lần, đọc param qua NodeHandle
        │
        ├── one-shot (họ A/B):  runBehavior() ──────────────► RecoveryResult{status, path|none}
        │
        └── per-cycle (họ C):   loop { computeCommand(dt) } ─► RecoveryResult{status, velocity}
                                (caller publish command mỗi cycle tới khi status != kRunning)

Ghi chú thiết kế

• computeCommand(dt) lấy pose robot từ costmap/tf bên trong (nhất quán mirror nav_core), không truyền pose qua tham số.
• Default RecoveryBehavior::computeCommand(dt) trả RecoveryResult::Failed() để họ A/B không vô tình sinh command mù.
• RecoveryConfig::validate() từ chối NaN/Inf, control_frequency <= 0, timeout < 0.
• RecoveryConfig::fromNodeHandle() đọc param chung và thay giá trị invalid bằng default an toàn.
• Interface KHÔNG include Boost.DLL; export/import là việc của plugin/loader.
• Plugin mẫu có dùng Boost.DLL alias, nhưng core contract vẫn không biết loader/adaptor.