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 NameDescription
GetOperationsGet the list of operations currently running on the machine.
ResourceNamesGet a list of all known resource names connected to this machine.
CancelOperationCancel the specified operation on the machine.
BlockForOperationBlocks on the specified operation on the machine.
DiscoverComponentsGet a list of discovered component configurations.
FrameSystemConfigGet the configuration of the frame system of a given machine.
TransformPoseTransform a given source Pose from the original reference frame to a new destination reference frame.
TransformPCDTransforms the pointcloud to the desired frame in the robot’s frame system.
GetStatusGet the status of the resources on the machine.
StopAllCancel all current and outstanding operations for the machine and stop all actuators and movement.
LogCreate a LogEntry object from the log to send to the RDK over gRPC.
GetCloudMetadataGet app-related information about the robot.
Options.with_api_keyCreate a RobotClient.Options using an API key as credentials.
AtAddressCreate a RobotClient that is connected to the machine at the provided address.
WithChannelCreate a RobotClient that is connected to a machine over the given channel.
RefreshManually refresh the underlying parts of this machine.
ShutdownShutdown shuts down the machine.
CloseClose the underlying connections and stop any periodic tasks across all constituent parts of the machine.

Fleet management API

The fleet management API supports the following methods:

Method NameDescription
ListOrganizationsList the organizations the user is an authorized user of.
GetOrganizationReturn details about the requested organization.
GetOrganizationNamespaceAvailabilityCheck the availability of an organization namespace.
UpdateOrganizationUpdates organization details.
ListOrganizationMembersList the members and invites of the organization that you are currently authenticated to.
CreateOrganizationInviteCreate an organization invite and send it by email.
UpdateOrganizationInviteAuthorizationsUpdate (add or remove) the authorizations attached to an organization invite that has already been created.
DeleteOrganizationMemberRemove a member from the organization you are currently authenticated to.
DeleteOrganizationInviteDelete a pending organization invite to the organization you are currently authenticated to.
ResendOrganizationInviteResend a pending organization invite email.
CreateLocationCreate and name a location under the organization you are currently authenticated to.
GetLocationGet a location by its location ID.
UpdateLocationChange the name of a parent location and/or assign it a new location.
DeleteLocationDelete a location.
ListLocationsGet a list of all locations under the organization you are currently authenticated to.
LocationAuthGet a location’s LocationAuth (location secret or secrets).
GetRobotGet a machine by its ID.
GetRobotPartsGet a list of all the parts under a specific machine.
GetRobotPartGet a specific machine part.
GetRobotPartLogsGet the logs associated with a specific machine part.
TailRobotPartLogsGet an asynchronous iterator that receives live machine part logs.
GetRobotPartHistoryGet a list containing the history of a machine part.
UpdateRobotPartChange the name of and assign an optional new configuration to a machine part.
NewRobotPartCreate a new machine part.
DeleteRobotPartDelete the specified machine part.
MarkPartAsMainMark a machine part as the main part of a machine.
MarkPartForRestartMark a specified machine part for restart.
CreateRobotPartSecretCreate a machine part secret.
DeleteRobotPartSecretDelete a machine part secret.
ListRobotsGet a list of all machines in a specified location.
NewRobotCreate a new machine.
UpdateRobotChange the name of an existing machine.
DeleteRobotDelete a specified machine.
ListFragmentsGet a list of fragments in the organization you are currently authenticated to.
GetFragmentGet a fragment by ID.
CreateFragmentCreate a new private fragment.
UpdateFragmentUpdate a fragment name and its config and/or visibility.
DeleteFragmentDelete a fragment.
AddRoleAdd a role under the organization you are currently authenticated to.
RemoveRoleRemove a role under the organization you are currently authenticated to.
ListAuthorizationsList all authorizations (owners and operators) of a specific resource (or resources) within the organization you are currently authenticated to.
CheckPermissionsCheck if the organization, location, or robot your ViamClient is authenticated to is permitted to perform some action or set of actions on the resource you pass to the method.
CreateModuleCreate a module under the organization you are currently authenticated to.
UpdateModuleUpdate the documentation URL, description, models, entrypoint, and/or the visibility of a module.
UploadModuleFileUpload a module file.
GetModuleGet a module by its ID.
ListModulesList the modules under the organization you are currently authenticated to.
CreateKeyCreate a new API key.
ListKeysList all keys for the organization that you are currently authenticated to.
CreateKeyFromExistingKeyAuthorizationsCreate a new API key with an existing key’s authorizations.

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 NameDescription
TabularDataByFilterFilter and download tabular data.
BinaryDataByFilterFilter and download binary data.
BinaryDataByIDsDownload binary data by IDs.
TabularDataBySQLObtain unified tabular data and metadata, queried with SQL.
TabularDataByMQLObtain unified tabular data and metadata, queried with MQL.
DeleteTabularDataDelete tabular data older than a specified number of days.
DeleteBinaryDataByFilterFilter and delete binary data.
DeleteBinaryDataByIdsFilter and delete binary data by ids.
AddTagsToBinaryDataByIdsAdd tags to binary data by ids.
AddTagsToBinaryDataByFilterAdd tags to binary data by filter.
RemoveTagsFromBinaryDataByIdsRemove tags from binary data by ids.
RemoveTagsFromBinaryDataByFilterRemove tags from binary data by filter.
TagsByFilterGet tags from data by filter.
BoundingBoxLabelsByFilterGet a list of bounding box labels using a Filter.
GetDatabaseConnectionGet a connection to access a MongoDB Atlas Data federation instance.
BinaryDataCaptureUploadUpload binary data collected on your machine through a specific component and the relevant metadata to the Viam app.
TabularDataCaptureUploadUpload tabular data collected on your machine through a specific component and the relevant metadata to the Viam app.
StreamingDataCaptureUploadUpload the contents of streaming binary data and the relevant metadata to the Viam app.
FileUploadUpload file data stored on your machine and the relevant metadata to the Viam app.
FileUploadFromPathUpload file data stored on your machine from the specified filepath and the relevant metadata to the Viam app.
AddBoundingBoxToImageByIdAdd a bounding box to an image specified by its BinaryID.
RemoveBoundingBoxFromImageByIdRemoves a bounding box from an image specified by its BinaryID.
CreateDatasetCreate a new dataset.
ListDatasetByIdsGet a list of datasets using their IDs.
ListDatasetByOrganizationIdGet the datasets in an organization.
RenameDatasetRename a dataset specified by the dataset ID.
DeleteDatasetDelete a dataset.
AddBinaryDataToDatasetByIdsAdd the BinaryData to the provided dataset. This BinaryData will be tagged with the VIAM_DATASET_{id} label.
RemoveBinaryDataFromDatasetByIdsRemove the BinaryData from the provided dataset. This BinaryData will lose the VIAM_DATASET_{id} tag.
ConfigureDatabaseUserConfigure a database user for the Viam organization’s MongoDB Atlas Data Federation instance.

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 NameDescription
GetTrainingJobGet training job metadata by ID.
ListTrainingJobsGet training job metadata for all jobs within an organization.
SubmitTrainingJobSubmit a training job.
CancelTrainingJobCancel the specified training job.

