nav-stack

A Viam navigation stack for mapping, localization, and obstacle-aware navigation on any Viam base. The last release that still bundled Nav2/slam_toolbox is preserved at git tag pre-ros-removal.

This module (viam-labs:nav-stack) provides:

SLAM and navigation run in-process over Viam APIs (lidar point clouds / shm, movement sensor, Base.SetVelocity). No external navigation stack install is required.

flowchart LR
  lidar["Viam lidar(s)"] --> slam["builtin SLAM"]
  odom["Viam movement sensor"] --> slam
  slam -->|"map + pose"| nav["builtin nav"]
  lidar --> nav
  nav -->|"SetVelocity"| base["Viam base"]

• A host running viam-server with Python 3 (Linux is typical; macOS can run the builtin path where serial/shm allow).
• On first deploy, setup.sh creates the Python venv and installs pip requirements.

{
  "name": "slam",
  "api": "rdk:service:slam",
  "model": "viam-labs:nav-stack:slam",
  "attributes": {
    "base": "my-base",
    "movement_sensor": "odometry",
    "lidars": [
      { "name": "front-lidar", "mount": { "x": 0.2, "y": 0.0, "theta": 0.0 } },
      { "name": "rear-lidar",  "mount": { "x": -0.2, "y": 0.0, "theta": 3.14159 } }
    ],
    "mode": "mapping",
    "maps_dir": "/root/.viam/nav-stack/maps",
    "active_map": "ground-floor"
  }
}

A single lidar can be given as "lidar": "front-lidar".

Per-lidar options include mount pose, scan_source (auto / get_laser_scan / point_cloud), height band (z_min / z_max), and obstacles_only (when true, the sensor is used only for obstacle avoidance — not SLAM matching or mapping). When mount is omitted, the module fills it from the Viam framesystem (component → base), converting Viam's Y-forward base axes into nav-stack's ROS X-forward mounts so scans align with odom. Explicit mount still wins. Example depth camera for avoidance only:

{
  "name": "depth-cam",
  "scan_source": "point_cloud",
  "obstacles_only": true,
  "cloud_frame": "camera_optical",
  "shm_name": "",
  "max_range": 4.0,
  "min_range": 0.4,
  "z_min": 0.15,
  "z_max": 1.5,
  "mount": { "x": 0.15, "y": 0.0, "z": 0.4, "theta": 0.0 }
}

RealSense / OpenCV depth clouds use optical axes (Z forward). Set cloud_frame: "camera_optical" so depth is remapped to X-forward before the mount and height band; without it, depth collapses into Z and paints a blob on the robot in the local costmap. Refresh rate is nav-side obstacles_only_rate_hz (default 5); set a POSIX shm_name (or use shm-pointcloud) before pushing toward 10–20 Hz.

Obstacles an obstacles_only camera saw are remembered (within 1.2 m, up to 20 s) after they leave its horizontal view, e.g. the low part of a curved table leg beside the robot that the lidar plane misses. A point is forgotten when a newer frame looks at it and sees nothing, or when the body covers it. Set the camera's horizontal field of view with fov_deg (default 87, RealSense D4xx depth).

avoid_obstacles_above_cart (default true) remembers those same depth returns out to 2.5 m after they leave the vertical view (vfov_deg, default 58). A later frame that still points at that spot but can no longer see that height does not clear them, so the cart does not drive underneath. By default the band is whatever the depth camera already reports, up to its z_max. Set cart_height_m only to ignore returns at or below the top of the cart.

Point-cloud returns whose base-frame XY lies inside the robot's box are dropped (crop_inside_footprint, default on once a footprint is known). That removes a stand or mast on the chassis without a radial min_range, so a hit the same distance in front of the bumper is kept. Set "crop_inside_footprint": false to keep those returns.

Footprint resolution (SLAM, navigation and navigation-external alike): the base's framesystem box geometry is read as Viam +Y forward (length), +X right (width). footprint_length_m and footprint_width_m are optional and each overrides its own side of that box, so setting only one keeps the other from the framesystem. A side neither sets takes 2 × robot_radius when the other side is known. With no box and no footprint_*, navigation stays on its circular robot_radius model and SLAM crops a robot_radius disc. 0 and null mean "not set". Nav's robot_radius defaults to the box's half-width.

Tuning via Viam config (no YAML editing required):

Example with map resolution tuning:

