ros2-stack-patterns

# ROS 2 Stack Patterns (from Nav2 / MoveIt / ros2_control) Extract **paradigms**, not package names. Cite those stacks only as origins. ## 1. Layered servers, thin glue | Layer | Responsibility | Pattern origin | |-------|----------------|----------------| | Bringup / lifecycle manager | Ordered configure→activate; bond/heartbeat; crash → deactivate tree | Nav2 | | Capability servers | One job: plan, control, localize, execute trajectory | Nav2 / MoveIt | | Behavior / mission | BT or state machine calling **actions/services**, not motors | Nav2 BT / MoveIt move_group | | Hardware | `ros2_control` hardware iface + controllers at fixed rate | ros2_control | Do not let the BT or UI publish `cmd_vel`/joint torques directly in production — go through the controller server. ## 2. Composition as default packaging - Ship servers as **components**; launch via composable container (optional isolated process for fault isolation). - Intra-process for high-rate / large data **inside** one container. - Parameter YAML per server; remaps at launch — same binary, many robots. ## 3. Lifecycle + bond - Managed nodes for anything that allocates hardware or maps. - Manager activates in dependency order (map → sensors → localize → plan → control). - **Bond/heartbeat**: if a server dies, manager transitions dependents to safe inactive (stop commanding). - Prefer manager events over `TimerAction(3.0)` “hope it’s up”. ## 4. Planner ≠ controller - **Planner** (slow, heavy): action/service, may run in worker thread; output path/trajectory. - **Controller** (fast, light): timer 50–200 Hz; tracks path; short callback; soft-RT optional. - Never run full global planning inside the control timer (see `ros2-executors`). ## 5. Actions + behavior trees - Long skills = **actions** (navigate, execute trajectory) with cancel/preempt. - BT ticks at modest rate; leaves are action clients / conditions; halt ⇒ **cancel** goals. - Feedback for UI/progress only; safety uses state topics + local preemption. ## 6. Shared world state concurrency (MoveIt-style) - One **planning scene** / map / costmap accessed by planning and monitoring. - Readers/writers: mutex or locked copies; planning often snapshots scene then plans unlocked. - Occupancy/costmap updates from sensors under lock; controllers read carefully (copy or RCU-style). ## 7. Realtime / control thread discipline - Control loop: no allocations, no logging spam, no service waits, no TF “wait for transform” forever. - TF: latest or short timeout; fail safe (zero twist / hold) on miss. - Optional `SCHED_FIFO` for the control thread only — needs OS rtprio limits; document it. ## 8. Plugin interfaces - Algorithms behind plugins (controllers, planners, localizers) loaded at configure. - Swap implementations via params without rewriting bringup — Nav2/MoveIt/`controller_manager` all do this. ## 9. Safety defaults - Command timeout → zero command (watchdog). - Unknown state after cancel → explicit idle/brake, not “last twist forever”. - Separate **estop** path that does not depend on the planner action succeeding. ## Review checklist - [ ] Lifecycle-managed critical nodes + ordered bringup - [ ] Control rate path free of sync DDS waits - [ ] Callback groups / mutexes where MT is used (`ros2-executors`) - [ ] Actions cancel on BT halt / preempt - [ ] Plugins for swappable algorithms - [ ] MCU/driver side has local safe-stop if host dies (`ros2-micro-ros`)