Safely 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.
API key and API key ID
By default, the sample code does not include your machine API key and API key ID.
We strongly recommend that you add your API key and API key ID as an environment variable and import this variable into your development environment as needed.
To show your machine’s API key and API key ID in the sample code, toggle Include API key on the CONNECT tab’s Code sample page.
Caution
Do not share your API key or machine address publicly.
Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.
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.
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)
// Set the Mode the service is operating in to ModeWaypoint and begin navigation.
err := myNav.SetMode(context.Background(), navigation.ModeWaypoint, nil)
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.GeoPoint): The current location of the robot in the navigation service, represented in a GeoPoint with latitude and longitude values.
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()
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.services.navigation.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.
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()
([]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.
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)
// 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)
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.
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)
// 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)
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.
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.services.navigation.GeoGeometry]): A list comprised of each GeoGeometry in the service’s data storage. These are objects designated for the robot to avoid when navigating.
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()
([]*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.
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()
([]*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.
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()
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.
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)