{
  "name": "slam",
  "model": "viam-labs:nav-stack:slam",
  "attributes": {
    "base": "my-base",
    "movement_sensor": "odometry",
    "lidars": [{ "name": "front-lidar" }],
    "mode": "localizing",
    "maps_dir": "/root/.viam/nav-stack/maps",
    "active_map": "ground-floor",
    "resolution": 0.05,
    "max_laser_range": 25.0,
    "global_localize_on_start": true,
    "global_localize_on_start_options": {
      "map_source": "live",
      "full_map": true
    },
    "global_localize_on_start_refine": true,
    "global_localize_on_start_refine_delay_s": 8.0,
    "global_localize_on_start_refine_max_passes": 3,
    "global_localize_on_start_target_score": 0.7,
    "global_localize_on_start_target_ray_mae_m": 0.4,
    "global_localize_on_start_post_apply_refine": true,
    "global_localize_on_start_post_apply_refine_delay_s": 8.0,
    "global_localize_on_start_post_apply_refine_options": {
      "map_source": "live"
    },
    "global_localize_on_start_refine_options": {
      "local_yaw_window_deg": 120.0
    }
  }
}

Startup auto-localize evaluates candidate poses first (apply: false) and only publishes the best pose at the end, so early weak passes do not lock in a bad seed.

Scan freshness / capture-time stamping. When the lidar (e.g. viam-labs:mir-base) reports a per-scan cache age (age_s) in its get_laser_scan output, scans are stamped at its capture time (read_start - age_s) instead of read time. This keeps obstacles and scan-match registered where the robot actually was when the scan was captured — important on a moving/rotating robot where a cached scan stamped "now" would smear geometry and drive localization off. Scans older than scan_max_age_s are dropped for the SLAM path. Producers that don't report age_s fall back to read-time stamping (unchanged behavior).

mode changes take effect on reconfigure (or via start_mapping / start_localizing DoCommands).

For a bare IMU movement sensor (Wit, etc. with accel + gyro, no wheel pose), /odom yaw is integrated from gyro Z only. Absolute orientation / AHRS yaw from get_readings() is not snapped into the odom pose. With map_when_still, published TF XY stays frozen (IMU accel must not be the slam prior) while gyro yaw still updates for the App arrow; builtin SLAM uses that odom yaw as its match prior. Duplicated corridors after driving a loop are usually failed loop closure (gyro drift) — pause often facing clear walls and prefer smaller circuits. Do not loosen loop_match_minimum_chain_size / loop_search_* aggressively; that trades missed closures for false corridor snaps and warped ghost maps.

Wall-line yaw correction (anti-banana). Long straight walls drawn as curves usually mean gyro heading walked off while driving parallel to the wall. With map_when_still + point-cloud lidars, wall_yaw_correction defaults on: each accepted pause scan looks for a long side wall (≥ wall_yaw_min_length_m) and soft-corrects /odom yaw by at most wall_yaw_max_step_deg (blended by wall_yaw_blend) so the wall lines up with robot +X. Status field wall_yaw reports the last observation. Disable with "wall_yaw_correction": false if a cluttered side repeatedly misleads the fit.

For Viam wheeled bases (rdk:builtin:wheeled) and MiR250 (viam-labs:mir-base), keep the default "base_velocity_convention": "viam" so forward builtin nav commands map to Viam linear.y (Viam wheeled / MiR expect forward on Y, not X). Use "ros" only for bases that drive on linear.x. Legacy "mir" is accepted and normalized to "viam". Odometry from viam-labs:mir-base:movement stays in ROS convention and does not need swapping. Nav-stack stops builtin nav motion with set_velocity(0) (not Base.stop()), so MiR Manualcontrol and go_to_location keep working after a navigation cancel or goal completion.

The MiR250 is differential drive — use "kinematics": "differential" (the default). Configuring omni makes builtin nav command lateral velocities the robot cannot execute. Tune lookahead / tolerances under the builtin attribute block.

For MiR movement sensors (viam-labs:mir-base:movement), the bridge reads a single get_readings() per odom tick. It uses odom_position_x_m / odom_position_y_m / odom_yaw_deg when present (true /odom frame from mir-base ≥ the odom-fields update). Map-frame position_x_m/position_y_m and fused yaw_deg are not used for /odom — builtin SLAM needs a smooth odom frame. Until mir-base exposes the odom fields, orientation falls back to velocity integration; upgrade mir-base or patch it to publish odom_* keys from the parsed /odom message. Raise mir-base's mir_rosbridge_timeout_s attribute (≥5, on the viam-labs:mir-base component, not this module) and scan_rate_hz / odom_rate_hz (e.g. 15–20) if updates lag.

