Navigation service API

The navigation service API allows you to define waypoints and move your machine along those waypoints while avoiding obstacles.

The navigation service supports the following methods:

Method NameDescription
GetModeGet the Mode the service is operating in.
SetModeSet the Mode the service is operating in.
GetLocationGet the current location of the robot in the navigation service.
GetWaypointsGet an array of waypoints currently in the service’s data storage.
AddWaypointAdd a waypoint to the service’s data storage.
RemoveWaypointRemove a waypoint from the service’s data storage.
GetObstaclesGet an array or list of the obstacles currently in the service’s data storage.
GetPathsGet each path, the series of geo points the robot plans to travel through to get to a destination waypoint, in the machine’s motion planning.
GetPropertiesGet information about the navigation service.
ReconfigureReconfigure this resource.
DoCommandExecute model-specific commands that are not otherwise defined by the service API.
GetResourceNameGet the ResourceName for this instance of the navigation service with the given name.
CloseSafely shut down the resource and prevent further use.

Establish a connection

To get started using Viam’s SDKs to connect to and control your machine, go to your machine’s page on the Viam app, navigate to the CONNECT tab’s Code sample page, select your preferred programming language, and copy the sample code.

When executed, this sample code creates a connection to your machine as a client.

The following code examples assume that you have a machine configured with a Navigation service.

from viam.services.navigation import NavigationClient
import (
  "go.viam.com/rdk/services/navigation"
)

API

GetMode

Get the Mode the service is operating in.

There are two options for modes: MODE_MANUAL or MODE_WAYPOINT.

  • MODE_WAYPOINT: Start to look for added waypoints and begin autonomous navigation.
  • MODE_MANUAL: Stop autonomous navigation between waypoints and allow the base to be controlled manually.

Parameters:

  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (viam.services.navigation.Mode.ValueType): The Mode the service is operating in.

Example:

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get the Mode the service is operating in
await my_nav.get_mode()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • (Mode): The Mode the service is operating in.
  • (error): An error, if one occurred.

Example:

// Get the Mode the service is operating in.
mode, err := myNav.Mode(context.Background(), nil)

For more information, see the Go SDK Docs.

SetMode

Set the Mode the service is operating in.

There are two options for modes: MODE_MANUAL or MODE_WAYPOINT.

  • MODE_WAYPOINT: Start to look for added waypoints and begin autonomous navigation.
  • MODE_MANUAL: Stop autonomous navigation between waypoints and allow the base to be controlled manually.

Parameters:

  • mode (viam.services.navigation.Mode.ValueType) (required): The Mode for the service to operate in.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • None.

Example:

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Set the Mode the service is operating in to MODE_WAYPOINT and begin navigation
await my_nav.set_mode(Mode.ValueType.MODE_WAYPOINT)

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • mode (Mode): The Mode for the service to operate in.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • (error): An error, if one occurred.

Example:

// Set the Mode the service is operating in to ModeWaypoint and begin navigation.
err := myNav.SetMode(context.Background(), navigation.ModeWaypoint, nil)

For more information, see the Go SDK Docs.

GetLocation

Get the current location of the robot in the navigation service.

Parameters:

  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

Example:

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get the current location of the robot in the navigation service
location = await my_nav.get_location()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • (*spatialmath.GeoPose): The current location of the robot in the navigation service, represented in a Point with latitude and longitude values.
  • (error): An error, if one occurred.

Example:

// Get the current location of the robot in the navigation service.
location, err := myNav.Location(context.Background(), nil)

For more information, see the Go SDK Docs.

GetWaypoints

Get an array of waypoints currently in the service’s data storage. These are locations designated within a path for the robot to navigate to.

Parameters:

  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

Example:

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get a list containing each waypoint stored by the navigation service
waypoints = await my_nav.get_waypoints()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • ([]Waypoint): An array comprised of each Waypoint in the service’s data storage. These are locations designated within a path for the robot to navigate to.
  • (error): An error, if one occurred.

Example:

waypoints, err := myNav.Waypoints(context.Background(), nil)

For more information, see the Go SDK Docs.

AddWaypoint

Add a waypoint to the service’s data storage.

Parameters:

  • point (viam.services.navigation.GeoPoint) (required): The current location of the robot in the navigation service, represented in a GeoPoint with latitude and longitude values.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • None.

Example:

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

 # Create a new waypoint with latitude and longitude values of 0 degrees
 location = GeoPoint(latitude=0, longitude=0)


 # Add your waypoint to the service's data storage
 await my_nav.add_waypoint(point=location)

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • point (*geo.Point): The current location of the robot in the navigation service, represented in a Point with latitude (lat) and longitude (lng) values.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • (error): An error, if one occurred.

Example:

// Create a new waypoint with latitude and longitude values of 0 degrees.
// Assumes you have imported "github.com/kellydunn/golang-geo" as `geo`.
location := geo.NewPoint(0, 0)

