> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration field reference

> Complete configuration structure, schema defaults, and a downloadable calibrated example.

Use [Configure navigation](/navigation/configuration) first to choose between
dotted overrides and a complete config. This reference inventories every
configuration field in the Pre-release schema.

[Download JSON Schema](/assets/navigation/navigation-config.schema.json) ·
[Download complete R1Pro omni YAML](/assets/navigation/r1pro-omni.yaml)

The tables show **generic schema defaults**, not recommended tuning and not
necessarily your robot's defaults. A profile overrides them, and geometry
propagation may derive further values. Inspect `nav.config` for actual values.
“Factory / see resolved YAML” means a nested object or collection is built
by the config loader; the downloadable YAML supplies a complete resolved example.

The schema is a snapshot of the documented code. An agent should use the
installed runtime's schema and validation when they differ. It is a JSON
Schema for the nested config dictionary, not a tool-call schema.

## Units and validation

Distances are metres, speeds m/s, angular speeds rad/s, and frequencies Hz.
Names ending in `_s`, `_m`, `_hz`, or `_deg` specify seconds, metres,
Hz, or degrees. Coordinate arrays have the frame and shape described in the
configuration guide or matching robot profile.

The runtime validates more than JSON Schema alone describes. Root motion caps
and update rates must be finite and positive, goal thresholds and failure
tolerance finite and nonnegative, and max\_steps positive. Camera matrices,
transform lengths, image sizes, enumerated modes, and footprint dependencies
are checked by the loader. Keep strict booleans and integer ports in runtime
settings; unknown root/runtime fields and unknown dotted overrides are rejected.
Do not interpret an unconstrained array in JSON Schema as accepting arbitrary
calibration dimensions.

## Root fields

| Field | Meaning | Generic default |
| - | - | - |
| `max_linear_vel` | Maximum linear speed, m/s. | `0.35` |
| `max_angular_vel` | Maximum angular speed, rad/s. | `0.2` |
| `min_turn_forward` | Minimum forward motion setting during turns, m/s. | `0.02` |
| `controller_failure_tolerance_s` | Time tolerated for controller failure, seconds. | `0.0` |
| `control_hz` | Control update frequency, Hz. | `10.0` |
| `diag_export_hz` | Diagnostic export frequency, Hz. | `3.0` |
| `hloc_hz` | Cloud localization query frequency, Hz. | `1.0` |
| `intermediate_threshold_m` | Distance threshold for intermediate goals, metres. | `1.5` |
| `final_threshold_m` | Distance threshold for final goal, metres. | `1.0` |
| `max_steps` | Maximum control-loop steps. | `10000` |
| `async_odom_hz` | Odometry polling frequency, Hz. | `40.0` |
| `async_lidar_hz` | LiDAR polling frequency, Hz. | `20.0` |
| `async_lidar_control_reserve_s` | Reserve between LiDAR work and the control loop, seconds. | `0.0` |
| `self_exclusion_m` | Legacy robot self-return exclusion size, metres. | `0.0` |
| `planner_exclusion_m` | Legacy planner exclusion size, metres. | `0.0` |
| `self_exclusion_box_m` | Body-frame \[x\_min, x\_max, y\_min, y\_max], metres. | `[]` |

## Nested sections

A section table is relative to that section: field `backend` under
`runtime` is the override path `runtime.backend`. Use the nested mapping
shape in YAML or JSON. Expand the section you need.