Breaking change: both navigation models are now rdk:service:motion (previously rdk:service:generic). Update robot configs accordingly; attributes are unchanged.

{
  "name": "nav",
  "api": "rdk:service:motion",
  "model": "viam-labs:nav-stack:navigation",
  "attributes": {
    "slam_service": "slam",
    "base": "my-base",
    "kinematics": "differential",
    "robot_radius": 0.22,
    "footprint_width_m": 0.59,
    "footprint_length_m": 0.72,
    "max_linear_velocity": 0.4,
    "max_vel_theta": 1.0,
    "clearance_m": 0.2,
    "xy_goal_tolerance": 0.25,
    "yaw_goal_tolerance": 0.35,
    "nav_backend": "builtin",
    "builtin": {
      "replan_period_s": 1.0
    }
  }
}

Map-frame goals use the standard Motion API. Pose units are millimeters and orientation degrees (planar OrientationVector: o_z=1, yaw in theta):

from viam.proto.common import Pose
from viam.services.motion import MotionClient

nav = MotionClient.from_robot(robot, "nav")
execution_id = await nav.move_on_map(
    component_name="my-base",
    destination=Pose(x=3500, y=-1000, z=0, o_x=0, o_y=0, o_z=1, theta=0),
    slam_service_name="slam",
)
# Non-blocking: poll progress
plan = await nav.get_plan("my-base", execution_id=execution_id)
await nav.stop_plan("my-base")  # cancel

MoveOnMap returns an execution_id. Use GetPlan / ListPlanStatuses for status (IN_PROGRESS / SUCCEEDED / STOPPED / FAILED). Move and MoveOnGlobe are not implemented. Locations, zones, and simple go_to_* remain available via DoCommand (including the meters/radians navigate_to_point alias used by existing scripts). Tune replan rate and recoveries under the builtin attribute block (replan_period_s, recovery_wait_duration_s, backup settings). Changes apply on reconfigure.

Set "kinematics": "omni" and a non-zero max_vel_y for omnidirectional bases.

Use viam-labs:nav-stack:navigation-external to drive builtin navigation from any rdk:service:slam (for example a third-party RTAB-Map module). Same Motion + DoCommand surface as navigation; map/pose come from the SLAM service (GetPosition, get_grid), scans from configured lidars, and drive from Base.SetVelocity.

• slam_service names an rdk:service:slam dependency. It must support GetPosition() and a get_grid DoCommand returning {rows, cols, xMin, yMin, cellSize, data} with int8 cells (-1/0/100).

{
  "name": "nav",
  "api": "rdk:service:motion",
  "model": "viam-labs:nav-stack:navigation-external",
  "attributes": {
    "slam_service": "rtabmap",
    "base": "my-base",
    "kinematics": "differential",
    "lidars": [{ "name": "mid360", "scan_source": "point_cloud" }],
    "movement_sensor": "mid360-imu",
    "imu_odom_mode": "accel_only",
    "lidar_odom_enabled": true,
    "robot_radius": 0.22,
    "max_linear_velocity": 0.4,
    "clearance_m": 0.2
  }
}

Optional attributes: trust_movement_sensor_pose (default false), snap_heading (default false), plus the same lidar/odometry tuning fields as the SLAM service and the same builtin block as navigation. The built-in navigation model is unchanged; use it when you map with nav-stack:slam.

Bring up slam + navigation against a raycast floorplan so you can map, localize, plan/execute paths (including from nav-stack-ui), and repeat the same path after a pose reset — without real lidars or a wheeled base.

Architecture:

• viam-labs:nav-stack:sim-base — real Viam Base; SetVelocity / teleop update a shared SimWorld
• SLAM sim.enabled — in-process SimSensors (raycast lidar + integrated odom); no Camera deps
• Real slam / navigation / optional nav-camera APIs unchanged for the UI

Example fragment (configure sim-base before slam so the world exists; slam may also create it):

