# Hướng Dẫn Viết Plugin recovery_core

Package hiện có 4 plugin mẫu dưới `plugins/`:
- `clear_costmap_recovery` — nhóm B, one-shot, no output.
- `rotate_recovery` — nhóm C, per-cycle velocity.
- `back_up_recovery` — nhóm C, per-cycle velocity.
- `regen_path_recovery` — nhóm A, path output.

## Bước chung

1. Kế thừa `recovery_core::RecoveryBehavior`.
2. Override `initialize()` — đọc param riêng qua `robot::NodeHandle("~/" + name)`, cache
   tf/global_path/costmap.
3. Override method theo họ (xem dưới) + `status()`.
4. Thêm factory `static Ptr create()` **không tham số** + `BOOST_DLL_ALIAS(...)`.

## Override theo họ

| Họ | Override | Trả về |
|----|----------|--------|
| A. path | `runBehavior()` | `RecoveryResult::PathOut(path, kSucceeded)` |
| B. none | `runBehavior()` | `RecoveryResult::Succeeded()` / `Failed()` |
| C. velocity | `computeCommand(dt)` | `RecoveryResult::Velocity(twist, kRunning|kSucceeded)` |

## Export bằng Boost.DLL (bắt buộc cho plugin)

```cpp
#include <recovery_core/recovery_behavior.h>
#include <boost/dll/alias.hpp>

namespace recovery_plugins {
class SpinRecovery : public recovery_core::RecoveryBehavior {
 public:
  static recovery_core::RecoveryBehavior::Ptr create() {
    return std::make_shared<SpinRecovery>();
  }
  // override initialize()/computeCommand()/runBehavior()/status()...
};
}  // namespace recovery_plugins

// alias = `type` dùng trong YAML recovery_behaviors.
BOOST_DLL_ALIAS(recovery_plugins::SpinRecovery::create, spin_recovery)
```

## Nạp phía loader (adapter/caller — không nằm trong recovery_core)

```cpp
#include <boost/dll/import.hpp>
auto loader = boost::dll::import_alias<recovery_core::RecoveryBehavior::Ptr()>(
    path_so, /*symbol=*/type, boost::dll::load_mode::append_decorations);
recovery_core::RecoveryBehavior::Ptr behavior = loader();
behavior->initialize(name, tf, global_path, global_costmap, local_costmap);
```

Lưu ý: adapter/test phải giữ handle `.so` sống lâu hơn object plugin. Nếu library bị unload trong
khi object plugin còn tồn tại, virtual call qua vtable của plugin có thể crash.

## CMake cho plugin

- `find_package(Boost REQUIRED COMPONENTS system filesystem)`
- link `${Boost_LIBRARIES}`, `${CMAKE_DL_LIBS}`, `recovery_core`
- `set_target_properties(<plugin> PROPERTIES POSITION_INDEPENDENT_CODE ON)`
- build shared library, tên library + symbol khớp `type`; install `.so` nơi loader tìm.

## Test plugin

```bash
catkin_make --pkg recovery_core
./devel/lib/recovery_core/recovery_core_plugin_loader_test
```

Standalone:

```bash
cmake -S src/AMR_T800/pnkx_nav_core/src/Navigations/Libraries/recovery_core -B /tmp/recovery_core_phase3_build
make -C /tmp/recovery_core_phase3_build -j4
/tmp/recovery_core_phase3_build/test/recovery_core_plugin_loader_test
```