<AccordionGroup>
  <Accordion title="safety">
    Collision gating, standoff, sensor freshness, and Nav2 collision-monitor policies. mode selects gate or nav2. Geometry and stopping behavior must match the robot.

    | Field | Type | Generic default |
    | - | - | - |
    | `enabled` | `boolean` | `true` |
    | `mode` | `string` | `"gate"` |
    | `nav2` | `Nav2CollisionMonitorConfig` | `factory / see resolved YAML` |
    | `separating_allowance` | `SeparatingAllowanceConfig` | `factory / see resolved YAML` |
    | `self_hit_min_range_m` | `number` | `factory / see resolved YAML` |
    | `front_stop_m` | `number` | `0.3` |
    | `front_stop_min_m` | `number` | `0.0` |
    | `front_stop_react_s` | `number` | `0.35` |
    | `front_slow_m` | `number` | `0.85` |
    | `front_half_width_m` | `number` | `0.45` |
    | `stop_core_half_width_frac` | `number` | `0.8` |
    | `front_bumper_offset_m` | `number` | `0.22` |
    | `front_turn_sweep_half_width_m` | `number` | `0.75` |
    | `front_turn_stop_w_radps` | `number` | `0.12` |
    | `front_turn_sweep_q` | `number` | `0.15` |
    | `front_turn_sweep_min_points` | `integer` | `8` |
    | `front_turn_slow_m` | `number` | `0.45` |
    | `near_front_mtf_soft_band_m` | `number` | `0.22` |
    | `near_front_mtf_min_scale` | `number` | `0.35` |
    | `rear_stop_m` | `number` | `0.3` |
    | `rear_half_width_m` | `number` | `0.35` |
    | `rear_bumper_offset_m` | `number` | `0.22` |
    | `rear_slow_band_m` | `number` | `0.35` |
    | `rear_turn_sweep_half_width_m` | `number` | `0.75` |
    | `rear_turn_stop_w_radps` | `number` | `0.12` |
    | `rear_turn_sweep_q` | `number` | `0.15` |
    | `rear_turn_sweep_min_points` | `integer` | `8` |
    | `coordinated_vw_scaling` | `boolean` | `true` |
    | `coordinated_vw_min_scale` | `number` | `0.4` |
    | `lidar_max_points` | `integer` | `0` |
    | `walk_init_threshold_mps` | `number` | `0.0` |
    | `predictive_enabled` | `boolean` | `false` |
    | `predictive_horizon_s` | `number` | `0.8` |
    | `predictive_dt_s` | `number` | `0.1` |
    | `predictive_front_extent_m` | `number` | `0.3` |
    | `predictive_rear_extent_m` | `number` | `0.25` |
    | `predictive_half_width_m` | `number` | `0.3` |
    | `predictive_margin_m` | `number` | `0.03` |
    | `predictive_min_points` | `integer` | `1` |
    | `barrier_enabled` | `boolean` | `false` |
    | `barrier_a_brake_mps2` | `number` | `0.6` |
    | `barrier_margin_m` | `number` | `0.05` |
    | `barrier_hw_base_m` | `number` | `0.26` |
    | `barrier_hw_turn_gain_m_per_radps` | `number` | `0.08` |
    | `barrier_front_extent_m` | `number` | `0.28` |
    | `barrier_rear_extent_m` | `number` | `0.25` |
    | `barrier_horizon_s` | `number` | `1.5` |
    | `barrier_dt_s` | `number` | `0.05` |
    | `barrier_block_floor_mps` | `number` | `0.1` |
    | `barrier_self_hit_min_range_m` | `number` | `-1.0` |
    | `barrier_rot_radius_m` | `number` | `-1.0` |
    | `barrier_footprint_polygon` | `any` | `null` |
  </Accordion>

  <Accordion title="lidar_filter">
    LiDAR height and range filtering before obstacle processing.

    | Field | Type | Generic default |
    | - | - | - |
    | `z_ground_max` | `number` | `-0.35` |
    | `z_lethal_max` | `number` | `0.5` |
    | `z_overhang_max` | `number` | `1.8` |
  </Accordion>

  <Accordion title="dwa">
    Dynamic Window Approach sampling, scoring, and kinematic parameters; relevant when using the DWA controller.

    | Field | Type | Generic default |
    | - | - | - |
    | `predict_time` | `number` | `1.7` |
    | `sim_time_samples` | `integer` | `10` |
    | `velocity_samples` | `integer` | `20` |
    | `yawrate_samples` | `integer` | `20` |
    | `obs_cost_gain` | `number` | `0.02` |
    | `to_goal_cost_gain` | `number` | `24.0` |
    | `speed_cost_gain` | `number` | `0.0` |
    | `path_cost_gain` | `number` | `32.0` |
    | `path_align_cost_gain` | `number` | `32.0` |
    | `path_align_forward_m` | `number` | `0.1` |
    | `goal_align_cost_gain` | `number` | `24.0` |
    | `goal_align_forward_m` | `number` | `0.1` |
    | `path_cost_tolerance_m` | `number` | `0.0` |
    | `path_align_obstacle_gate_m` | `number` | `0.0` |
    | `path_align_gated_scale` | `number` | `0.0` |
    | `osc_cost_gain` | `number` | `1.0` |
    | `use_speed_cost` | `boolean` | `true` |
    | `footprint_cost_gain` | `number` | `0.0` |
    | `footprint_front_extent_m` | `number` | `0.3` |
    | `footprint_rear_extent_m` | `number` | `0.25` |
    | `footprint_half_width_m` | `number` | `0.3` |
    | `footprint_margin_m` | `number` | `0.02` |
    | `footprint_soft_buffer_m` | `number` | `0.2` |
    | `footprint_min_points` | `integer` | `1` |
    | `footprint_hard_collision` | `boolean` | `false` |
    | `footprint_adaptive_hw_min_m` | `number` | `0.0` |
    | `footprint_adaptive_slack_m` | `number` | `0.02` |
    | `footprint_polygon` | `any` | `null` |
    | `footprint_turn_dilation_m_per_radps` | `number` | `0.0` |
    | `inflation_radius_m` | `number` | `-1.0` |
    | `osc_release_ticks` | `integer` | `8` |
    | `osc_zero_tol` | `number` | `0.001` |
    | `robot_radius` | `number` | `0.554` |
    | `footprint_padding` | `number` | `0.05` |
    | `escape_radius_scale` | `number` | `0.75` |
    | `escape_v_max` | `number` | `0.15` |
    | `rollout_distance_m` | `number` | `0.0` |
    | `obs_range` | `number` | `2.5` |
    | `costmap_size_m` | `number` | `-1.0` |
    | `costmap_resolution_m` | `number` | `-1.0` |
    | `min_vel_x` | `number` | `0.0` |
    | `min_velocity` | `number` | `0.0` |
    | `min_yawrate` | `number` | `0.05` |
    | `max_accel` | `number` | `2.5` |
    | `max_decel` | `number` | `2.5` |
    | `max_d_yawrate` | `number` | `3.2` |
    | `sim_period` | `number` | `0.1` |
    | `slow_velocity_th` | `number` | `0.1` |
    | `goal_threshold` | `number` | `0.8` |
    | `velocity_source` | `string` | `"measured"` |
  </Accordion>

  <Accordion title="stuck">
    Progress and stall detection windows and thresholds.

    | Field | Type | Generic default |
    | - | - | - |
    | `stuck_timeout_sec` | `number` | `20.0` |
    | `stuck_progress_epsilon_m` | `number` | `0.15` |
    | `stuck_progress_epsilon_rad` | `number` | `0.0` |
    | `osc_window_steps` | `integer` | `40` |
    | `osc_dist_progress_cap_m` | `number` | `0.12` |
    | `front_constraint_progress_cap_m` | `number` | `0.1` |
    | `recovery_rearm_min_no_progress_sec` | `number` | `6.0` |
    | `recovery_rearm_divergence_m` | `number` | `0.18` |
    | `recovery_rearm_max_per_waypoint` | `integer` | `1` |
  </Accordion>

  <Accordion title="recovery">
    Recovery behavior and round-robin policy. mode selects none, simple, or adaptive; presets are nav2\_faithful, deployment\_legacy, or benchmark\_legacy.

    | Field | Type | Generic default |
    | - | - | - |
    | `mode` | `string` | `"adaptive"` |
    | `max_per_waypoint` | `integer` | `4` |
    | `blocked_rearm_sec` | `number` | `5.0` |
    | `cooldown_ticks` | `integer or null` | `null` |
    | `round_robin_preset` | `string` | `"nav2_faithful"` |
    | `schedule` | `array[any]` | `factory / see resolved YAML` |
    | `profile` | `RecoveryProfileConfig` | `factory / see resolved YAML` |
    | `escalation_distance_scale` | `number` | `0.5` |
    | `escalation_distance_cap_m` | `number` | `0.6` |
  </Accordion>

  <Accordion title="pose_align">
    Terminal position/heading alignment. It is used when the final mission goal includes a heading; plain XY goals do not request heading alignment.

    | Field | Type | Generic default |
    | - | - | - |
    | `yaw_tolerance_rad` | `number` | `-1.0` |
    | `terminal_spin` | `boolean` | `false` |
    | `max_spin_attempts` | `integer` | `3` |
    | `spin_min_rot_vel` | `number` | `-1.0` |
    | `spin_max_rot_vel` | `number` | `-1.0` |
    | `spin_acc_lim` | `number` | `-1.0` |
  </Accordion>

  <Accordion title="velocity_smoother">
    Command acceleration/deceleration and smoothing. mode is legacy or nav2; feedback is OPEN\_LOOP or CLOSED\_LOOP.

    | Field | Type | Generic default |
    | - | - | - |
    | `enabled` | `boolean` | `false` |
    | `mode` | `string` | `"legacy"` |
    | `max_dv_accel` | `number` | `1.0` |
    | `max_dv_decel` | `number` | `2.0` |
    | `max_dw` | `number` | `3.0` |
    | `max_dvy` | `number` | `0.0` |
    | `smoothing_frequency` | `number` | `0.0` |
    | `scale_velocities` | `boolean` | `false` |
    | `feedback` | `string` | `"OPEN_LOOP"` |
    | `max_velocity` | `array[number]` | `factory / see resolved YAML` |
    | `min_velocity` | `array[number]` | `factory / see resolved YAML` |
    | `deadband_velocity` | `array[number]` | `factory / see resolved YAML` |
    | `velocity_timeout` | `number` | `1.0` |
    | `max_accel` | `array[number]` | `factory / see resolved YAML` |
    | `max_decel` | `array[number]` | `factory / see resolved YAML` |
  </Accordion>

  <Accordion title="dwa_pipeline">
    DWA costmap and pipeline settings.

    | Field | Type | Generic default |
    | - | - | - |
    | `rotation_shim_enabled` | `boolean` | `false` |
    | `rotation_shim_enter_rad` | `number` | `0.75` |
    | `rotation_shim_exit_rad` | `number` | `0.45` |
    | `rotation_shim_lookahead_m` | `number` | `0.5` |
    | `rotation_shim_angular_gain` | `number` | `1.2` |
    | `rotation_shim_min_w` | `number` | `0.12` |
    | `path_handler_max_search_dist_m` | `number` | `3.0` |
    | `path_handler_prune_distance_m` | `number` | `2.0` |
    | `progress_checker_enabled` | `boolean` | `true` |
    | `progress_checker_required_movement_radius` | `number` | `0.5` |
    | `progress_checker_movement_time_allowance` | `number` | `10.0` |
    | `progress_checker_required_movement_angle` | `number` | `0.5` |
    | `progress_checker_check_angle` | `boolean` | `false` |
    | `progress_checker_min_displacement_m` | `number` | `0.5` |
    | `progress_checker_window_ticks` | `integer` | `40` |
    | `stall_detector_enabled` | `boolean` | `true` |
    | `stall_goal_blocked_threshold_ticks` | `integer` | `12` |
    | `stall_patience_seconds` | `number` | `4.0` |
    | `stall_progress_epsilon_m` | `number` | `0.15` |
    | `lidar_ring_n_bins` | `integer` | `360` |
    | `lidar_ring_min_range_m` | `number` | `0.4` |
  </Accordion>

  <Accordion title="mppi_pipeline">
    MPPI prediction, sampling, costmap, critics, and trajectory validation. motion\_model is diff\_drive or omni. Footprint-aware cost/validation requires robot\_geometry.footprint\_polygon.

    | Field | Type | Generic default |
    | - | - | - |
    | `vx_min` | `number` | `-0.35` |
    | `command_decimation` | `integer` | `1` |
    | `controller_frequency_hz` | `number` | `0.0` |
    | `prediction_horizon_s` | `number` | `0.0` |
    | `model_delay_vx` | `number` | `0.0` |
    | `model_delay_vy` | `number` | `0.0` |
    | `model_delay_wz` | `number` | `0.0` |
    | `clamp_raw_controls` | `boolean` | `false` |
    | `time_steps` | `integer` | `56` |
    | `batch_size` | `integer` | `0` |
    | `iteration_count` | `integer` | `1` |
    | `temperature` | `number` | `0.3` |
    | `gamma` | `number` | `0.015` |
    | `motion_model` | `string` | `"diff_drive"` |
    | `vx_std` | `number` | `0.2` |
    | `vy_std` | `number` | `0.2` |
    | `wz_std` | `number` | `0.4` |
    | `vy_max` | `number` | `0.5` |
    | `wz_max` | `number` | `0.0` |
    | `goal_threshold` | `number or null` | `null` |
    | `legacy_g1_env_overrides` | `boolean` | `false` |
    | `path_follow_offset_from_furthest` | `integer` | `5` |
    | `path_angle_offset_from_furthest` | `integer` | `4` |
    | `blocked_guidance_enabled` | `boolean` | `false` |
    | `blocked_guidance_lookahead_m` | `number` | `2.0` |
    | `blocked_guidance_side_search_max_m` | `number` | `1.5` |
    | `blocked_guidance_minimum_side_offset_m` | `number` | `0.0` |
    | `blocked_guidance_side_margin_m` | `number` | `0.1` |
    | `blocked_guidance_entry_lead_m` | `number` | `0.75` |
    | `blocked_guidance_treat_unknown_as_invalid` | `boolean` | `true` |
    | `blocked_guidance_invalid_ticks_before_reselect` | `integer` | `1` |
    | `blocked_guidance_target_smoothing_alpha` | `number` | `1.0` |
    | `cost_weight` | `number` | `3.81` |
    | `cost_consider_footprint` | `boolean` | `false` |
    | `path_align_weight` | `number` | `2.0` |
    | `path_align_offset_from_furthest` | `integer` | `20` |
    | `path_follow_weight` | `number` | `7.0` |
    | `prefer_forward_weight` | `number` | `1.0` |
    | `path_angle_weight` | `number` | `2.0` |
    | `path_angle_threshold_to_consider` | `number` | `0.5` |
    | `path_angle_max_angle_to_furthest` | `number` | `1.0` |
    | `goal_angle_weight` | `number` | `3.0` |
    | `goal_angle_threshold_to_consider` | `number` | `0.5` |
    | `use_goal_yaw` | `boolean` | `false` |
    | `deadband_critic_enabled` | `boolean` | `false` |
    | `velocity_deadband_weight` | `number` | `35.0` |
    | `validator_collision_lookahead_time` | `number` | `2.0` |
    | `validator_consider_footprint` | `boolean` | `false` |
    | `costmap_size_m` | `number` | `20.0` |
    | `costmap_resolution` | `number` | `0.1` |
    | `inflation_radius_m` | `number` | `0.55` |
    | `inflation_cost_scaling_factor` | `number` | `10.0` |
    | `footprint_radius_padding_m` | `number or null` | `null` |
    | `progress_checker_enabled` | `boolean` | `true` |
    | `progress_checker_required_movement_radius` | `number` | `0.5` |
    | `progress_checker_movement_time_allowance` | `number` | `10.0` |
    | `progress_checker_required_movement_angle` | `number` | `0.5` |
    | `progress_checker_check_angle` | `boolean` | `false` |
    | `costmap_lidar_window_ticks` | `integer` | `30` |
    | `costmap_default_unknown` | `boolean` | `false` |
    | `consider_unknown_as_lethal` | `boolean` | `false` |
    | `costmap_origin_hysteresis_m` | `number` | `0.0` |
    | `costmap_lidar_max_points` | `integer` | `0` |
    | `footprint_clearing_enabled` | `boolean` | `true` |
    | `footprint_clearing_margin_m` | `number` | `0.03` |
    | `footprint_clearing_z_max_m` | `number` | `0.62` |
    | `stall_detector_enabled` | `boolean` | `true` |
    | `stall_goal_blocked_threshold_ticks` | `integer` | `12` |
    | `stall_patience_seconds` | `number` | `4.0` |
    | `stall_progress_epsilon_m` | `number` | `0.15` |
    | `stall_progress_epsilon_rad` | `number` | `0.0` |
    | `rotation_shim_enabled` | `boolean` | `false` |
    | `rotation_shim_enter_rad` | `number` | `0.75` |
    | `rotation_shim_exit_rad` | `number` | `0.45` |
    | `rotation_shim_lookahead_m` | `number` | `2.0` |
    | `rotation_shim_angular_gain` | `number` | `1.2` |
    | `rotation_shim_min_w` | `number` | `0.12` |
    | `shim_stall_yield_ticks` | `integer` | `4` |
    | `shim_reengage_clear_s` | `number` | `1.0` |
  </Accordion>

  <Accordion title="escape_fallback">
    Optional fallback for extracting the robot from a safety standoff. Disabled unless explicitly configured.

    | Field | Type | Generic default |
    | - | - | - |
    | `enabled` | `boolean` | `false` |
    | `mode` | `string` | `"shadow"` |
    | `entry_failures` | `integer` | `3` |
    | `entry_min_s` | `number` | `0.15` |
    | `standoff_ticks` | `integer` | `4` |
    | `standoff_seconds` | `number` | `0.5` |
    | `exit_successes` | `integer` | `3` |
    | `handback_clear_s` | `number` | `0.5` |
    | `min_dwell_s` | `number` | `1.0` |
    | `translation_cap_mps` | `number` | `0.25` |
    | `angular_cap_radps` | `number` | `0.3` |
    | `escape_margin_m` | `number` | `0.04` |
    | `world_speed_bound_mps` | `number` | `1.5` |
    | `self_speed_bound_mps` | `number` | `0.3` |
    | `hard_age_ceiling_s` | `number` | `1.5` |
    | `corridor_fast_path_enabled` | `boolean` | `true` |
    | `overlap_band_m` | `number` | `0.03` |
    | `initial_overlap_epsilon_m` | `number` | `0.005` |
    | `wheel_top_m` | `number` | `0.28` |
    | `deck_top_m` | `number` | `0.35` |
    | `upper_z_min_m` | `number` | `0.62` |
    | `episode_timeout_s` | `number` | `12.0` |
    | `episode_distance_m` | `number` | `1.25` |
    | `leg_distance_m` | `number` | `0.25` |
    | `max_legs` | `integer` | `4` |
    | `max_episodes_per_waypoint` | `integer` | `2` |
    | `sector_bins` | `integer` | `36` |
    | `no_candidate_ticks` | `integer` | `3` |
    | `no_candidate_seconds` | `number` | `0.5` |
    | `sweep_deadline_ms` | `number` | `50.0` |
    | `static_taper_rectangle_m` | `array[any]` | `[-0.36,0.22,-0.32,0.32]` |
    | `static_mid_rectangle_m` | `array[any]` | `[-0.26,0.1,-0.19,0.19]` |
    | `static_upper_rectangle_m` | `array[any]` | `[-0.25,0.15,-0.22,0.22]` |
    | `static_band_use_base_footprint` | `boolean` | `false` |
    | `fk_band_exclude_link_prefixes` | `array[string]` | `factory / see resolved YAML` |
  </Accordion>

  <Accordion title="robot_geometry">
    Footprint, dimensions, inflation, and optional articulated projection. Geometry propagation derives related planner/safety values; edit geometry rather than assuming a derived field stays independent.

    | Field | Type | Generic default |
    | - | - | - |
    | `inscribed_radius_m` | `number` | `0.285` |
    | `footprint_padding_m` | `number` | `0.05` |
    | `circumscribed_radius_m` | `number` | `0.335` |
    | `self_hit_min_range_m` | `number` | `0.4` |
    | `front_bumper_offset_m` | `number` | `0.1` |
    | `rear_bumper_offset_m` | `number` | `0.1` |
    | `footprint_polygon` | `any` | `null` |
    | `footprint_turn_dilation_m_per_radps` | `number` | `0.0` |
    | `inflation_radius_m` | `number` | `-1.0` |
    | `gait_deadband_mps` | `number` | `0.0` |
    | `self_mask_model_path` | `string` | `""` |
    | `articulated_projection_model_path` | `string` | `""` |
    | `articulated_planner_clearance_m` | `number` | `0.15` |
    | `articulated_joint_motion_horizon_s` | `number` | `0.75` |
    | `articulated_maximum_joint_motion_inflation_m` | `number` | `0.15` |
    | `articulated_stationary_joint_speed_tolerance` | `number` | `0.001` |
    | `articulated_predictive_envelope_enabled` | `boolean` | `false` |
    | `articulated_predictive_history_s` | `number` | `2.0` |
    | `articulated_predictive_start_step` | `integer` | `0` |
    | `articulated_joint_position_overrides` | `any` | `null` |
  </Accordion>

  <Accordion title="robot_adaptation">
    Robot-specific command and feedback adaptations. Preserve the matching profile; defaults disable these adaptations.

    | Field | Type | Generic default |
    | - | - | - |
    | `velocity_source` | `string or null` | `null` |
    | `creep_floor_mps` | `number or null` | `null` |
    | `planar_gate_threshold_mps` | `number or null` | `null` |
    | `yaw_gate_threshold_radps` | `number or null` | `null` |
    | `reverse_scale` | `number or null` | `null` |
    | `pivot_arc_speed_mps` | `number or null` | `null` |
    | `pivot_angular_threshold_radps` | `number or null` | `null` |
    | `band_overrides` | `object or null` | `null` |
  </Accordion>

  <Accordion title="runtime">
    Controller selection, recording, replanning, and GRX streaming defaults. See the configuration guide for supported values and per-run overrides.

    | Field | Type | Generic default |
    | - | - | - |
    | `backend` | `"dwa" / "mppi"` | `"mppi"` |
    | `run_name` | `string` | `"nav"` |
    | `record` | `string` | `"default"` |
    | `enable_cloud_replan` | `boolean` | `false` |
    | `cloud_replan_cooldown_s` | `number` | `1.0` |
    | `cloud_replan_timeout_s` | `number` | `1.0` |
    | `stream_viz_grx` | `boolean` | `false` |
    | `stream_viz_port` | `integer or null` | `null` |
  </Accordion>

  <Accordion title="robot">
    Robot identity, camera calibration, image dimensions, rigid transforms, and sensor-frame flags. Preserve the calibration for the physical robot.

    | Field | Type | Generic default |
    | - | - | - |
    | `robot_type` | `string` | `"vision60"` |
    | `camera_name` | `string` | `"front_left"` |
    | `query_intrinsics` | `array[any]` | `factory / see resolved YAML` |
    | `query_image_size` | `array[any]` | `factory / see resolved YAML` |
    | `query_resolution` | `array[any]` | `factory / see resolved YAML` |
    | `wide_camera_calibration_path` | `string` | `""` |
    | `undistort_query` | `boolean` | `false` |
    | `query_distortion_model` | `string` | `"rational_polynomial"` |
    | `query_distortion` | `array[any]` | `factory / see resolved YAML` |
    | `T_body_camera` | `array[any]` | `factory / see resolved YAML` |
    | `T_body_lidar` | `array[any]` | `factory / see resolved YAML` |
    | `lidar_points_in_base_link` | `boolean` | `false` |
    | `transform_lidar_to_body` | `boolean` | `false` |
    | `enable_walking` | `boolean` | `false` |
    | `odom_has_velocity` | `boolean` | `true` |
  </Accordion>

  <Accordion title="localization">
    Cloud localization timeouts and quality gates, pose fusion, and optional LiDAR refinement. lidar\_refine selects off, shadow (diagnostics only), refine, or gate. Frequency hloc\_hz is a root field.

    | Field | Type | Generic default |
    | - | - | - |
    | `hloc_query_timeout_s` | `number` | `10.0` |
    | `connect_attempts` | `integer` | `2` |
    | `connect_timeout_s` | `number` | `20.0` |
    | `connect_backoff_s` | `number` | `1.0` |
    | `bootstrap_timeout_s` | `number` | `0.0` |
    | `ekf_backend` | `string` | `"auto"` |
    | `min_quality` | `number` | `0.1` |
    | `min_inliers` | `integer` | `50` |
    | `inliers_ref` | `integer` | `350` |
    | `q_trans_std` | `number` | `0.047` |
    | `q_yaw_std_deg` | `number` | `1.6` |
    | `r_pos_std_min` | `number` | `0.4` |
    | `r_pos_std_max` | `number` | `1.0` |
    | `r_yaw_std_min_deg` | `number` | `4.0` |
    | `r_yaw_std_max_deg` | `number` | `35.0` |
    | `init_yaw_std_deg` | `number` | `20.0` |
    | `gate_maha` | `number` | `5.99` |
    | `max_consecutive_rejects` | `integer` | `8` |
    | `reset_on_reject_streak` | `boolean` | `false` |
    | `pos_only` | `boolean` | `true` |
    | `relocalize_confirm_count` | `integer` | `2` |
    | `correction_confirm_count` | `integer` | `3` |
    | `relocalize_radius_m` | `number` | `0.7` |
    | `odom_rot180_threshold_deg` | `number` | `150.0` |
    | `odom_rot180_accept_deg` | `number` | `120.0` |
    | `lidar_refine` | `string` | `"off"` |
    | `lidar_map_weight` | `integer` | `10` |
    | `lidar_cache_dir` | `string` | `"`/.cache/grid\_graf"\` |
    | `lidar_voxel` | `number` | `0.1` |
    | `lidar_map_voxel` | `number` | `0.2` |
    | `lidar_max_range_m` | `number` | `18.0` |
    | `lidar_min_points` | `integer` | `200` |
    | `lidar_min_inlier` | `number` | `0.35` |
    | `lidar_min_tight` | `number` | `0.0` |
    | `lidar_max_corr_trans_m` | `number` | `1.0` |
    | `lidar_max_corr_yaw_deg` | `number` | `20.0` |
    | `lidar_icp_iters` | `integer` | `30` |
    | `lidar_icp_threads` | `integer` | `4` |
    | `lidar_icp_hz` | `number` | `3.0` |
    | `lidar_icp_max_source_points` | `integer` | `5000` |
    | `lidar_icp_r_pos_std` | `number` | `0.1` |
    | `lidar_icp_r_yaw_std_deg` | `number` | `4.0` |
    | `lidar_icp_max_result_age_s` | `number` | `1.0` |
    | `lidar_icp_apply_step_trans_m` | `number` | `0.05` |
    | `lidar_icp_apply_step_yaw_deg` | `number` | `2.0` |
    | `lidar_gate_on_low_overlap` | `boolean` | `false` |
  </Accordion>

  <Accordion title="self_mask">
    Exclusion of robot-body returns from LiDAR, including optional forward-kinematic masking and model assets.

    | Field | Type | Generic default |
    | - | - | - |
    | `mode` | `string` | `"radial"` |
    | `model_path` | `string` | `""` |
    | `margin_m` | `number` | `0.02` |
    | `velocity_margin_s` | `number` | `0.05` |
    | `graft_band_m` | `number` | `0.0` |
    | `graft_max_cluster` | `integer` | `25` |
    | `graft_band_gripper_m` | `number` | `0.0` |
    | `joint_indices` | `array[any]` | `factory / see resolved YAML` |
    | `joint_groups` | `array[any]` | `factory / see resolved YAML` |
    | `joint_group_slots` | `object` | `factory / see resolved YAML` |
  </Accordion>

  <Accordion title="benchmark">
    Simulation benchmark parameters present in the config schema. These do not expose a simulation or benchmark service through Nexus.

    | Field | Type | Generic default |
    | - | - | - |
    | `self_mask_mode` | `string` | `"radial"` |
    | `dyn_obs_amplitude_m` | `number` | `0.5` |
    | `dyn_obs_frequency_hz` | `number` | `0.25` |
    | `articulated_fixed_joint_positions` | `object` | `factory / see resolved YAML` |
  </Accordion>
