Interact with Resources with Viam's Client SDKs
Every Viam resource exposes an Application Programming Interface (API) described through protocol buffers. You can think of this as a description of how you can interact with that resource. Different models of resources implement the same API, which Viam SDKs expose, allowing you to control different models of resource types with a consistent interface.
The API methods provided by the SDKs for each of these resource APIs wrap gRPC client requests to the machine when you execute your program, providing you a convenient interface for accessing information about and controlling the resources you have configured on your machine.
Robot management APIs
Robot API
All machines support the following methods through the robot API:
Method Name | Description |
---|---|
Options.with_api_key | Create RobotClient connection options with an API key as credentials. |
AtAddress | Create a RobotClient that is connected to the machine at the provided address. |
WithChannel | Create a RobotClient that is connected to a machine over the given channel. |
Refresh | Manually refresh the underlying parts of the machine. |
GetOperations | Get the list of operations currently running on the machine. |
CancelOperation | Cancel the specified operation on the machine. |
BlockForOperation | Blocks on the specified operation on the machine. |
TransformPose | Transform a given source Pose from the original reference frame to a new destination reference frame. |
DiscoverComponents | Get a list of discovered component configurations. |
FrameSystemConfig | Get the configuration of a machine’s frame system. |
Status | Get the status of each of the resources on the machine. |
Close | Close the connections and stop periodic tasks across the machine. |
StopAll | Cancel all operations for the machine and stop its movement. |
ResourceNames | Get a list of all the machine’s resources. |
GetCloudMetadata | Returns app-related information about the robot. |
Fleet management API
The fleet management API supports the following methods:
Method Name | Description |
---|---|
ListOrganizations | List the organizations the user owns. |
GetOrganizationNamespaceAvailability | Check the availability of an organization namespace. |
ListOrganizationMembers | List the members and invites of the current organization. |
UpdateOrganizationInviteAuthorizations | Update the authorizations attached to an organization invite that has already been created. |
CreateLocation | Create and name a location. |
GetLocation | Get a location by its ID. |
UpdateLocation | Change the name of and/or assign a parent location to a location. |
DeleteLocation | Delete a location. |
ListLocations | List locations. |
LocationAuth | Get a location’s authorization (location secrets). |
CreateLocationSecret | Create a new location secret. Deprecated. |
DeleteLocationSecret | Delete a location secret. Deprecated. |
GetRobot | Get a machine by machine ID. |
GetRobotParts | Get a list of all the parts under a specific machine. |
GetRobotPart | Get a machine part. |
GetRobotPartLogs | Get the logs associated with a machine part. |
TailRobotPartLogs | Get an asynchronous iterator that receives live machine part logs. |
GetRobotPartHistory | Get a list containing the history of a machine part. |
UpdateRobotPart | Update the name or configuration of a machine part. |
NewRobotPart | Create a new machine part. |
DeleteRobotPart | Delete a machine part. |
MarkPartAsMain | Mark a part as the main part of a machine. |
MarkPartForRestart | Mark a machine part for restart. |
CreateRobotPartSecret | Create a machine part secret. Deprecated. |
DeleteRobotPartSecret | Delete a machine part secret. Deprecated. |
ListRobots | Get a list of all machines in a location. |
NewRobot | Create a new machine. |
UpdateRobot | Change the name of an existing machine. |
DeleteRobot | Delete a machine. |
ListFragments | Get a list of fragments. |
GetFragment | Get a fragment by its ID. |
CreateFragment | Create a new private fragment. |
UpdateFragment | Update a fragment name, config or visibility. |
DeleteFragment | Delete a fragment. |
AddRole | Add a role (owner or operator). |
RemoveRole | Remove a role (owner or operator). |
ListAuthorizations | List authorizations (owners and operators). |
CreateModule | Create a module. |
UpdateModule | Update module metadata. |
UploadModuleFile | Upload a module file. |
GetModule | Get a module by its ID. |
ListModules | List available modules. |
CreateOrganizationInvite | Create an organization invite and send it by email. |
DeleteOrganizationMember | Remove a member from the organization. |
DeleteOrganizationInvite | Delete a pending organization invite. |
ResendOrganizationInvite | Resend a pending organization invite email. |
GetRoverRentalRobots | Return a list of rover rental robots within an org. |
CheckPermissions | Check if the entity you’re currently authenticated to is permitted to perform some action or set of actions on the resource you pass to the method. |
CreateKey | Create a new API key. |
CreateKeyFromExistingKeyAuthorizations | Create a new API key with an existing key’s authorizations. |
ListKeys | List all keys for an organization. |
Data client API
The data client API supports the following methods to upload and retrieve data like images or sensor readings directly to the Viam app (among others):
Method Name | Description |
---|---|
TabularDataByFilter | Filter and download tabular data. |
BinaryDataByFilter | Filter and download binary data. |
BinaryDataByIDs | Download binary data by IDs. |
DeleteTabularData | Delete tabular data older than a specified number of days. |
DeleteBinaryDataByFilter | Filter and delete binary data. |
DeleteBinaryDataByIds | Filter and delete binary data by ids. |
AddTagsToBinaryDataByIds | Add tags to binary data by ids. |
AddTagsToBinaryDataByFilter | Add tags to binary data by filter. |
RemoveTagsFromBinaryDataByIds | Remove tags from binary data by ids. |
RemoveTagsFromBinaryDataByFilter | Remove tags from binary data by filter. |
TagsByFilter | Get tags from data by filter. |
BoundingBoxLabelsByFilter | Get a list of bounding box labels using a Filter. |
GetDatabaseConnection | Get a connection to access a MongoDB Atlas Data federation instance. |
BinaryDataCaptureUpload | Upload binary data collected on your machine through a specific component and the relevant metadata to the Viam app. |
TabularDataCaptureUpload | Upload tabular data collected on your machine through a specific component and the relevant metadata to the Viam app. |
StreamingDataCaptureUpload | Upload the contents of streaming binary data and the relevant metadata to the Viam app. |
FileUpload | Upload file data stored on your machine and the relevant metadata to the Viam app. |
FileUploadFromPath | Upload file data stored on your machine from the specified filepath and the relevant metadata to the Viam app. |
AddBoundingBoxToImageById | Add a bounding box to an image specified by its BinaryID. |
RemoveBoundingBoxFromImageById | Removes a bounding box from an image specified by its BinaryID. |
CreateDataset | Create a new dataset. |
ListDatasetByIds | Get a list of datasets using their IDs. |
ListDatasetByOrganizationId | Get the datasets in an organization. |
RenameDataset | Rename a dataset specified by the dataset ID. |
DeleteDataset | Delete a dataset. |
AddBinaryDataToDatasetByIds | Add the BinaryData to the provided dataset. This BinaryData will be tagged with the VIAM_DATASET_{id} label. |
RemoveBinaryDataFromDatasetByIds | Remove the BinaryData from the provided dataset. This BinaryData will lose the VIAM_DATASET_{id} tag. |
ML training API
The ML training API allows you to get information about and cancel ML training jobs taking place on the Viam app:
Method Name | Description |
---|---|
GetTrainingJob | Get training job metadata by ID. |
ListTrainingJobs | Get training job metadata for all jobs within an organization. |
CancelTrainingJob | Cancel the specified training job. |
Billing client API
The billing client API supports the following methods to retrieve billing information from the Viam app:
Method Name | Description |
---|---|
GetCurrentMonthUsage | Access data usage information for the current month for a given organization. |
GetInvoicePdf | Access invoice PDF data and optionally save it to a provided file path. |
GetInvoicesSummary | Access total outstanding balance plus invoice summaries for a given org. |
GetOrgBillingInformation | Access billing information (payment method, billing tier, etc.) for a given org. |
Component APIs
These APIs provide interfaces for controlling and getting information from various components of a machine. Built-in API methods are defined for every model of each component type. Documentation on using these methods in your SDK code is found on each component page as follows:
Arm
The arm component supports the following methods:
Method Name | Description |
---|---|
GetEndPosition | Get the current position of the arm as a Pose. |
MoveToPosition | Move the end of the arm to the desired Pose. |
MoveToJointPositions | Move each joint on the arm to the desired position. |
GetJointPositions | Get the current position of each joint on the arm. |
Stop | Stop the arm from moving. |
IsMoving | Get if the arm is currently moving. |
GetKinematics | Get the kinematics information associated with the arm. |
GetGeometries | Get all the geometries associated with the arm in its current configuration, in the frame of the arm. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Base
The base component supports the following methods:
Method Name | Description |
---|---|
MoveStraight | Move the base in a straight line across the given distance at the given velocity. |
Spin | Move the base to the given angle at the given angular velocity. |
SetPower | Set the relative power (out of max power) for linear and angular propulsion of the base. |
SetVelocity | Set the linear velocity and angular velocity of the base. |
IsMoving | Return whether the base is moving or not. |
Stop | Stop the base. |
GetProperties | Get the width and turning radius of the base in meters. |
GetGeometries | Get all the geometries associated with the base in its current configuration, in the frame of the base. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Board
The board component supports the following methods:
Method Name | Description |
---|---|
ReadAnalog | Get an Analog by name . |
GetDigitalInterruptValue | Get a DigitalInterrupt by name . |
GetGPIO | Get a GPIOPin by its pin number. |
SetGPIO | Set a GPIOPin by its pin number. |
AnalogNames | Get the name of every Analog . |
DigitalInterruptNames | Get the name of every DigitalInterrupt . |
Status | Get the current status of this board. |
SetPWM | Set the board to the indicated power mode. |
WriteAnalog | Write an analog value to a pin on the board. |
StreamTicks | Start a stream of DigitalInterrupt ticks. |
GetGeometries | Get all the geometries associated with the board in its current configuration, in the frame of the board. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Camera
The camera component supports the following methods:
Method Name | Description |
---|---|
GetImage | Return an image from the camera. |
GetImages | Return multiple simultaneous images from different imagers, along with associated metadata. |
GetPointCloud | Return a point cloud from the camera. |
GetProperties | Return the camera intrinsic and camera distortion parameters, as well as whether the camera supports returning point clouds. |
GetGeometries | Get all the geometries associated with the camera in its current configuration, in the frame of the camera. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Encoder
The encoder component supports the following methods:
Method Name | Description |
---|---|
GetPosition | Get the current position of the encoder. |
ResetPosition | Reset the position to zero. |
GetProperties | Get the supported properties of this encoder. |
GetGeometries | Get all the geometries associated with the encoder in its current configuration, in the frame of the encoder. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Gantry
The gantry component supports the following methods:
Method Name | Description |
---|---|
GetPosition | Get the current positions of the axes of the gantry in mm. |
MoveToPosition | Move the axes of the gantry to the desired positions. |
GetLengths | Get the lengths of the axes of the gantry in mm. |
Stop | Stop the gantry from moving. |
IsMoving | Get if the gantry is currently moving. |
GetGeometries | Get all the geometries associated with the gantry in its current configuration, in the frame of the gantry. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Generic
The generic component supports the following methods:
Method Name | Description |
---|---|
GetGeometries | Get all the geometries associated with the generic component in its current configuration, in the frame of the generic component. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Gripper
The gripper component supports the following methods:
Method Name | Description |
---|---|
Open | Open the gripper. |
Grab | Close the gripper until it grabs something or closes completely. |
Stop | Stop the gripper’s movement. |
IsMoving | Report whether the gripper is currently moving. |
GetGeometries | Get all the geometries associated with the gripper in its current configuration, in the frame of the gripper. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Input Controller
The input controller component supports the following methods:
Method Name | Description |
---|---|
GetControls | Get a list of input Controls that this Controller provides. |
GetEvents | Get the current state of the Controller as a map of the most recent Event for each Control. |
RegisterControlCallback | Define a callback function to execute whenever one of the EventTypes selected occurs on the given Control. |
GetGeometries | Get all the geometries associated with the input controller in its current configuration, in the frame of the input controller. |
TriggerEvent | Trigger an event on the controller. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Motor
The motor component supports the following methods:
Method Name | Description |
---|---|
SetPower | Set the power to send to the motor as a portion of max power. |
GoFor | Spin the motor the specified number of revolutions at specified RPM. |
GoTo | Send the motor to a specified position (in terms of revolutions from home) at a specified speed. |
ResetZeroPosition | Set the current position to be the new zero (home) position. |
GetPosition | Report the position of the motor based on its encoder. Not supported on all motors. |
GetProperties | Return whether or not the motor supports certain optional features. |
IsPowered | Return whether or not the motor is currently on, and the amount of power to it. |
IsMoving | Return whether the motor is moving or not. |
Stop | Cut power to the motor off immediately, without any gradual step down. |
GetGeometries | Get all the geometries associated with the motor in its current configuration, in the frame of the motor. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Movement Sensor
The movement sensor component supports the following methods. Some methods are only supported by certain models:
Method Name | Description | Models That Support This Method |
---|---|---|
GetPosition | Get the current latitude, longitude and altitude. | GPS models, wheeled-odometry |
GetLinearVelocity | Get the current linear velocity as a 3D vector. | GPS models, wheeled-odometry |
GetAngularVelocity | Get the current angular velocity as a 3D vector. | IMU models, gyro-mpu6050 , and wheeled-odometry |
GetLinearAcceleration | Get the current linear acceleration as a 3D vector. | IMU models, accel-adxl345 , and gyro-mpu6050 |
GetCompassHeading | Get the current compass heading in degrees. | GPS models |
GetOrientation | Get the current orientation. | IMU models, wheeled-odometry |
GetProperties | Get the supported properties of this sensor. | all models |
GetAccuracy | Get the accuracy of the various sensors. | GPS models |
GetReadings | Obtain the measurements/data specific to this sensor. | all models |
GetGeometries | Get all the geometries associated with the movement sensor in its current configuration, in the frame of the movement sensor. | all models |
DoCommand | Send or receive model-specific commands. | all models |
Close | Safely shut down the resource and prevent further use. | all models |
Power Sensor
The power sensor component supports the following methods:
Method Name | Description |
---|---|
GetCurrent | Return the current of a specified device and whether it is AC or DC. |
GetVoltage | Return the voltage of a specified device and whether it is AC or DC. |
GetPower | Return the power consumption of a specified device in watts. |
GetGeometries | Get all the geometries associated with the power sensor in its current configuration, in the frame of the power sensor. |
GetReadings | Get all measurements or readings that this power sensor provides. |
DoCommand | Execute model-specific commands that are not otherwise defined by the component API. |
Close | Safely shut down the resource and prevent further use. |
Sensor
The sensor component supports the following methods:
Method Name | Description |
---|---|
GetReadings | Get the measurements or readings that this sensor provides. |
GetGeometries | Get all the geometries associated with the sensor in its current configuration, in the frame of the sensor. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Servo
The servo component supports the following methods:
Method Name | Description |
---|---|
Move | Move the servo to the desired angle. |
GetPosition | Get the current angle of the servo. |
Stop | Stop the servo. |
GetGeometries | Get all the geometries associated with the servo in its current configuration, in the frame of the servo. |
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
Service APIs
These APIs provide interfaces for controlling and getting information from the services you configured on a machine. Built-in API methods are defined for each service implementation. Documentation on using these methods in your SDK code is found on service pages as follows:
Base Remote Control
The base remote control service supports the following methods:
Method Name | Description |
---|---|
Close | Close out of all remote control related systems. |
ControllerInputs | Get a list of inputs from the controller that is being monitored for that control mode. |
Data Management
The data management service supports the following methods:
Method Name | Description |
---|---|
Sync | Sync data stored on the machine to the cloud. |
Generic
The generic service supports the following methods:
Method Name | Description |
---|---|
DoCommand | Send or receive model-specific commands. |
Close | Safely shut down the resource and prevent further use. |
ML Model
The ML model service supports the following methods:
Method Name | Description |
---|---|
Infer | Take an already ordered input tensor as an array, make an inference on the model, and return an output tensor map. |
Metadata | Get the metadata (such as name, type, expected tensor/array shape, inputs, and outputs) associated with the ML model. |
DoCommand | Send arbitrary commands to the resource. |
Close | Safely shut down the resource and prevent further use. |
Motion
The motion service supports the following methods:
Method Name | Description |
---|---|
Move | Move multiple components in a coordinated way to achieve a desired motion. |
GetPose | Get the current location and orientation of a component as a Pose . |
MoveOnMap | Move a base component to a Pose in respect to the origin of a SLAM map. Use the machine’s position reported by the SLAM service to check the location of the machine. |
MoveOnGlobe | Move a base component to a destination GPS point. Use a Movement Sensor to measure the machine’s GPS coordinates. |
StopPlan | Stop a base component being moved by an in progress MoveOnGlobe or MoveOnMap call. |
GetPlan | Returns the plan history of the most recent MoveOnGlobe or MoveOnMap call to move a base component. |
ListPlanStatuses | Returns the plan statuses created by MoveOnGlobe or MoveOnMap calls. |
DoCommand | Send arbitrary commands to the resource. |
Close | Safely shut down the resource and prevent further use. |
Navigation
The navigation service supports the following methods:
Method Name | Description |
---|---|
Mode | Get the mode the service is operating in. |
SetMode | Set the mode the service is operating in. |
Location | Get the current location of the robot. |
Waypoints | Get the waypoints currently in the service’s data storage. |
GetProperties | Get information regarding the service. |
AddWaypoint | Add a waypoint to the service’s data storage. |
RemoveWaypoint | Remove a waypoint from the service’s data storage. |
Paths | Get each path, the series of geo points the robot plans to travel through to get to a destination waypoint, in the robot’s motion planning. |
Obstacles | Get the obstacles currently in the service’s data storage. |
DoCommand | Execute model-specific commands that are not otherwise defined by the service API. |
Close | Safely shut down the resource and prevent further use. |
SLAM
The Simultaneous Localization And Mapping (SLAM) service supports the following methods:
Method Name | Description |
---|---|
GetPosition | Get the current position of the specified source component in the point cloud SLAM map. |
GetPointCloudMap | Get the point cloud SLAM map. |
GetProperties | Get information regarding the current SLAM session. |
GetInternalState | Get the internal state of the SLAM algorithm required to continue mapping/localization. |
DoCommand | Send arbitrary commands to the resource. |
Close | Safely shut down the resource and prevent further use. |
Vision
Different vision service models support different methods:
Method Name | Description | Models That Support This Method |
---|---|---|
GetDetections | Get detections from an image. | detectors |
GetDetectionsFromCamera | Get detections from the next image from a camera. | detectors |
GetClassifications | Get classifications from an image. | classifiers |
GetClassificationsFromCamera | Get classifications from the next image from a camera. | classifiers |
GetObjectPointClouds | Get a list of point cloud objects from a 3D camera. | segmenters |
DoCommand | Send arbitrary commands to the resource. | |
Close | Safely shut down the resource and prevent further use. |
Signaling APIs
GPIO pins
In addition to the board API, the board component supports the following methods for interfacing with GPIO pins on a board:
Method Name | Description |
---|---|
SetGPIO | Set the output of this pin to high/low. |
GetGPIO | Get if this pin is active (high). |
GetPWM | Get the pin’s pulse-width modulation duty cycle. |
SetPWM | Set the pin’s pulse-width modulation duty cycle. |
PWMFreq | Get the pulse-width modulation frequency of this pin. |
SetPWMFreq | Set the pulse-width modulation frequency of this pin. |
Close | Safely shut down the resource and prevent further use. |
Analog-to-digital converters (ADCs)
In addition to the board API, the board component supports the following methods for interfacing with ADCs on a board:
Method Name | Description |
---|---|
Read | Read the current integer value of the digital signal output by the ADC. |
Close | Safely shut down the resource and prevent further use. |
Digital interrupts
In addition to the board API, the board component supports the following methods for interfacing with digital interrupts on a board:
Method Name | Description |
---|---|
Value | Get the current value of this interrupt. |
Tick | Record an interrupt. |
AddCallback | Add a channel as a callback for Tick(). |
Close | Safely shut down the resource and prevent further use. |
ResourceBase methods
In the Python SDK, the ResourceBase
class defines a basic set of API methods that all child resources should provide for users.
In the other SDKs, resource APIs implement but do not inherit these base requirements.
ResourceBase
methods include:
FromRobot
Get a resource configured on a machine by "name"
.
Parameters:
robot
(RobotClient): The machine.name
(str): Thename
of the resource.
Returns:
- (Resource): The named resource if it exists on your machine. For example, an arm.
my_arm = Arm.from_robot(robot, "my_arm")
For more information, see the Python SDK Docs.
Parameters:
r
(RobotClient): The machine.name
(string): The “name” of the resource.
Returns:
- (Resource): The named resource if it exists on your machine. For example, an arm.
my_arm = arm.FromRobot(robot, "my_arm")
For more information, see the Go SDK Docs.
In the TypeScript SDK, the equivalent of the FromRobot
is defined in each resource API’s client constructor.
For example, a component with type arm
and name my_arm
belonging to a machine robot
is instantiated as follows:
Parameters:
client
(RobotClient): The machine.name
(string): Thename
of the resource.
Returns:
- (Resource): The named resource if it exists on your machine. For example, an ArmClient.
const myArmClient = new VIAM.ArmClient(robot, "my_arm");
For more information, see the Typescript SDK Docs.
Name
Info
An equivalent for Name
is not currently provided by the TypeScript SDK.
Get the ResourceName
of a resource with the configured name
.
Parameters:
name
(str): Thename
of the resource.
Returns:
name
(proto.common.ResourceName
): TheResourceName
of the resource, including string fields for thenamespace
,type
,subtype
, andname
.
my_arm_name = my_arm.get_resource_name("my_arm")
For more information, see the Python SDK Docs.
Get the Name
of the resource.
Parameters:
- None
Returns:
name
(Name): TheName
of the resource, including fields for theAPI
withType
andSubtypeName
, and stringRemote
andName
.
MyArmName := MyArm.Name()
For more information, see the Go SDK Docs.
DoCommand
DoCommand sends commands containing arbitrary data to the resource.
Parameters:
command
(Mapping[str, viam.utils.ValueTypes]
): The command to execute.timeout
(Optional[float]
): 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]
): The result of the executed command.
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.cmd
(map[string]interface{}): The command to execute.
Returns:
- (map[string]interface{}): The result of the executed command.
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
Parameters:
command
(StructType): The command to execute.
Returns:
- (StructType): The result of the executed command.
For more information, see the Typescript SDK Docs.
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!