// Add your waypoint to the service's data storage.
err := myNav.AddWaypoint(context.Background(), location, nil)

For more information, see the Go SDK Docs.

RemoveWaypoint

Remove a waypoint from the service’s data storage. If the robot is currently navigating to this waypoint, the motion will be canceled, and the robot will proceed to the next waypoint.

Parameters:

  • id (str) (required): The MongoDB ObjectID of the Waypoint to remove from the service’s data storage.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • None.

Example:

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Remove the waypoint matching that ObjectID from the service's data storage
await my_nav.remove_waypoint(waypoint_id)

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • id (primitive.ObjectID): The MongoDB ObjectID of the Waypoint to remove from the service’s data storage.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • (error): An error, if one occurred.

Example:

// Assumes you have already called AddWaypoint once and the waypoint has not yet been reached.
waypoints, err := myNav.Waypoints(context.Background(), nil)
if (err != nil || len(waypoints) == 0) {
    return
}

// Remove the first waypoint from the service's data storage.
err = myNav.RemoveWaypoint(context.Background(), waypoints[0].ID, nil)

For more information, see the Go SDK Docs.

GetObstacles

Get an array or list of the obstacles currently in the service’s data storage. These are objects designated for the robot to avoid when navigating. These include all transient obstacles which are discovered by the vision services configured for the navigation service, in addition to the obstacles that are configured as a part of the service. See the motion service for more information.

Parameters:

  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

Example:

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get a list containing each obstacle stored by the navigation service
obstacles = await my_nav.get_obstacles()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • ([]*spatialmath.GeoGeometry): An array comprised of each GeoObstacle in the service’s data storage. These are objects designated for the robot to avoid when navigating.
  • (error): An error, if one occurred.

Example:

// Get an array containing each obstacle stored by the navigation service.
obstacles, err := myNav.Obstacles(context.Background(), nil)

For more information, see the Go SDK Docs.

GetPaths

Get each path, the series of geo points the robot plans to travel through to get to a destination waypoint, in the machine’s motion planning.

Parameters:

  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (List[viam.proto.service.navigation.Path]): An array comprised of Paths, where each path is either a user-provided destination or a Waypoint, along with the corresponding set of geopoints. This outlines the route the machine is expected to take to reach the specified destination or Waypoint.

Example:

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get a list containing each path stored by the navigation service
paths = await my_nav.get_paths()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • ([]*Path): An array of paths, each path being a user-provided destination, or Waypoint, and the set of geo Points the robot plans to travel through to get there.
  • (error): An error, if one occurred.

Example:

// Get an array containing each path stored by the navigation service.
paths, err := myNav.Paths(context.Background(), nil)

For more information, see the Go SDK Docs.

GetProperties

Get information about the navigation service.

Parameters:

  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (viam.services.navigation.MapType.ValueType): Information about the type of map the service is using.

Example:

my_nav = NavigationClient.from_robot(robot=robot, name="my_nav_service")

# Get the properties of the current navigation service.
nav_properties = await my_nav.get_properties()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

  • (Properties): Information about the type of map the service is using.
  • (error): An error, if one occurred.

Example:

// Get the properties of the current navigation service.
navProperties, err := myNav.Properties(context.Background())

For more information, see the Go SDK Docs.

Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • deps (Dependencies): The resource dependencies.
  • conf (Config): The resource configuration.

Returns:

  • (error): An error, if one occurred.

For more information, see the Go SDK Docs.

DoCommand

Execute model-specific commands that are not otherwise defined by the service API. For built-in service models, any model-specific commands available are covered with each model’s documentation. If you are implementing your own navigation service and add features that have no built-in API method, you can access them with DoCommand.

Parameters:

  • command (Mapping[str, ValueTypes]) (required): The command to execute.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (Mapping[str, viam.utils.ValueTypes]): Result of the executed command.

Example:

service = NavigationClient.from_robot(robot, "my_navigation_svc")

my_command = {
  "cmnd": "dosomething",
  "someparameter": 52
}

# Can be used with any resource, using the motion service as an example
await service.do_command(command=my_command)

For more information, see the Python SDK Docs.

Parameters:

Returns:

Example:

myNavigation, err := navigation.FromRobot(machine, "my_navigation")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myNavigation.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

GetResourceName

Get the ResourceName for this instance of the navigation service with the given name.

Parameters:

  • name (str) (required): The name of the Resource.

Returns:

Example:

my_navigation_svc_name = NavigationClient.get_resource_name("my_navigation_svc")

For more information, see the Python SDK Docs.

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None.

Returns:

  • None.

Example:

await my_navigation_svc.close()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

  • (error): An error, if one occurred.

Example:

my_nav, err := navigation.FromRobot(machine, "my_nav_svc")

err := my_nav.Close(context.Background())

For more information, see the Go SDK Docs.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.