Billing client API

The billing client API supports the following methods to retrieve billing information from the Viam app:

Method NameDescription
GetCurrentMonthUsageAccess data usage information for the current month for a given organization.
GetInvoicePdfAccess invoice PDF data and optionally save it to a provided file path.
GetInvoicesSummaryAccess total outstanding balance plus invoice summaries for a given org.
GetOrgBillingInformationAccess 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 NameDescription
GetEndPositionGet the current position of the arm as a pose.
MoveToPositionMove the end of the arm to the desired pose, relative to the base of the arm.
MoveToJointPositionsMove each joint on the arm to the position specified in positions.
GetJointPositionsGet the current position of each joint on the arm.
GetKinematicsGet the kinematics information associated with the arm as the format and byte contents of the kinematics file.
IsMovingGet if the arm is currently moving.
StopStop all motion of the arm.
GetGeometriesGet all the geometries associated with the arm in its current configuration, in the frame of the arm.
ReconfigureReconfigure this resource.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
CloseSafely shut down the resource and prevent further use.

Base

The base component supports the following methods:

Method NameDescription
MoveStraightMove the base in a straight line across the given distance at the given velocity.
SpinMove the base to the given angle at the given angular velocity.
SetPowerSet the relative power (out of max power) for linear and angular propulsion of the base.
SetVelocitySet the linear velocity and angular velocity of the base.
IsMovingReturn whether the base is moving or not.
StopStop the base.
GetPropertiesGet the width and turning radius of the base in meters.
GetGeometriesGet all the geometries associated with the base in its current configuration, in the frame of the base.
DoCommandSend or receive model-specific commands.
CloseSafely shut down the resource and prevent further use.

