Navigation service API

The navigation service API provides methods for controlling autonomous GPS-based navigation. Use these methods to set the navigation mode, manage waypoints, monitor the robot’s location, and query obstacles and paths.

GetMode

Get the current navigation mode.

Returns: Mode (MANUAL, WAYPOINT, or EXPLORE)

mode = await nav.get_mode()
print(f"Current mode: {mode}")

mode, err := nav.Mode(ctx, nil)

SetMode

Set the navigation mode.

In Manual mode, the navigation service is passive. You control the base directly. In Waypoint mode, the service takes control of the base and navigates to unvisited waypoints.

Switching from Waypoint to Manual stops the current motion plan but preserves all waypoints. Switching back to Waypoint resumes from the next unvisited waypoint.

Explore mode is accepted by SetMode and returned by GetMode but is not currently exposed in the Viam app’s navigation UI mode selector. To use it, call SetMode from an SDK.

from viam.proto.service.navigation import Mode

await nav.set_mode(Mode.MODE_WAYPOINT)

err := nav.SetMode(ctx, navigation.ModeWaypoint, nil)

GetLocation

Get the robot’s current GPS location and compass heading.

Returns: GeoPoint with latitude and longitude, plus compass heading in degrees (0 = north, 90 = east, 180 = south, 270 = west).

location = await nav.get_location()
print(f"Lat: {location.latitude}, Lng: {location.longitude}")

geoPose, err := nav.Location(ctx, nil)
loc := geoPose.Location()
heading := geoPose.Heading()

GetWaypoints

Get all unvisited waypoints. Visited waypoints are not included.

Returns: list of Waypoint objects, each with an id and location (GeoPoint).

waypoints = await nav.get_waypoints()
for wp in waypoints:
    print(f"Waypoint {wp.id}: {wp.location.latitude}, {wp.location.longitude}")

waypoints, err := nav.Waypoints(ctx, nil)
for _, wp := range waypoints {
    pt := wp.ToPoint()
    fmt.Printf("Waypoint %s: %f, %f\n", wp.ID.Hex(), pt.Lat(), pt.Lng())
}

AddWaypoint

Add a GPS waypoint to the navigation queue. Waypoints are visited in the order they are added.

from viam.proto.common import GeoPoint

point = GeoPoint(latitude=40.6640, longitude=-73.9387)
await nav.add_waypoint(point)

point := geo.NewPoint(40.6640, -73.9387)
err := nav.AddWaypoint(ctx, point, nil)

RemoveWaypoint

Remove a waypoint by its ID. Use this to skip a waypoint the robot can’t reach, or to clear the queue.

waypoints = await nav.get_waypoints()
if waypoints:
    await nav.remove_waypoint(waypoints[0].id)

waypoints, _ := nav.Waypoints(ctx, nil)
if len(waypoints) > 0 {
    err := nav.RemoveWaypoint(ctx, waypoints[0].ID, nil)
}

GetObstacles

Get all known obstacles, including both static obstacles from configuration and transient obstacles detected by vision services.

Returns: list of GeoGeometry objects.

obstacles = await nav.get_obstacles()
print(f"Found {len(obstacles)} obstacles")

obstacles, err := nav.Obstacles(ctx, nil)

GetPaths

Get the planned paths to waypoints, if any exist.

Returns: list of Path objects, each with a destination waypoint ID and a list of GeoPoints defining the path.

paths = await nav.get_paths()
for path in paths:
    print(f"Path to {path.destination_waypoint_id}: {len(path.geopoints)} points")

paths, err := nav.Paths(ctx, nil)
for _, p := range paths {
    fmt.Printf("Path to %s: %d points\n",
        p.DestinationWaypointID().Hex(), len(p.GeoPoints()))
}

GetProperties

Get the navigation service’s properties, including the map type.

Returns: MapType (NONE or GPS).

props = await nav.get_properties()
print(f"Map type: {props.map_type}")

props, err := nav.Properties(ctx)
fmt.Printf("Map type: %v\n", props.MapType)

DoCommand

Send a model-specific command to the navigation service. The builtin model does not define any DoCommand keys, so this is useful only with custom navigation modules that document their own command schema.

result = await nav.do_command({"custom_command": "value"})

result, err := nav.DoCommand(ctx, map[string]interface{}{"custom_command": "value"})

GetStatus

Return a generic status map for liveness checks. The content of the map is implementation-defined; treat it as opaque unless a specific model documents its fields.

status = await nav.get_status()
print(status)

status, err := nav.GetStatus(ctx)