</AccordionGroup>

## Nested policy objects

These types are referenced by the section tables. Arrays of these objects
must be replaced as a whole when using dotted overrides.

<AccordionGroup>
  <Accordion title="Nav2CollisionMonitorConfig">
    | Field | Type | Generic default |
    | - | - | - |
    | `polygons` | `array[Nav2CollisionPolygonConfig]` | `factory / see resolved YAML` |
    | `processing_frequency_hz` | `number` | `20.0` |
    | `source_timeout` | `number` | `2.0` |
    | `base_shift_correction` | `boolean` | `true` |
    | `cmd_vel_timeout` | `number` | `0.5` |
    | `stop_pub_timeout` | `number` | `1.0` |
    | `use_realtime_priority` | `boolean` | `false` |
  </Accordion>

  <Accordion title="Nav2CollisionPolygonConfig">
    | Field | Type | Generic default |
    | - | - | - |
    | `name` | `string` | `""` |
    | `enabled` | `boolean` | `true` |
    | `type` | `string` | `"polygon"` |
    | `points` | `any` | `null` |
    | `radius` | `number` | `0.0` |
    | `action_type` | `string` | `"none"` |
    | `min_points` | `integer` | `4` |
    | `slowdown_ratio` | `number` | `0.5` |
    | `linear_limit` | `number` | `0.5` |
    | `angular_limit` | `number` | `0.5` |
    | `time_before_collision` | `number` | `2.0` |
    | `simulation_time_step` | `number` | `0.1` |
    | `holonomic` | `boolean` | `false` |
    | `trigger_consecutive_points` | `integer` | `1` |
    | `release_consecutive_points` | `integer` | `1` |
    | `use_robot_footprint` | `boolean` | `false` |
    | `velocity_polygons` | `array[Nav2VelocitySubPolygonConfig]` | `factory / see resolved YAML` |
  </Accordion>

  <Accordion title="Nav2VelocitySubPolygonConfig">
    | Field | Type | Generic default |
    | - | - | - |
    | `name` | `string` | `""` |
    | `points` | `any` | `null` |
    | `linear_min` | `number` | `0.0` |
    | `linear_max` | `number` | `0.0` |
    | `theta_min` | `number` | `0.0` |
    | `theta_max` | `number` | `0.0` |
    | `direction_start_angle` | `number` | `-3.141592653589793` |
    | `direction_end_angle` | `number` | `3.141592653589793` |
  </Accordion>

  <Accordion title="RecoveryProfileConfig">
    | Field | Type | Generic default |
    | - | - | - |
    | `enabled` | `boolean` | `true` |
    | `backup_speed_mps` | `number` | `0.15` |
    | `backup_distance_scale` | `number` | `1.0` |
    | `max_backup_m` | `number` | `0.6` |
    | `first_backup_distance_m` | `number or null` | `null` |
    | `allow_reverse_arc` | `boolean` | `true` |
    | `allow_spin` | `boolean` | `true` |
    | `spin_target_rad` | `number` | `1.5708` |
    | `wait_duration_s` | `number` | `5.0` |
    | `alternate_side_bias` | `number` | `0.1` |
    | `backup_before_spin` | `boolean` | `false` |
    | `straight_first_backup` | `boolean` | `false` |
    | `opposite_spin_after_blocked_backup` | `boolean` | `true` |
    | `spin_direction_from_context` | `boolean` | `false` |
    | `reset_controller_between_actions` | `boolean` | `false` |
    | `reset_rearm_success_ticks` | `integer` | `1` |
    | `adaptive_goals` | `boolean` | `false` |
    | `adaptive_backup_min_m` | `number` | `0.15` |
    | `adaptive_costmap_stale_s` | `number` | `0.5` |
    | `adaptive_spin_clearance_m` | `number` | `1.0` |
    | `adaptive_spin_samples` | `integer` | `25` |
    | `breakthrough_valid_fraction` | `number` | `0.15` |
    | `separating_enabled` | `boolean` | `false` |
    | `separating_holonomic` | `boolean` | `false` |
    | `separating_distance_m` | `number` | `0.25` |
    | `separating_speed_mps` | `number` | `0.2` |
    | `separating_angular_speed_radps` | `number` | `0.3` |
    | `separating_candidate_checks` | `integer` | `12` |
    | `separating_time_allowance_s` | `number` | `4.0` |
  </Accordion>

  <Accordion title="SeparatingAllowanceConfig">
    | Field | Type | Generic default |
    | - | - | - |
    | `enabled` | `boolean` | `false` |
    | `mode` | `string` | `"shadow"` |
  </Accordion>
