Agent Skills: Nav2 Knowledge Patch

Nav2 Knowledge Patch

Use this skill when configuring, migrating, extending, or troubleshooting Nav2. Start with the breaking interface and parameter changes below, then open the topic reference that matches the subsystem being changed. Treat the running distribution's packages, interfaces, and tests as authoritative when a mixed or backported installation differs from these defaults.

Reference index

| Reference | Topics | | --- | --- | | Migration and integration | Distribution status, messages, namespaces, ROS wrappers, simulation, RViz, lifecycle, and test builds | | Behavior Trees | Error propagation, node and port renames, selectors, subtrees, cancellation, validation, and replanning | | Planning and control | Planner/controller selection, server behavior, MPPI, RPP, SMAC, Rotation Shim, goal checking, and smoothing | | Costmaps, localization, and mapping | Costmap APIs, layers, transports, clearing, inflation, AMCL, footprints, and vector objects | | Routing, docking, and behaviors | Route Server, docking, Following Server, Behavior Server, loopback simulation, and motion behaviors | | Collision Monitor | Command pipeline, fail-safe timing, zones, sources, runtime controls, debounce, and costmap input |

Migration triage

Check these first when moving launch files, parameter files, plugins, or trees:

• cmd_vel uses geometry_msgs/TwistStamped by default. Set enable_stamped_cmd_vel: false on every affected node only for a deliberately retained Twist pipeline.
• Replace BT Navigator's removed error_code_names with error_code_name_prefixes, and wire both error_code_id and error_msg on relevant action nodes.
• Multi-pose actions now carry nav_msgs/Goals; use poses.goals or goals.goals. Preserve the parallel WaypointStatus list through pruning nodes.
• Remove use_namespace from nav2_bringup. namespace is always applied, defaults to /, and relative topics resolve inside it.
• Move Costmap2DROS.map_topic to the StaticLayer; use the consolidated Costmap2DROS(name, parent_namespace, use_sim_time) constructor.
• Treat control_frequency as startup-only configuration.
• In Rotation Shim, nest the primary controller's plugin and parameters beneath primary_controller.
• In MPPI, configure a named motion-model plugin group rather than legacy DiffDrive, Omni, or Ackermann string values.
• Replace ValidatePath.check_full_path with the oppositely worded stop_at_first_collision; old false maps to new true.
• Move controller-specific plan transformation and pruning parameters to Controller Server's path-handler plugin.
• Retune Constrained Smoother weights because its corrected objective is weight * residual².
• Move navigator blackboard-ID parameters beneath each navigator plugin, and rename TruncatePathLocal.robot_frame to robot_base_frame.

See Migration and integration and Behavior Trees for the complete migration set.

Action error propagation

Configure contextual action errors with prefixes:

error_code_name_prefixes: [compute_path, follow_path, spin, route]

Expose matching tree ports:

<FollowPath path="{path}" error_code_id="{follow_path_error_code}"
            error_msg="{follow_path_error_msg}"/>

The removed error_code_names parameter causes a startup exception rather than silently falling back.

Namespaces and message interfaces

• Prefer relative topics such as scan for namespaced robots. Keep /scan only when the source is intentionally global.
• Costmap layers that must resolve relative to their parent costmap can use joinWithParentNamespace() instead of their private layer namespace.
• With stamped velocity enabled, preserve timestamps through smoothing and safety nodes so stale commands can be rejected.
• For dynamic footprints, enable subscribe_to_stamped_footprint only when publishing PolygonStamped; the subscription type changes from Polygon.

Planning and control quick reference

• Use NavFn, Smac 2D, or Theta Star primarily for circular differential or omnidirectional robots. Use Smac Hybrid-A* for footprint-aware, curvature-constrained platforms and Smac Lattice for explicit kinematic control sets.
• DWB normally serves differential and omnidirectional bases. RPP and Vector Pursuit do not support omnidirectional motion; MPPI and TEB span differential, omnidirectional, Ackermann, and legged platforms.
• Controller Server's costmap freshness timeout defaults to 0.3 seconds; Planner Server's defaults to 1.0 second.
• Controller exception tolerance defaults to disabled (failure_tolerance: 0.0); -1.0 tolerates failures indefinitely.
• use_realtime_priority: true requests thread priority 90 and requires an adequate process-user rtprio limit.
• PositionGoalChecker ignores orientation. Axis, symmetric-yaw, and adaptive goal checkers cover more specialized completion semantics.
• Partial multi-pose planning is opt-in with allow_partial_planning; inspect last_reached_index before accepting a returned prefix.
• Keep Velocity Smoother limits at least as permissive as Dynamic Window Pure Pursuit's controller limits.