{
  "components": [
    {
      "name": "sim-base",
      "api": "rdk:component:base",
      "model": "viam-labs:nav-stack:sim-base",
      "attributes": {
        "world_name": "default",
        "seed_x": 1.0,
        "seed_y": 1.0,
        "seed_theta": 0.0
      }
    }
  ],
  "services": [
    {
      "name": "slam",
      "api": "rdk:service:slam",
      "model": "viam-labs:nav-stack:slam",
      "attributes": {
        "base": "sim-base",
        "slam_backend": "builtin",
        "mode": "mapping",
        "sim": {
          "enabled": true,
          "world_name": "default",
          "seed_x": 1.0,
          "seed_y": 1.0
        }
      }
    },
    {
      "name": "nav",
      "api": "rdk:service:motion",
      "model": "viam-labs:nav-stack:navigation",
      "attributes": {
        "slam_service": "slam",
        "base": "sim-base",
        "nav_backend": "builtin"
      }
    }
  ]
}

Notes:

• Default world is a built-in L-corridor; set sim.map_path / map_path on sim-base to a .npy grid (+ optional sibling .json with resolution, origin_x, origin_y).
• Lidars and movement sensors are omitted when sim.enabled is true.
• Reset pose for repeatable runs: sim-base DoCommand {"command": "reset"} (optional x / y / theta).

Local bring-up (viam-server):

./scripts/run_local_sim.sh          # creates venv if needed, serves on :8081 (--no-tls)
# BIND=:8082 ./scripts/run_local_sim.sh
# ./scripts/run_local_sim.sh --print   # write resolved config only

Uses sample_configs/local_sim.json (rewrites executable_path + maps_dir to absolute paths). Resources: sim-base, slam, nav, nav-view.

Point nav-stack-ui at it (fully local, no cloud/API keys):

# in nav-stack-ui/.env
VITE_HOST=http://localhost:8081
VITE_CAMERA_NAME=nav-view
VITE_SLAM_SERVICE=slam
VITE_NAV_SERVICE=nav
VITE_BASE_NAME=sim-base

Then npm run dev in nav-stack-ui. Teleop sim-base to map, navigate with nav, reset with DoCommand {"command":"reset"} on sim-base.

viam-labs:nav-stack:nav-camera is a read-only rdk:component:camera that renders, as an image you can watch in the Viam app's camera stream, what the navigation service is doing — no external visualizer required. It draws builtin nav's global costmap (so you see the inflated cost surface the planner actually reasons over) with these overlays:

• global plan (/plan) in green — the route to the current goal;
• plan history — superseded plans for the current goal, greyed out and faded oldest→faintest, so you can watch how the route changed as the robot replanned (reset on each new goal);
• local plan (/local_plan) in orange — the controller's short-horizon path;
• robot pose + footprint (red arrow + blue polygon) from the map → base_link TF;
• goal marker (magenta) with a heading tick.

Occupancy colouring: unknown = dark grey, free = light, optional soft inflation = grey→orange gradient, hard clearance_m next to walls = amber, lethal = near-black. The camera is workspace: only clearance_m around an obstacle is drawn as keep-out. Planning still uses the body+clearance C-space disk (a remaining one-cell gap is room for the robot center). World "up" renders as image up (image-up).

It reads directly from the running navigation service's in-process viz store (found by the navigation attribute), so there is no extra ROS process and no round-trip. Because it consumes only builtin nav's standard costmap/plan topics, it works with any SLAM backend and with either navigation or navigation-external.

{
  "name": "nav-view",
  "api": "rdk:component:camera",
  "model": "viam-labs:nav-stack:nav-camera",
  "attributes": {
    "navigation": "nav"
  }
}

• navigation (required) — the name of the navigation / navigation-external service to visualize. It is also declared as a dependency so it starts first.
• Optional: max_dim (longest output edge in px, default 700), plan_history_len (faded trail length, default 8), robot_radius_m (footprint fallback + pose-arrow size, default 0.22), and per-overlay toggles show_global_plan / show_local_plan / show_pose / show_footprint / show_goal / show_history (all default true).

Windowing — by default the camera renders the whole map. window_mode crops/zooms it:

• "full" (default) — the entire occupancy grid.
• "follow" — a window_size_m-metre square that tracks the robot (falls back to the goal, then the grid centre, if there's no pose yet). Best for large maps where the whole grid is too zoomed-out to see the plan. window_size_m defaults to 6.0.
• "region" — a fixed map-frame bounding box from window_min_x / window_min_y / window_max_x / window_max_y (metres). Best for watching one fixed spot (e.g. a doorway). If any bound is missing it falls back to "full".

{ "navigation": "nav", "window_mode": "follow", "window_size_m": 5.0 }

Until a costmap is available, the camera returns a placeholder frame.

DoCommand:

• {"command": "legend"} — the colour key as a printable string in legend, so you can read the map without guessing colours.
• {"command": "stats"} (or any other command) — a text summary: whether the bridge/costmap is present, plan point counts, current goal/pose. Handy for verifying without a video stream.

1. Configure the SLAM service with "mode": "mapping" (or call start_mapping).
2. Drive the base around manually (Viam remote control / SDK). The module only takes over the base while navigating, so manual driving and mapping don't conflict.
3. Optionally force a pose-graph optimization mid-map (serialize → reload so useful after closing a loop that looks bent): do_command({"command": "optimize"}).
4. Save when done: do_command({"command": "save_map"}).

await slam.do_command({"command": "start_localizing", "map": "ground-floor"})
await slam.do_command({"command": "set_initial_pose", "pose": {"x": 0, "y": 0, "theta": 0}})
# XY roughly right but heading unknown/wrong? builtin SLAM only self-corrects
# ~±30° of yaw — add refine to run a full-yaw seeded scan match and apply it:
await slam.do_command({"command": "set_initial_pose",
                       "pose": {"x": 0, "y": 0, "theta": 0}, "refine": True})

If the nav-stack map is aligned with the MiR onboard map, seed from the MiR pose instead (continuous laser matching on the MiR side; nav-stack still needs one /initialpose seed):

await slam.do_command({
    "command": "start_localizing",
    "map": "ground-floor",
    "use_mir_pose": True,
})
# or after localizing:
await slam.do_command({"command": "relocalize", "use_mir_pose": True})

Preferred: match live lidar against the saved nav-stack occupancy map (no MiR map pose):

await slam.do_command({"command": "global_localize"})
# search the whole map when pose is unknown:
await slam.do_command({"command": "global_localize", "full_map": True})
# narrow search around a rough guess (meters):
await slam.do_command({
    "command": "global_localize",
    "pose": {"x": 1.0, "y": 2.0, "theta": 0.0},
    "search_radius_m": 6.0,
})
# preview-only (do not publish /initialpose yet):
await slam.do_command({"command": "global_localize", "apply": False})

Returned fields include pose, score, candidates_evaluated, scan_points_used, in_map_points, hit_rate, ray_score, and ray_mae_m. If in_map_points is low or ray_mae_m is high, the match is unreliable. Speed/robustness knobs: local_yaw_window_deg, coarse_position_step_m, coarse_yaw_step_deg, max_scan_points, min_in_map_points, min_in_map_ratio, hit_radius_cells, ray_refine_candidates, ray_refine_beams, ray_step_m, ray_weight.

By default, global_localize now auto-falls back to full-map search when local search quality is weak. Tune or disable with auto_full_map_fallback, fallback_score_threshold, and fallback_hit_rate_threshold.

When you are roughly in the right place but nav-stack drifted (~2 m), trigger scan-to-map matching with wider covariance:

await slam.do_command({"command": "relocalize"})

Full DoCommand reference (all commands, args, aliases): docs/navigation-docommands.md.

nav is a Motion service — prefer move_on_map for map goals (mm / degrees). DoCommand navigate_to_point / locations still use meters / radians:

# Save the robot's current spot as "kitchen"
await nav.do_command({"command": "add_location", "name": "kitchen"})
# Or specify a pose (meters / radians, map frame)
await nav.do_command({"command": "add_location", "name": "dock",
                      "pose": {"x": 1.0, "y": 2.0, "theta": 0.0}})

await nav.do_command({"command": "navigate_to_location", "name": "kitchen"})
await nav.do_command({"command": "navigate_to_point", "x": 3.5, "y": -1.0})
await nav.do_command({"command": "get_status"})
# Preview a path without moving (builtin nav ComputePathToPose). Returns map-frame
# waypoints in meters/radians; also draws on nav-camera if configured:
# await nav.do_command({"command": "plan_to_point", "x": 3.5, "y": -1.0})
# await nav.do_command({"command": "plan_to_location", "name": "kitchen"})
# → {"status": "planned", "feasible": true, "path": [{"x":..., "y":..., "theta":...}, ...],
#    "length_m": ..., "planning_time_s": ...}
# Then run the previewed goal:
# await nav.do_command({"command": "execute_plan"})
# Motion MoveOnMap can also preview: move_on_map(..., extra={"preview": true})
# get_status includes last_cmd_vel plus cmd_vel_history (last ~20 distinct
# ROS/Viam SetVelocity samples, oldest→newest — survives cancel/stop zeros)
# Plain-English snapshot of what nav is commanding right now (returns immediately):
# await nav.do_command({"command": "describe_motion"})
# → {"summary": "builtin nav navigating (goal 'kitchen' is about 2.5 m ahead and to the
#    right): driving forward at moderate speed while turning hard right for
#    about 3.0 s — closing distance toward the goal, steering toward the goal",
#    "goal_relative": "...", "toward_goal": "...", ...}
# Probe the builtin nav SetVelocity path without navigating:
# await nav.do_command({"command": "test_drive", "vx": 0.5, "angular_z_deg_s": 57.3, "duration_s": 2})
await nav.do_command({"command": "cancel"})

# Suspend/resume: cancel the active goal but remember it (for safety stops).
# resume re-issues navigate/simple-go to the same pose (builtin nav replans from here).
# await nav.do_command({"command": "suspend", "reason": "safety"})
# → {"status": "suspended", "goal": {"x": ..., "y": ..., "theta": ..., "motion": "builtin"}}
# get_status includes suspended + suspended_goal while held
# await nav.do_command({"command": "resume"})
# → {"status": "navigating", "resumed": true, "target": {...}, "execution_id": "..."}
# cancel / stop_plan / a new navigate clears any suspended goal (no resume).

Locations CRUD: add_location, get_location, list_locations, update_location, delete_location (alias remove_location), delete_all_locations.

Routes are ordered lists of location waypoints (same map). CRUD: add_route, get_route, list_routes, update_route, delete_route (alias remove_route), delete_all_routes; waypoint ops: add_waypoint, update_waypoint, remove_waypoint / delete_waypoint, move_waypoint, set_waypoints, clear_waypoints, list_waypoints. Drive a saved route (or an inline waypoint list) with navigate_route. See docs/navigation-docommands.md.

Physical obstacles are avoided automatically. Virtual zones are user-defined:

# A no-go region
await nav.do_command({"command": "add_zone", "name": "fragile-display",
                      "type": "keepout",
                      "geometry": {"type": "circle", "center": [4.0, 1.5], "radius": 0.8}})
# A slow-down region (30% of max speed)
await nav.do_command({"command": "add_zone", "name": "busy-aisle",
                      "type": "speed_limit", "speed_pct": 30,
                      "geometry": {"type": "polygon",
                                   "points": [[0,0],[2,0],[2,3],[0,3]]}})

Zones CRUD: add_zone, get_zone, list_zones, update_zone, delete_zone, delete_all_zones. Geometry types: circle, box (optionally rotation), polygon. Locations, zones, and routes are stored per-map. Keepout zones are obstacles for planning; speed-limit zones scale linear velocity while the robot is inside them.

list_maps, get_active_map, set_active_map, rename_map, delete_map, clear_map, clear_obstacles (alias erase_obstacles; paint free space in a disk — builtin SLAM; args x/y or pose, radius_m, optional save), start_mapping, start_localizing, save_map, optimize (alias optimize_graph; mapping mode — force pose-graph SPA via serialize/deserialize reload), get_mode, get_status (SLAM health; optional probe_sensors: false to skip a one-shot lidar/odom read; includes measured scan_hz / lidar_read_hz over the last ~2 s plus configured scan_rate_hz — with map_when_still, expect low scan_hz while driving), set_initial_pose, global_localize (lidar scan match against saved map; optional full_map, search_radius_m, apply, local_yaw_window_deg, max_scan_points, auto_full_map_fallback), relocalize (alias refine_localization; optional pose, location), revisit_check / get_revisit_check (mapping-mode revisit watchdog cycle on demand; optional apply to force or dry-run the odom correction; optional yaw_flip to take the opposite corridor heading; flip_yaw_only to reverse the current map heading in place when XY is already right).

./setup.sh                 # create venv (add python -m pytest tests/    # pure-Python unit tests (no ROS needed)
./build.sh                 # package module.tar.gz

Geometry/format conversions and map/location/zone stores are unit-tested directly.

• 2D ground-robot navigation. One base per service.
• Differential and omnidirectional kinematics supported; Ackermann is out of scope.
• Multi-lidar merging for SLAM assumes roughly coplanar lidars with accurate mount transforms; all lidars still contribute to builtin obstacle avoidance regardless. Set "obstacles_only": true on a lidar (e.g. a short-range depth camera) to include it in avoidance / local costmap only — it is excluded from SLAM scan-matching and map updates.