Navigation

Lupin navigates with Nav2 tuned end-to-end for a holonomic mecanum base, an MPPIController running an Omni motion model so the chassis actually strafes sideways, and costmaps sized for the ~0.8 m gaps between greenhouse plant rows rather than the open rooms Nav2 ships defaults for. Everything lives in one package, lupin_navigation, with one params file as the single source of truth and a small fan of launch wrappers over a shared core.

This page is the runbook and reference for that stack: how the six launch files compose, why Nav2 cannot just come up alongside SLAM, what every load-bearing parameter buys, and how the cmd_vel output threads through arbitration to the wheels. The interesting parts are not the Nav2 defaults Lupin keeps, they are the handful it changes and the ordering it enforces around them.

Launch topology: wrappers over a core

The package ships six launch files, not the single nav2.launch.py an older revision documented. The shape is a core-plus-wrapper pattern on both halves, SLAM and Nav2, with the wrappers existing only to preset the two things that differ between targets: slam:=true and use_sim_time.

The core files take all the real arguments; the wrappers are three lines of IncludeLaunchDescription each. _slam_core.launch.py is underscore-prefixed because you are not meant to run it directly, the use_sim_time arg has no sensible default for both targets, so you always go through slam_sim.launch.py or slam_hardware.launch.py. The recommended manual workflow is slam_<env>.launch.py first, then nav2_<env>.launch.py, and the old ros2 launch slam_toolbox online_async_launch.py ... invocation the package README still shows is retired, it cannot be SIGTERM-restarted for the map-erase feature (see Resetting the map).

Launch arguments

nav2.launch.py is the only file that declares arguments; the wrappers bake them in. All node parameters come from config/nav2_params.yaml, wrapped in a RewrittenYaml that substitutes use_sim_time and the map path (yaml_filename) at launch time.

ros2 launch lupin_navigation slam_sim.launch.py    # slam_toolbox + slam_reset_node
# drive the base a little (teleop) so slam_toolbox has scan context, then:
ros2 launch lupin_navigation nav2_sim.launch.py    # waits for /map, then activates

ros2 launch lupin_navigation slam_hardware.launch.py
# confirm /map and warm the TF:
ros2 run lupin_bringup wait_for_tf odom base_link 30.0
ros2 launch lupin_navigation nav2_hardware.launch.py

Why Nav2 waits: the sentinel cascade

The single biggest why on this page is an ordering dependency that looks like ceremony until you hit the wedge it prevents. Nav2 cannot be launched alongside SLAM. Its lifecycle activation does a one-shot TF lookup of odom -> base_link during local_costmap configure; if that transform is not yet in the buffer the configure throws Invalid frame ID base_link and the managed node stays inactive with no automatic retry, which wedges the entire lifecycle manager. slam_toolbox publishes map -> odom only after it has ingested scans, so on a cold DDS-over-WiFi start there is a real window, ~5-10 s, where the transform simply is not there yet.

lupin_bringup/hardware.launch.py closes that window with a RegisterEventHandler chain that gates each stage on the previous one exiting cleanly.

Each sentinel is a throwaway ros2 topic echo --once (or the wait_for_tf helper) whose process exit fires the next stage. wait_for_map subscribes RELIABLE + TRANSIENT_LOCAL so the QoS negotiation with slam_toolbox's latched /map actually connects, a default-RELIABLE echo would silently never match and the cascade would hang forever. When you run the wrappers by hand, you are the cascade: launch SLAM, eyeball /map in RViz, warm the TF, then launch Nav2.

The bond_timeout WiFi fix

A second cold-start trap lives in the lifecycle managers themselves. Nav2's lifecycle_manager bonds with each managed node and aborts the whole stack if the bond does not form within bond_timeout, which defaults to 4.0 s. Over the FastDDS discovery-server WiFi link the lifecycle-to-server bond round-trips through the robot's discovery server at :11811 and can take longer than 4 s on a cold bring-up, spuriously tripping unable to be reached after 4.00s by bond and killing a launch that was otherwise fine.

MPPI for a holonomic base