Board

The board component supports the following methods:

Method NameDescription
AnalogByNameGet an Analog by name.
GetDigitalInterruptValueGet a DigitalInterrupt by name.
GetGPIOGet a GPIOPin by its pin number.
SetGPIOSet a GPIOPin by its pin number.
AnalogNamesGet the name of every Analog.
DigitalInterruptNamesGet the name of every DigitalInterrupt.
SetPWMSet the board to the indicated power mode.
StreamTicksStart a stream of DigitalInterrupt ticks.
GetGeometriesGet all the geometries associated with the board in its current configuration, in the frame of the board.
DoCommandSend or receive model-specific commands.
CloseSafely shut down the resource and prevent further use.

Camera

The camera component supports the following methods:

Method NameDescription
GetImageReturn an image from the camera.
GetImagesGet simultaneous images from different imagers, along with associated metadata.
GetPointCloudGet a point cloud from the camera as bytes with a MIME type describing the structure of the data.
GetPropertiesGet the camera intrinsic parameters and camera distortion, as well as whether the camera supports returning point clouds.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
GetGeometriesGet all the geometries associated with the camera in its current configuration, in the frame of the camera.
CloseSafely shut down the resource and prevent further use.

Encoder

The encoder component supports the following methods:

Method NameDescription
GetPositionGet the current position of the encoder in ticks or degrees.
ResetPositionSet the current position of the encoder to be the new zero position.
GetPropertiesGet a list of all the position types that are supported by a given encoder.
GetGeometriesGet all the geometries associated with the encoder in its current configuration, in the frame of the encoder.
ReconfigureReconfigure this resource.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
CloseSafely shut down the resource and prevent further use.

Gantry

The gantry component supports the following methods:

Method NameDescription
GetPositionGet the current positions of the axis of the gantry (mm).
MoveToPositionMove the axes of the gantry to the desired positions (mm) at the requested speeds (mm/sec).
GetLengthsGet the lengths of the axes of the gantry (mm).
HomeRun the homing sequence of the gantry to re-calibrate the axes with respect to the limit switches.
GetGeometriesGet all the geometries associated with the gantry in its current configuration, in the frame of the gantry.
IsMovingGet if the gantry is currently moving.
StopStop all motion of the gantry.
ReconfigureReconfigure this resource.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
CloseSafely shut down the resource and prevent further use.

Generic

The generic component supports the following methods:

Method NameDescription
GetGeometriesGet all the geometries associated with the generic component in its current configuration, in the frame of the generic component.
DoCommandSend or receive model-specific commands.
CloseSafely shut down the resource and prevent further use.

Gripper

The gripper component supports the following methods:

Method NameDescription
OpenOpens the gripper.
GrabCloses the gripper until it grabs something or closes completely, and returns whether it grabbed something or not.
IsMovingReturns whether the gripper is actively moving (or attempting to move) under its own power.
StopStops the gripper.
GetGeometriesGet all the geometries associated with the gripper in its current configuration, in the frame of the gripper.
ReconfigureReconfigure this resource.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
CloseSafely shut down the resource and prevent further use.

Input Controller

The input controller component supports the following methods:

Method NameDescription
GetControlsGet a list of the Controls that your controller provides.
GetEventsThis method returns the current state of the controller as a map of Event Objects, representing the most recent event that has occurred on each available Control.
TriggerEventDirectly send an Event Object from external code.
GetGeometriesGet all the geometries associated with the input controller in its current configuration, in the frame of the input controller.
RegisterControlCallbackDefines a callback function to execute whenever one of the EventTypes selected occurs on the given Control.
ReconfigureReconfigure this resource.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
CloseSafely shut down the resource and prevent further use.

Motor

The motor component supports the following methods:

Method NameDescription
SetPowerSet the portion of max power to send to the motor (between -1 and 1).
GoForSpin the motor the specified number of revolutions at specified revolutions per minute.
GoToTurn the motor to a specified position (in terms of revolutions from home/zero) at a specified speed in revolutions per minute (RPM).
ResetZeroPositionSet the current position (modified by offset) to be the new zero (home) position.
GetPositionReport the position of the motor based on its encoder.
GetPropertiesReport a dictionary mapping optional properties to whether it is supported by this motor.
IsPoweredReturn whether or not the motor is currently running, and the portion of max power (between 0 and 1; if the motor is off the power will be 0).
GetGeometriesGet all the geometries associated with the motor in its current configuration, in the frame of the motor.
IsMovingReturn whether the motor is actively moving (or attempting to move) under its own power.
StopCut the power to the motor immediately, without any gradual step down.
ReconfigureReconfigure this resource.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
CloseSafely 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 NameDescriptionModels That Support This Method
GetPositionGet the current latitude, longitude and altitude.GPS models, wheeled-odometry
GetLinearVelocityGet the current linear velocity as a 3D vector.GPS models, wheeled-odometry
GetAngularVelocityGet the current angular velocity as a 3D vector.IMU models, gyro-mpu6050, and wheeled-odometry
GetLinearAccelerationGet the current linear acceleration as a 3D vector.IMU models, accel-adxl345, and gyro-mpu6050
GetCompassHeadingGet the current compass heading in degrees.GPS models
GetOrientationGet the current orientation.IMU models, wheeled-odometry
GetPropertiesGet the supported properties of this sensor.all models
GetAccuracyGet the accuracy of the various sensors.GPS models
GetReadingsObtain the measurements/data specific to this sensor.all models
GetGeometriesGet all the geometries associated with the movement sensor in its current configuration, in the frame of the movement sensor.all models
DoCommandSend or receive model-specific commands.all models
CloseSafely shut down the resource and prevent further use.all models

Power Sensor

The power sensor component supports the following methods:

Method NameDescription
GetCurrentReturn the current of a specified device and whether it is AC or DC.
GetVoltageReturn the voltage of a specified device and whether it is AC or DC.
GetPowerReturn the power consumption of a specified device in watts.
GetGeometriesGet all the geometries associated with the power sensor in its current configuration, in the frame of the power sensor.
GetReadingsGet all measurements or readings that this power sensor provides.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
CloseSafely shut down the resource and prevent further use.

Sensor

The sensor component supports the following methods:

Method NameDescription
GetReadingsGet the measurements or readings that this sensor provides.
GetGeometriesGet all the geometries associated with the sensor in its current configuration, in the frame of the sensor.
DoCommandSend or receive model-specific commands.
CloseSafely shut down the resource and prevent further use.

Servo

The servo component supports the following methods:

Method NameDescription
MoveMove the servo to the desired angle.
GetPositionGet the current angle of the servo.
StopStop the servo.
GetGeometriesGet all the geometries associated with the servo in its current configuration, in the frame of the servo.
DoCommandSend or receive model-specific commands.
CloseSafely 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 NameDescription
CloseClose out of all remote control related systems.
ControllerInputsGet 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 NameDescription
SyncSync data stored on the machine to the cloud.

Generic

The generic service supports the following methods:

Method NameDescription
DoCommandSend or receive model-specific commands.
CloseSafely shut down the resource and prevent further use.

ML Model

The ML model service supports the following methods:

Method NameDescription
InferTake an already ordered input tensor as an array, make an inference on the model, and return an output tensor map.
MetadataGet the metadata (such as name, type, expected tensor/array shape, inputs, and outputs) associated with the ML model.
DoCommandSend arbitrary commands to the resource.
CloseSafely shut down the resource and prevent further use.

