Navigation service configuration

The navigation service is configured as a service in your machine’s JSON configuration. You can configure it through the Viam app UI or by editing JSON directly.

Required attributes

AttributeTypeDescription
basestringName of the base component the navigation service drives.
movement_sensorstringName of the movement sensor that provides GPS position and compass heading. Required when map_type is "GPS".

Optional attributes

AttributeTypeDefaultDescription
storeobject{"type": "memory"}Where to store waypoints. See Store configuration. Defaults to the in-memory store if omitted.
map_typestring"GPS""GPS" for GPS-based waypoint navigation, or "None" for manual-only mode (no autonomous navigation). Case-sensitive. Omit or leave empty to use the default.
motion_servicestring"builtin"Name of a motion service implementation that supports MoveOnGlobe and MoveOnMap. See the note below on the built-in motion service.
meters_per_secfloat0.3Linear speed in meters per second. How fast the robot drives in a straight line. Start low and increase after testing. Faster speeds need more stopping distance for obstacle avoidance.
degs_per_secfloat20.0Angular speed in degrees per second. How fast the robot turns. Higher values make sharper turns. Lower values make smoother, wider turns.
plan_deviation_mfloat2.6How far, in meters, the robot can deviate from its planned path before replanning. Set this larger than your GPS error. Standard GPS has about 3 m accuracy, so the default of 2.6 m replans frequently. Use 5 to 10 m for standard GPS, or 1 to 2 m for RTK.
position_polling_frequency_hzfloat1.0How often to check the robot’s GPS position, in Hz. Higher values detect deviation sooner but use more CPU. 1 Hz is sufficient for most outdoor robots.
obstacle_polling_frequency_hzfloat1.0How often to query obstacle detectors, in Hz. Higher values detect obstacles sooner but use more CPU and camera bandwidth.
replan_cost_factorfloat1.0Multiplier on the current plan’s cost when the service decides whether to replan after a deviation. Higher values bias the service toward the current plan; lower values favor replanning. Must be non-negative; omit or set to zero to use the default.
obstacle_detectorsarray[]List of vision service and camera pairs for obstacle detection. See Obstacle detectors.
obstaclesarray[]Static obstacles the robot should avoid, defined as geographic geometries with latitude, longitude, and box, sphere, or capsule dimensions in millimeters. Use these for fixed hazards such as buildings, ponds, or restricted areas. Most users configure obstacles through the visual editor in the Viam app; see Avoid obstacles for the JSON schema.
bounding_regionsarray[]Geographic regions the robot must stay within (geofences). If configured, the robot will not navigate outside these boundaries. Define these as geographic geometries.
log_file_pathstring""Path to a file for debug logging. When set, the navigation service writes detailed logs (mode transitions, waypoint attempts, obstacle detections, frame transformations) to the file instead of the standard log stream, which makes field debugging easier.

Store configuration

The store object configures where waypoints are persisted.

FieldTypeDescription
typestring"memory" (default) or "mongodb".

Memory store keeps waypoints in RAM. Simple, no dependencies, works for development and single-session deployments. Waypoints are lost when viam-server restarts.

MongoDB store persists waypoints to a MongoDB database. Waypoints survive restarts. Requires a MongoDB server accessible from the machine. Add a config object with your MongoDB connection details:

{
  "type": "mongodb",
  "config": {
    "uri": "mongodb://127.0.0.1:27017"
  }
}

Obstacle detectors

Each obstacle detector pairs a vision service with a camera. The vision service analyzes frames from the camera and reports detected obstacles. The navigation service transforms these detections into geographic coordinates and feeds them to the path planner.

You can configure multiple detectors. Each one contributes obstacles independently. For example, use a forward-facing camera for path obstacles and a downward-facing camera for terrain hazards.

{
  "obstacle_detectors": [
    {
      "vision_service": "obstacle-detector",
      "camera": "front-cam"
    },
    {
      "vision_service": "terrain-classifier",
      "camera": "down-cam"
    }
  ]
}

Full example

{
  "name": "my-nav",
  "api": "rdk:service:navigation",
  "model": "builtin",
  "attributes": {
    "base": "my-base",
    "movement_sensor": "my-gps",
    "map_type": "GPS",
    "store": {
      "type": "memory"
    },
    "meters_per_sec": 0.5,
    "degs_per_sec": 30,
    "plan_deviation_m": 5.0,
    "position_polling_frequency_hz": 2,
    "obstacle_polling_frequency_hz": 2,
    "obstacle_detectors": [
      {
        "vision_service": "obstacle-detector",
        "camera": "front-cam"
      }
    ]
  }
}

What’s next