The controller is nav2_mppi_controller::MPPIController, chosen from day one with no DWB detour. The single change that makes mecanum driving work is motion_model: "Omni", and the mechanism is worth spelling out because it explains the whole page. MPPI works by sampling a cloud of noised control rollouts and weighting them by cost. With motion_model: Omni the noised distribution is 3-DOF, it samples (vx, vy, wz), so every batch contains candidate trajectories that translate sideways. With a DiffDrive or Ackermann model the vy dimension is constrained to zero, so every sampled trajectory is a forward arc and the holonomic shortcut is never even a candidate. The lateral capability is not penalised away, it is structurally absent from the search.

The velocity envelope is asymmetric forward/back but deliberately symmetric sideways:

The vy symmetry is the same sampling logic one level down: leave vy_min at the Nav2 default of 0.0 and the noised distribution can only push right, so left-strafe samples collapse and the controller explores half the lateral space it should. The MPPI rollout samples batch_size: 2000 trajectories of time_steps: 56 at model_dt: 0.05, running at controller_frequency: 20.0 Hz, with min_y_velocity_threshold: 0.001 so lateral motion is never gated as noise.

The critic stack

MPPI scores each rollout through eight critics with weights chosen to balance path adherence against obstacle avoidance against goal capture, with a deliberately low forward bias for the mecanum base.

That low PreferForwardCritic weight is the holonomic philosophy in one number: the critic stays in the stack so a pure-lateral wiggle is not preferred when forward is equally good, but it is too weak to override a genuinely shorter strafe.

The global planner is nav2_navfn_planner/NavfnPlanner (Dijkstra: use_astar: false, allow_unknown: true, tolerance: 0.5).

Goal tolerance

The goal checker (nav2_controller::SimpleGoalChecker) uses xy_goal_tolerance: 0.25 and a tightened yaw_goal_tolerance: 0.12 rad (~7°). The tight yaw tolerance exists for perception: it frames the AprilTag head-on at each per-tag approach pose so the climate-data read is clean, which couples this dial directly to the mission approach-pose pipeline.

Costmaps for narrow aisles

Both costmaps model the robot as a circle with robot_radius: 0.22 at resolution: 0.05. The inflation is deliberately thin so plant-row aisles stay drivable:

The inflation radius sits barely above the robot radius on purpose: at 0.25 m it leaves only ~0.03 m of true clearance past the 0.22 m footprint, betting on cost_scaling_factor: 5.0 to make the cost falloff steep enough that MPPI threads the aisle on the low-cost spine rather than refusing to enter. A textbook 0.55 m halo on a 0.22 m robot would close a 0.8 m gap completely.

always_send_full_costmap: False is load-bearing on hardware. A full-grid publish serialises the entire OccupancyGrid every cycle; on a KRR-house-scale map that is tens of thousands of cells JSON-encoded on the Pi, every publish, changed or not. Switching to incremental deltas cuts costmap publish bytes ~5-10×, and combined with the slam_toolbox transform_publish_period drop from 50 Hz to 10 Hz, these are the two bandwidth levers that keep the Pi-side rosbridge encoder below its silent-wedge threshold.

Local vs global obstacle ranges

The two costmaps clamp obstacle ranges differently, and the asymmetry is intentional:

Raw 12 m sim-lidar returns produce a noisy global costmap and costly publishes, so the global layer raytraces (clears) out to 12 m but only marks obstacles out to 5 m, which covers across-room geometry in the KRR house without the long-tail noise. The local costmap is a 3×3 m rolling window updating at 5.0 Hz with obstacle_layer + inflation_layer (laser-only in v1; /camera/depth/points exists but is not yet a costmap source). The global costmap adds a static_layer with map_subscribe_transient_local: True and tracks unknown space.

The cmd_vel chain

Nav2 never publishes to /cmd_vel directly. The smoothed output is remapped to /cmd_vel_auto, which feeds the lupin twist_mux as the autonomy input, so autonomy goes through the exact same arbitration the Xbox dead-man and web HMI teleop use.

The inter-stage remaps are the part that trips readers: controller_server remaps its cmd_vel output to /cmd_vel_nav, velocity_smoother subscribes to /cmd_vel_nav and remaps its cmd_vel_smoothed output to /cmd_vel_auto. Publishing to a bare /cmd_vel would hit the vendor gazebo_planar_move teleport plugin in sim and bypass both the mux and the real mecanum controller, so the launch is explicit about never doing it.