Open Planning and control before changing planner, controller, goal-checker, smoother, or path-handler plugins.

Behavior Tree quick reference

• NonblockingSequence ticks later children while an earlier child is still RUNNING.
• PauseResumeController combines pause/resume services with PersistentSequence, whose bidirectional child-index port resumes progress.
• RoundRobin now defaults to wrap_around="false" and fails after the last child unless wrapping is explicitly enabled.
• The default navigation tree can select progress checker, goal checker, path handler, controller, and planner IDs through selector topics.
• The default near-goal fallback retains a valid remaining plan when the goal is unchanged and nearby; it replans when any guard fails.
• Reusable subtree files come from bt_search_directories; select trees by a unique ID rather than a shared MainTree.

Open Behavior Trees when modifying XML or BT Navigator parameters; it includes all action/condition renames and port changes.

Costmap and localization quick reference

• Keep costmap filters in filters, separate from ordinary plugins; filters run after the layered costmap has been combined.
• A selective clear request is atomic: an invalid or non-clearable named plugin makes the request fail without clearing anything.
• transport_type may select compressed point-cloud transports; raw remains the default.
• custom_inscribed_radius: 0.0 bypasses the inscribed region and is unsafe for ordinary planners or controllers that expect standard cost semantics.
• AMCL random_seed: -1 remains nondeterministic; a nonnegative seed makes particle-filter runs repeatable.
• always_reset_initial_pose: true requires a new initial pose after reset; first_map_only: true ignores replacement maps.

Open Costmaps, localization, and mapping for conversion values, startup transform timing, visualization, mapping, and layer details.

Routing, docking, and behavior quick reference

• Route Server plans over a predefined graph, emits node/edge events, and can smooth corners with tangent arcs when geometry permits.
• Docking collision checking is enabled by default. Configure direction per plugin with dock_direction; use reverse_to_dock only for the staged forward-detection/backward-entry workflow.
• Custom charging and non-charging dock plugins must implement detection start and stop hooks.
• Behavior Server loads Spin, BackUp, DriveOnHeading, and Wait by default; AssistedTeleop must be added explicitly.
• disable_collision_checks defaults to false for Spin, BackUp, and DriveOnHeading. Do not disable it casually.
• The loopback simulator is for ideal odometry tests, not physics or localization error modeling.

Open Routing, docking, and behaviors for server parameters, action-owned inputs, route operations, and following.

Collision Monitor safety checklist

• Put Collision Monitor after smoothing in the command pipeline and publish its safety-adjusted output on the robot command topic.
• Keep source_timeout enabled unless another fail-safe owns stale-source handling. A stale observation source stops the robot.
• base_shift_correction should remain enabled for fast robots or modest sensor rates.
• Overlapping zones resolve to the most restrictive action. For velocity polygons, order overlaps deliberately and finish with a catch-all range.
• Migrating Humble thresholds requires min_points = max_points + 1.
• Costmap source cost 255 follows treat_unknown_as_obstacle, separately from cost_threshold.
• Runtime Toggle disables polygons but leaves sensor checking active.

Open Collision Monitor before changing zone geometry, temporal debounce, observation filters, source types, or fail-safe timers.

Verification workflow

After a migration or configuration change:

1. Confirm each renamed or moved parameter is absent from its old scope.
2. Inspect actual action, service, topic, and BT port types instead of assuming an older interface.
3. Verify relative topic resolution under the intended robot namespace.
4. Exercise failure paths: stale sensors, controller exceptions, partial plans, invalid clear-plugin names, and BT cancellation.
5. Check visualization and introspection only after functional behavior; both are optional and may be disabled by default.
6. Run isolated middleware tests with --cmake-args -DUSE_ISOLATED_TESTS=ON when a separate Zenoh router is not part of the test environment.