</AccordionGroup>

## Runtime versus mission policy

`constraints` is a per-mission argument, not a NavigationConfig field.
See [polygon constraints](/navigation/configuration#polygon-constraints) for
its separate versioned contract. The editor's map height slice, route
optimization, and obstacle clearance are also outside this config.

## Present but ineffective settings

The schema still accepts the following fields, but the configuration audit
found no effective runtime consumer. Their presence is not a supported
capability; use the active settings below where available.

| Fields | Effective setting or limitation |
| - | - |
| `benchmark` section | Does not control production navigation behavior. |
| `stuck.osc_window_steps`, `osc_dist_progress_cap_m`, `front_constraint_progress_cap_m` | Use the controller progress/stall settings under `dwa_pipeline` or `mppi_pipeline`. |
| `dwa_pipeline.progress_checker_min_displacement_m`, `progress_checker_window_ticks` | Use `progress_checker_required_movement_radius` and `progress_checker_movement_time_allowance` (seconds). |
| `robot_geometry.self_mask_model_path` | Use `self_mask.model_path`. |
| `robot_geometry.articulated_planner_clearance_m`, `articulated_joint_motion_horizon_s`, `articulated_maximum_joint_motion_inflation_m` | These declared features are not connected to runtime behavior. Implemented live projection settings remain available. |
| `robot_geometry.self_hit_min_range_m`, `front_bumper_offset_m`, `rear_bumper_offset_m` | The active gate settings are under `safety`; DWA's ring range is `dwa_pipeline.lidar_ring_min_range_m`. |
| `robot_adaptation.velocity_source`, `band_overrides` | Use `dwa.velocity_source` for DWA and supported typed dotted overrides for other settings. |

See the configuration guide for current limitations in geometry propagation,
safety-mode environment precedence, polygon validation, and MPPI timing.
Do not assume audit fixes or proposed APIs are present in an installed runtime.


## Related topics

- [Configure navigation](/navigation/configuration.md)
- [Session Configuration](/simulation/airgen/session_configuration.md)
- [Sensors](/simulation/isaac/sensors.md)
- [Navigation data schemas](/navigation/data-types.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.