Motion

The motion service supports the following methods:

Method NameDescription
MoveMove multiple components in a coordinated way to achieve a desired motion.
GetPoseGet the current location and orientation of a component as a Pose.
MoveOnMapMove 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.
MoveOnGlobeMove a base component to a destination GPS point. Use a Movement Sensor to measure the machine’s GPS coordinates.
StopPlanStop a base component being moved by an in progress MoveOnGlobe or MoveOnMap call.
GetPlanReturns the plan history of the most recent MoveOnGlobe or MoveOnMap call to move a base component.
ListPlanStatusesReturns the plan statuses created by MoveOnGlobe or MoveOnMap calls.
DoCommandSend arbitrary commands to the resource.
CloseSafely shut down the resource and prevent further use.

The navigation service supports the following methods:

Method NameDescription
ModeGet the mode the service is operating in.
SetModeSet the mode the service is operating in.
LocationGet the current location of the robot.
WaypointsGet the waypoints currently in the service’s data storage.
GetPropertiesGet information regarding the service.
AddWaypointAdd a waypoint to the service’s data storage.
RemoveWaypointRemove a waypoint from the service’s data storage.
PathsGet 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.
ObstaclesGet the obstacles currently in the service’s data storage.
DoCommandExecute model-specific commands that are not otherwise defined by the service API.
CloseSafely shut down the resource and prevent further use.

SLAM

The Simultaneous Localization And Mapping (SLAM) service supports the following methods:

Method NameDescription
GetPositionGet the current position of the specified source component in the point cloud SLAM map.
GetPointCloudMapGet the point cloud SLAM map.
GetPropertiesGet information regarding the current SLAM session.
GetInternalStateGet the internal state of the SLAM algorithm required to continue mapping/localization.
DoCommandSend arbitrary commands to the resource.
CloseSafely shut down the resource and prevent further use.

Vision

Different vision service models support different methods:

Method NameDescriptionModels That Support This Method
GetDetectionsGet detections from an image.detectors
GetDetectionsFromCameraGet detections from the next image from a camera.detectors
GetClassificationsGet classifications from an image.classifiers
GetClassificationsFromCameraGet classifications from the next image from a camera.classifiers
GetObjectPointCloudsGet a list of point cloud objects from a 3D camera.segmenters
DoCommandSend arbitrary commands to the resource.
CloseSafely 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 NameDescription
SetGPIOSet the output of this pin to high/low.
GetGPIOGet if this pin is active (high).
GetPWMGet the pin’s pulse-width modulation duty cycle.
SetPWMSet the pin’s pulse-width modulation duty cycle.
PWMFreqGet the pulse-width modulation frequency of this pin.
SetPWMFreqSet the pulse-width modulation frequency of this pin.
CloseSafely 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 NameDescription
ReadRead the current integer value of the digital signal output by an analog pin or ADC.
WriteWrite an analog value using a pin on an SBC capable of doing so.

Digital interrupts

In addition to the board API, the board component supports the following methods for interfacing with digital interrupts on a board:

Method NameDescription
ValueGet the current value of this interrupt.

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:

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:

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:

Returns:

const myArmClient = new VIAM.ArmClient(robot, "my_arm");

For more information, see the Typescript SDK Docs.

Name

Get the ResourceName of a resource with the configured name.

Parameters:

  • name (str): The name of the resource.

Returns:

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): The Name of the resource, including fields for the API with Type and SubtypeName, and string Remote and Name.
MyArmName := MyArm.Name()

For more information, see the Go SDK Docs.

DoCommand

DoCommand sends commands containing arbitrary data to the resource.

Parameters:

Returns:

my_board = Board.from_robot(robot=robot, name="my_board")

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

await my_board.do_command(my_command)

For more information, see the Python SDK Docs.

Parameters:

Returns:

myBoard, err := board.FromRobot(machine, "my_board")

resp, err := myBoard.DoCommand(ctx, map[string]interface{}{"command": "dosomething", "someparameter": 52})

For more information, see the Go SDK Docs.

Parameters:

Returns:

For more information, see the Typescript SDK Docs.