temporary storage

docs/PLUGIN_GUIDE.md

@@ -0,0 +1,78 @@
+# 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
+```