easynav_diagnostic_recovery

A diagnosis-driven recovery system for EasyNav: easynav_diagnostic_recovery/DiagnosticRecoveryManager. For the full design, see docs/recoveries_easynav.md in EasyNavigation.

A recovery system is a RecoveryManagerBase plugin hosted by recovery_node. This one is made of plugins too, at two levels:

• Level 0, RT: safety reflexes (SafetyReflexBase). Every RT cycle, right before publishing, each reflex checks the command about to be sent, whoever produced it (the controller or a mitigation). On imminent danger it overrides that command (highest priority, not smoothed).
• Level 1, non-RT: evaluators and mitigations.
  • Evaluators (RecoveryEvaluatorBase) diagnose. Each one writes a diagnostic_msgs/DiagnosticStatus (OK/WARN/ERROR) to NavState.
  • Mitigations (RecoveryMitigationBase) handle diagnostics in ERROR. On each cycle, the manager:
    • takes the first diagnostic in ERROR and starts the first mitigation, by priority (lower first), whose can_handle() accepts it;
    • runs at most one mitigation at a time, until it returns SUCCEEDED or FAILED;
    • when one fails, excludes it for that diagnostic, so the next one is tried (escalation).
  • A mitigation that requires_control() drives the robot: it takes over the controller.
  • Mitigations ask EasyNav through the manager to abort the mission or shut down.
  • While a mitigation is active or a diagnostic is in ERROR, the mission’s progress is held: no goal is taken as reached.

Topics: diagnostics (diagnostic_msgs/DiagnosticArray) and mitigation (rcl_interfaces/Log, what the active mitigation reports). The EasyNav TUI shows both.

Supported ROS 2 Distributions

Distribution	Status
humble
jazzy
kilted
lyrical
rolling

Package layout

Everything is in the easynav_diagnostic_recovery package and library. Headers are under include/easynav_diagnostic_recovery/, sources under src/easynav_diagnostic_recovery/ and tests under tests/, with the same subfolders:

A component can also ship recovery for its own failures. For example, easynav_costmap_localizer ships AmclConvergenceEvaluator and AmclRelocalizeMitigation.

Plugins

Each plugin’s parameters are under recovery_manager.<type>.. Every mitigation also takes priority (default 100).

Usage

```yaml recovery_node: ros__parameters: recovery_manager: plugin: easynav_diagnostic_recovery/DiagnosticRecoveryManager safety_reflex_types: [collision] collision: plugin: easynav_diagnostic_recovery/CollisionSafetyReflex evaluator_types: [no_path, obstacle_close, controller_stuck, amcl_convergence, ros_graph] no_path: plugin: easynav_diagnostic_recovery/NoPathEvaluator obstacle_close: plugin: easynav_diagnostic_recovery/ObstacleTooCloseEvaluator controller_stuck: plugin: easynav_diagnostic_recovery/ControllerStuckEvaluator amcl_convergence: plugin: easynav_costmap_localizer/AmclConvergenceEvaluator ros_graph: plugin: easynav_diagnostic_recovery/RosGraphEvaluator # Tried in priority order (lower first) for each ERROR they can handle: # specific fixes -> terminate on a miswired graph -> wait for a human -> cancel the mission mitigation_types: [retreat, amcl_relocalize, advance, shutdown, human_assistance, cancel_mission] retreat: plugin: easynav_diagnostic_recovery/SafeRetreatRecovery

File truncated at 100 lines see the full file

Changelog for package easynav_diagnostic_recovery

0.5.0 (2026-10-08)

• First release: DiagnosticRecoveryManager, a recovery manager driven by diagnostics, with evaluators, mitigations and real-time safety reflexes
• Safety channel evaluator
• The collision reflex fails safe without data
• Rejected reconfigurations are handled
• Each evaluator reports whether it keeps its frequency
• Builds on Humble, Jazzy, Kilted, Lyrical and Rolling
• Contributors: Francisco Martín Rico