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 robot when you execute your program, providing you a convenient interface for accessing information about and controlling the resources you have configured on your robot.

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 robot by "name".

Parameters:

Returns:

  • (Resource): The named resource if it exists on your robot. 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 robot. 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 robot 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:

For more information, see the Python SDK Docs.

Parameters:

Returns:

For more information, see the Go SDK Docs.

Parameters:

Returns:

For more information, see the Typescript SDK Docs.

Component APIs

These APIs provide interfaces for controlling and getting information from various components of a robot. 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.
MoveToJointPositionsMove each joint on the arm to the desired position.
JointPositionsGet the current position of each joint on the arm.
StopStop the arm from moving.
IsMovingGet if the arm is currently moving.
GetKinematicsGet the kinematics information associated with the arm.
DoCommandSend or receive model-specific commands.

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.
DoCommandSend or receive model-specific commands.

Board

The board component supports the following methods:

Method NameDescription
AnalogReaderByNameGet an AnalogReader by name.
DigitalInterruptByNameGet a DigitalInterrupt by name.
GPIOPinByNameGet a GPIOPin by its pin number.
AnalogReaderNamesGet the name of every AnalogReader.
DigitalInterruptNamesGet the name of every DigitalInterrupt.
StatusGet the current status of this board.
ModelAttributesGet the attributes related to the model of this board.
SetPowerModeSet the board to the indicated power mode.
DoCommandSend or receive model-specific commands.

Camera

The camera component supports the following methods:

Method NameDescription
GetImageReturn an image from the camera.
GetImagesReturn multiple simultaneous images from different imagers, along with associated metadata.
GetPointCloudReturn a point cloud from the camera.
GetPropertiesReturn the camera intrinsic and camera distortion parameters, as well as whether the camera supports returning point clouds.
DoCommandSend or receive model-specific commands.

Encoder

The encoder component supports the following methods:

Method NameDescription
GetPositionGet the current position of the encoder.
ResetPositionReset the position to zero.
GetPropertiesGet the supported properties of this encoder.
DoCommandSend or receive model-specific commands.

Gantry

The gantry component supports the following methods:

Method NameDescription
GetPositionGet the current positions of the axes of the gantry in mm.
MoveToPositionMove the axes of the gantry to the desired positions.
LengthsGet the lengths of the axes of the gantry in mm.
StopStop the gantry from moving.
IsMovingGet if the gantry is currently moving.
DoCommandSend or receive model-specific commands.

Generic

The generic component supports the following methods:

Method NameDescription
DoCommandSend or receive model-specific commands.

Gripper

The gripper component supports the following methods:

Method NameDescription
OpenOpen the gripper.
GrabClose the gripper until it grabs something or closes completely.
StopStop the gripper’s movement.
IsMovingReport whether the gripper is currently moving.
DoCommandSend or receive model-specific commands.

Input Controller

The input controller component supports the following methods:

Method NameDescription
GetControlsGet a list of input Controls that this Controller provides.
GetEventsGet the current state of the Controller as a map of the most recent Event for each Control.
RegisterControlCallbackDefine a callback function to execute whenever one of the EventTypes selected occurs on the given Control.
DoCommandSend or receive model-specific commands.

Motor

The motor component supports the following methods:

Method NameDescription
SetPowerSet the power to send to the motor as a portion of max power.
GoForSpin the motor the specified number of revolutions at specified RPM.
GoToSend the motor to a specified position (in terms of revolutions from home) at a specified speed.
ResetZeroPositionSet the current position to be the new zero (home) position.
GetPositionReport the position of the motor based on its encoder. Not supported on all motors.
GetPropertiesReturn whether or not the motor supports certain optional features.
IsPoweredReturn whether or not the motor is currently on, and the amount of power to it.
IsMovingReturn whether the motor is moving or not.
StopCut power to the motor off immediately, without any gradual step down.
DoCommandSend or receive model-specific commands.

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
GetLinearVelocityGet the current linear velocity as a 3D vector.GPS models
GetAngularVelocityGet the current angular velocity as a 3D vector.IMU models and gyro-mpu6050
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 and imu-vectornav
GetOrientationGet the current orientation.IMU models
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
DoCommandSend or receive model-specific commands.all models

Sensor

The sensor component supports the following methods:

Method NameDescription
GetReadingsGet the measurements or readings that this sensor provides.
DoCommandSend or receive model-specific commands.

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.
DoCommandSend or receive model-specific commands.

Service APIs

These APIs provide interfaces for controlling and getting information from the services you configured on a robot. 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 robot to the cloud.

MLModel

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.

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.
MoveOnGlobeMove a base component to a destination GPS point. Use a Movement Sensor to measure the robot’s GPS coordinates.

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.
AddWaypointAdd a waypoint to the service’s data storage.
RemoveWaypointRemove a waypoint from the service’s data storage.
GetObstaclesGet the obstacles currently in the service’s data storage.

Sensors

The sensors service supports the following methods:

Method NameDescription
GetSensorsReturn a list of names of the available sensors.
GetReadingsReturn a list of readings from a given list of sensors.

SLAM

The 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.
GetInternalStateGet the internal state of the SLAM algorithm required to continue mapping/localization.
GetLatestMapInfoGet the timestamp of the last update to the point cloud SLAM map.

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

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
SetSet the output of this pin to high/low.
GetGet 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.

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 the ADC.

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.
TickRecord an interrupt.
AddCallbackAdd a channel as a callback for Tick().
AddPostProcessorAdd a PostProcessor function for Value().

Robot Management APIs

Robot API

All robots support the following methods through the robot API:

Method NameDescription
DiscoverComponentsGet a list of discovered component configurations.
FrameSystemConfigGet the configuration of a robot’s frame system.
StatusGet the status of each of the resources on the robot.
CloseClose the connections and stop periodic tasks across the robot.
StopAllCancel all operations for the robot and stop its movement.
ResourceNamesGet a list of all the robot’s resources.

Cloud API

The cloud API supports the following methods (among others):

Method NameDescription
ListOrganizationsList the organizations the user owns.
GetOrganizationNamespaceAvailabilityCheck the availability of an organization namespace.
ListOrganizationMembersList the members and invites of the current organization.
UpdateOrganizationInviteAuthorizationsUpdate the authorizations attached to an organization invite that has already been created.
CreateLocationCreate and name a location.
GetLocationGet a location by its ID.
UpdateLocationChange the name of and/or assign a parent location to a location.
DeleteLocationDelete a location.
ListLocationsList locations.
LocationAuthGet a location’s authorization (location secrets).
CreateLocationSecretCreate a new location secret.
DeleteLocationSecretDelete a location secret.
GetRobotGet a robot by robot ID.
GetRobotPartsGet a list of all the parts under a specific robot.
GetRobotPartGet a robot part.
GetRobotPartLogsGet the logs associated with a robot part.
TailRobotPartLogsGet an asynchronous iterator that receives live robot part logs.
GetRobotPartHistoryGet a list containing the history of a robot part.
UpdateRobotPartUpdate the name or configuration of a robot part.
NewRobotPartCreate a new robot part.
DeleteRobotPartDelete a robot part.
NewRobotCreate a new robot.