The smoother's 3-DOF limits [vx, vy, wtheta] mirror the full MPPI envelope, which is a triple coupling a tuner has to change together:

MPPI            ax_max 2.5  ay_max 2.5  az_max 3.2   vx [0.5,-0.35]  vy ±0.5  wz 1.9
velocity_smoother  max_accel [2.5, 2.5, 3.2]  max_decel [-2.5, -2.5, -3.2]
velocity_smoother  max_velocity [0.5, 0.5, 1.9]  min_velocity [-0.35, -0.5, -1.9]

If MPPI samples outside the smoother's caps, the smoother chops the very trajectory MPPI just optimised and PathAlign drifts. The three sets, MPPI accel, smoother accel, and smoother velocity, must all mirror the MPPI velocity envelope, so changing the top speed means touching all three. See Teleop & manual control for the twist_mux priorities, where /cmd_vel_auto at priority 10 is the lowest driving input but not the absolute lowest, the sim-only /zero_cmd_vel idle guard sits at priority 1 to halt the Gazebo planar driver when every real input has timed out.

Sim and hardware parity

Three params are aligned so the same config behaves identically in Gazebo and on the robot:

• base_link everywhere, every node uses base_link as its base frame (amcl.base_frame_id, all robot_base_frame, slam_toolbox base_frame). The MIRTE URDF publishes no base_footprint.
• odom_topic: /mirte_base_controller/odom, wheel-encoder odometry used by bt_navigator, controller_server, and velocity_smoother. This topic exists in both sim and hardware, unlike the sim-only teleport /odom feed.
• min_laser_range: 0.25 m, applied in AMCL (laser_min_range), slam_toolbox, and both costmaps to filter lidar returns hitting the robot's own body. 12.0 m matches the RPLidar A1 effective max.

The dormant AMCL path uses nav2_amcl::OmniMotionModel (a DiffDrive model would penalise the real lateral motion), with all five noise params alpha1-alpha5 at 0.2 and set_initial_pose: true seeding belief at the vendor spawn pose (x=1.0527, y=0.509611, yaw=0) for headless restarts. To actually use it you would need slam:=false and a saved map served by map_server, the RViz 2D Pose Estimate tool still reseeds at runtime.

The map

maps/krr_house.yaml defines the AWS small-house ("KRR house") world at resolution: 0.05, mode: trinary, origin: [-9.53, -4.68, 0], with occupied_thresh: 0.65 / free_thresh: 0.25. The gotcha is that in slam mode this map is never loaded, map_server is not even instantiated, yet a real path is still required because RewrittenYaml substitutes yaml_filename into the params blob and a literal '' makes the substitution explode. So krr_house.yaml is forwarded as a placeholder in every orchestrated launch purely to keep the YAML rewrite happy.

SLAM configuration

config/slam_toolbox_sim.yaml runs slam_toolbox in mode: mapping with the Ceres solver, resolution: 0.05, and scan_topic: /scan. Despite the _sim filename it is shared sim and hardware, only use_sim_time differs and that arrives as a launch arg, not a baked value. The notable tuning is transform_publish_period: 0.10 (10 Hz, down from the 50 Hz default):

Resetting the map

slam_toolbox 2.6 (Humble) has no runtime "wipe map" service, /slam_toolbox/clear_changes only drops the localization edit buffer, not the scan-built occupancy grid. The pragmatic v1 erase is therefore a process restart, and the clever part is that it heals itself.

The slam_reset_node advertises /lupin/nav/clear_map (std_srvs/srv/Trigger). On call it:

ros2 service call /lupin/nav/clear_map std_srvs/srv/Trigger {}

The whole trick depends on respawn=True + respawn_delay=1.0 on the slam_toolbox Node in _slam_core.launch.py (and the same in hardware.launch.py). SIGTERM the process and respawn brings it back ~1 s later with an empty pose graph, mapping from scratch. This is exactly why the launch spawns slam_toolbox as a direct Node, not via the upstream online_async_launch.py, which has no respawn knob and would leave the kill permanently dead. The web HMI's Erase map button calls this same service.

See also