How ros-navigation/navigation2 works
Purpose and runtime
Nav2 is a ROS 2 navigation stack for mobile robots. It is a multi-package C++ system with Python launch/client packages, built with CMake/ament. Nodes communicate through ROS 2 actions, services, topics, TF transforms, lifecycle state, and nav2_msgs interfaces. Shared plugin contracts define replaceable planners, controllers, smoothers, behaviors, and navigators: nav2_core/include/nav2_core/global_planner.hpp, nav2_core/include/nav2_core/controller.hpp, nav2_msgs/action/NavigateToPose.action.
System entry points and composition
The principal operational entry is the bringup launch layer, which assembles localization, navigation servers, maps, parameters, and lifecycle management: nav2_bringup/launch/bringup_launch.py, nav2_bringup/launch/navigation_launch.py, nav2_bringup/params/nav2_params.yaml. Individual server executables generally enter through package-local src/main.cpp, such as nav2_planner/src/main.cpp and nav2_controller/src/main.cpp. nav2_lifecycle_manager controls ordered activation and health/bond management: nav2_lifecycle_manager/src/lifecycle_manager.cpp.
World model and localization
Map serving supplies occupancy-grid maps and map persistence; map/filter metadata forms the static environment boundary: nav2_map_server/src/map_server/map_server.cpp, nav2_map_server/src/map_io.cpp, nav2_bringup/maps/warehouse.yaml. AMCL provides particle-filter localization from map, laser, and motion inputs: nav2_amcl/src/amcl_node.cpp, nav2_amcl/src/sensors/laser/likelihood_field_model.cpp. The layered 2D costmap combines static maps and live sensor observations into global/local collision-cost representations; filters can impose keepout or speed zones: nav2_costmap_2d/src/costmap_2d_ros.cpp, nav2_costmap_2d/plugins/obstacle_layer.cpp, nav2_costmap_2d/plugins/costmap_filters/keepout_filter.cpp.
Navigation orchestration
nav2_bt_navigator accepts high-level navigation actions and executes XML behavior trees. Its trees call planner, controller, smoother, route, behavior, and recovery actions through reusable BT nodes, allowing replanning, cancellation, and recovery policy to be configured rather than hardcoded: nav2_bt_navigator/src/bt_navigator.cpp, nav2_bt_navigator/behavior_trees/navigate_to_pose_w_replanning_and_recovery.xml, nav2_behavior_tree/src/behavior_tree_engine.cpp. The public command boundary is primarily NavigateToPose/NavigateThroughPoses; Python applications can use nav2_simple_commander/nav2_simple_commander/robot_navigator.py.
Planning, routing, and smoothing
nav2_planner hosts global-planner plugins over the global costmap and exposes path computation/validation: nav2_planner/src/planner_server.cpp, nav2_planner/include/nav2_planner/is_path_valid_service.hpp. Included algorithms include NavFn, Theta*, and Smac 2D/Hybrid/Lattice planners: nav2_navfn_planner/src/navfn_planner.cpp, nav2_theta_star_planner/src/theta_star_planner.cpp, nav2_smac_planner/src/smac_planner_hybrid.cpp. nav2_smoother optionally refines paths before tracking: nav2_smoother/src/nav2_smoother.cpp. Separately, nav2_route plans and tracks routes on GeoJSON graphs, with pluggable edge scoring and route operations: nav2_route/src/route_server.cpp, nav2_route/src/route_planner.cpp, nav2_route/graphs/sample_graph.geojson.
Control, safety, and recovery
nav2_controller turns paths, current pose/odometry, and local costmaps into velocity commands via selectable controller, goal-checker, progress-checker, and path-handler plugins: nav2_controller/src/controller_server.cpp, nav2_controller/include/nav2_controller/controller_server.hpp. Implementations include DWB, MPPI, Regulated Pure Pursuit, Graceful, and rotation-shim controllers: nav2_dwb_controller/dwb_core/src/dwb_local_planner.cpp, nav2_mppi_controller/src/controller.cpp, nav2_regulated_pure_pursuit_controller/src/regulated_pure_pursuit_controller.cpp. Commands may be postprocessed by nav2_velocity_smoother/src/velocity_smoother.cpp; the independent collision monitor consumes scan/range/point-cloud sources and can constrain or stop motion: nav2_collision_monitor/src/collision_monitor_node.cpp. Recovery behaviors—spin, backup, wait, assisted teleop, drive-on-heading—are action servers invoked by BTs: nav2_behaviors/src/behavior_server.cpp.
Extensions and operational integrations
Pluginlib XML manifests are the central extension boundary across algorithms and behaviors, e.g. nav2_costmap_2d/costmap_plugins.xml, nav2_mppi_controller/critics.xml, and nav2_route/plugins.xml. Optional application servers cover waypoint tasks, following, and docking: nav2_waypoint_follower/src/waypoint_follower.cpp, nav2_following/opennav_following/src/following_server.cpp, nav2_docking/opennav_docking/src/docking_server.cpp. RViz integrations support operator visualization and route/docking tools: nav2_rviz_plugins/plugins_description.xml. Development infrastructure includes Docker/devcontainer support and GitHub/CircleCI workflows: Dockerfile, .devcontainer/devcontainer.json, .github/workflows/build_main_against_distros.yml.
Main entry points: behavior_tree_engine.cpp Behavior Tree Engine · controller_server.cpp Controller Server · map_server.cpp Map Server · costmap_2d_ros.cpp Global & Local Costmaps
Components 20
Bringup & Lifecycle
- Python Robot Client
nav2_simple_commander/nav2_simple_commander/robot_navigator.py - Bringup Launch · Composes localization, navigation servers, maps, and parameters.
nav2_bringup/launch/bringup_launch.py - Lifecycle Manager · Orders activation and monitors server health bonds.
nav2_lifecycle_manager/src/lifecycle_manager.cpp
World Model
- Map & Filter Metadata
nav2_bringup/maps/warehouse.yaml - Map Server · Serves occupancy grids and map persistence.
nav2_map_server/src/map_server/map_server.cpp - AMCL Localization · Estimates robot pose from map, laser, and motion inputs.
nav2_amcl/src/amcl_node.cpp - Global & Local Costmaps · Combines static maps, observations, and filters into collision costs.
nav2_costmap_2d/src/costmap_2d_ros.cpp
Navigation Pipeline
- BT Navigator · Runs configurable navigation and recovery behavior trees.
nav2_bt_navigator/src/bt_navigator.cpp - Navigation Behavior Trees
nav2_bt_navigator/behavior_trees/navigate_to_pose_w_replanning_and_recovery.xml - Behavior Tree Engine
nav2_behavior_tree/src/behavior_tree_engine.cpp - Planner Server · Hosts global-planner plugins and path validation.
nav2_planner/src/planner_server.cpp - Smoother Server · Optionally refines planned paths before tracking.
nav2_smoother/src/nav2_smoother.cpp - Route Server · Plans and tracks routes over GeoJSON graphs.
nav2_route/src/route_server.cpp
Motion & Safety
- Controller Server · Tracks paths using controller and checker plugins.
nav2_controller/src/controller_server.cpp - Velocity Smoother
nav2_velocity_smoother/src/velocity_smoother.cpp - Collision Monitor · Independently constrains or stops motion from sensor data.
nav2_collision_monitor/src/collision_monitor_node.cpp - Recovery Behaviors · Provides spin, backup, wait, teleop, and drive-on-heading actions.
nav2_behaviors/src/behavior_server.cpp
Extensions
- Plugin Contracts · Defines replaceable navigation algorithm contracts.
nav2_core/include/nav2_core/global_planner.hpp - Plugin Manifests · Registers algorithm, critic, behavior, and route extensions.
nav2_costmap_2d/costmap_plugins.xml - Task Application Servers · Waypoint following, robot following, and docking integrations.
nav2_waypoint_follower/src/waypoint_follower.cpp
Connections 29
- Python Robot Client → BT Navigator: NavigateToPose actions
- Bringup Launch → Map Server: launches
- Bringup Launch → AMCL Localization: launches
- Bringup Launch → BT Navigator: launches
- Bringup Launch → Lifecycle Manager: configures
- Lifecycle Manager → Map Server: activates
- Lifecycle Manager → BT Navigator: activates
- Map & Filter Metadata → Map Server: map input
- Map Server → AMCL Localization: occupancy grid
- Map Server → Global & Local Costmaps: static map layer
- AMCL Localization → Global & Local Costmaps: robot pose / TF
- BT Navigator → Navigation Behavior Trees: selects policy
- Navigation Behavior Trees → Behavior Tree Engine: executed by
- Behavior Tree Engine → Planner Server: compute path
- Behavior Tree Engine → Smoother Server: smooth path
- Behavior Tree Engine → Route Server: route operations
- Behavior Tree Engine → Controller Server: follow path
- Behavior Tree Engine → Recovery Behaviors: recovery actions
- Global & Local Costmaps → Planner Server: global costs
- Global & Local Costmaps → Controller Server: local costs
- Planner Server → Smoother Server: planned path
- Smoother Server → Controller Server: refined path
- Controller Server → Velocity Smoother: velocity command
- Velocity Smoother → Collision Monitor: smoothed command
- Plugin Contracts → Planner Server: planner interface
- Plugin Contracts → Controller Server: controller interface
- Plugin Manifests → Global & Local Costmaps: loads layers and filters
- Plugin Manifests → Controller Server: loads controllers and critics
- Task Application Servers → BT Navigator: navigation integration