Robot Service

Explanation of the robot service, its configuration, and its functionality.

Robot Service constitutes a minimal set of APIs that most robots (Viam Server, Viam Python SDK and various SDKs) should support. Users will likely use the Robot Service as an entrypoint to interact with Viam robots and provide a way to get updates from the robot as a whole.

The below is a current list of interfaces provided by the Robot Service.

OperationDescription
BlockForOperationThe request will only return once the specified operation is complete. Useful if a process needs to work until another is completed. Requires the Operations ID.
CancelOperationCancels a specified operation. Requires the Operations ID.
DiscoverComponentsReturns a best-effort configuration for a resource subtype and model that can be discovered on the robot (e.g., webcam on a pi).
FrameSystemConfigReturns the frame system configuration of the robot.
GetOperationsReturns all running operations initiated over gRPC (Google Remote Procedure Call
GetStatusReturns the status for the resources queried for, all resources if none specified.
ResourceNamesReturns the list of all resources currently available on the robot. This includes remote resources.
ResourceRPCSubtypesReturns all resource subtypes available on the robot (this is more of an advance feature, the RDK uses it for user defined resources)
StopAllCancels all ongoing operations and then attempts to stop all resources that can be stopped.
StreamStatusStreams the status for the resources queried for, all resources if none specified. The interval at which the stream refreshes can also be specified.
TransformPoseTransforms the pose in frame into a frame within the robot’s frame system.

Operation and Operation IDs

Operation IDs are how Viam tracks in-flight operations/robot commands over gRPC (i.e., network requests).

The robot creates a unique Operation ID for every request (operation). This ID expires once the request is completed. Each new gRPC request creates a new Operation ID, even if it was created from a pre-existing operation.

Users can cancel an operation by passing in its Operation ID, and can also block a specific operation, again, by specifying its Operation ID, until that operation is complete.

For example, consider two connected robots. Robot “A,” with an attached base and navigation service and robot “B,” operating remotely with an attached GPS.
A client’s request to the navigation service to move “A” creates a new Operation ID.

The request to the attached base is a local request (i.e., a non-gRPC request) between the navigation service and its base and does not create a new Operation ID. However, the navigation service request to the GPS is via gRPC, which spawns a new operation and thus another Operation ID.

Canceling the initial Operation ID cancels the first operation on the navigation service, but that does not cancel the second operation (obtaining the location from the remote GPS).