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.

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}")

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

DoCommand

Send an arbitrary command to the navigation service. This is model-specific and depends on the implementation.

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

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