Edit

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
`GetOperations`	Get the list of operations currently running on the machine.
`GetMachineStatus`	Get status information about the machine.
`ResourceNames`	Get a list of all known resource names connected to this machine.
`CancelOperation`	Cancel the specified operation on the machine.
`BlockForOperation`	Blocks on the specified operation on the machine.
`DiscoverComponents`	Get a list of discovered component configurations.
`FrameSystemConfig`	Get the configuration of the frame system of a given machine.
`TransformPose`	Transform a given source Pose from the original reference frame to a new destination reference frame.
`TransformPCD`	Transforms the pointcloud to the desired frame in the robot’s frame system.
`GetStatus`	Get the status of the resources on the machine.
`StopAll`	Cancel all current and outstanding operations for the machine and stop all actuators and movement.
`RestartModule`	Reload a module as if its config changed.
`Log`	Create a LogEntry object from the log to send to the RDK over gRPC.
`GetCloudMetadata`	Get app-related information about the robot.
`GetVersion`	Return version information about the machine.
`Options.with_api_key`	Create a `RobotClient.Options` using 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 this machine.
`Shutdown`	Shutdown shuts down the machine.
`Close`	Close 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 Name	Description
`GetUserIDByEmail`	Get the ID of a user by email.
`CreateOrganization`	Create an organization.
`ListOrganizations`	List the organizations the user is an authorized user of.
`GetOrganizationsWithAccessToLocation`	Get all organizations that have access to a location.
`ListOrganizationsByUser`	List the organizations a user belongs to.
`GetOrganization`	Return details about the requested organization.
`GetOrganizationNamespaceAvailability`	Check the availability of an organization namespace.
`UpdateOrganization`	Updates organization details.
`DeleteOrganization`	Delete an organization.
`ListOrganizationMembers`	List the members and invites of the organization that you are currently authenticated to.
`CreateOrganizationInvite`	Create an organization invite and send it by email.
`UpdateOrganizationInviteAuthorizations`	Update (add or remove) the authorizations attached to an organization invite that has already been created.
`DeleteOrganizationMember`	Remove a member from the organization you are currently authenticated to.
`DeleteOrganizationInvite`	Delete a pending organization invite to the organization you are currently authenticated to.
`ResendOrganizationInvite`	Resend a pending organization invite email.
`CreateLocation`	Create and name a location under the organization you are currently authenticated to.
`GetLocation`	Get a location by its location ID.
`UpdateLocation`	Change the name of a parent location and/or assign it a new location.
`DeleteLocation`	Delete a location.
`ListLocations`	Get a list of all locations under the organization you are currently authenticated to.
`ShareLocation`	Share a location with an organization.
`UnshareLocation`	Stop sharing a location with an organization.
`LocationAuth`	Get a location’s `LocationAuth` (location secret or secrets).
`CreateLocationSecret`	Create a new location secret.
`DeleteLocationSecret`	Delete a location secret.
`GetRobot`	Get a machine by its ID.
`GetRobotAPIKeys`	Gets the API keys for the machine.
`GetRobotParts`	Get a list of all the parts under a specific machine.
`GetRobotPart`	Get a specific machine part.
`GetRobotPartLogs`	Get the logs associated with a specific 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`	Change the name of and assign an optional new configuration to a machine part.
`NewRobotPart`	Create a new machine part.
`DeleteRobotPart`	Delete the specified machine part.
`MarkPartAsMain`	Mark a machine part as the main part of a machine.
`MarkPartForRestart`	Mark a specified machine part for restart.
`CreateRobotPartSecret`	Create a machine part secret.
`DeleteRobotPartSecret`	Delete a machine part secret.
`ListRobots`	Get a list of all machines in a specified location.
`NewRobot`	Create a new machine.
`UpdateRobot`	Change the name of an existing machine.
`DeleteRobot`	Delete a specified machine.
`ListFragments`	Get a list of fragments in the organization you are currently authenticated to.
`GetFragment`	Get a fragment by ID.
`CreateFragment`	Create a new private fragment.
`UpdateFragment`	Update a fragment name and its config and/or visibility.
`DeleteFragment`	Delete a fragment.
`GetFragmentHistory`	Get fragment history.
`AddRole`	Add a role under the organization you are currently authenticated to.
`RemoveRole`	Remove a role under the organization you are currently authenticated to.
`ChangeRole`	Changes an existing role to a new role.
`ListAuthorizations`	List all authorizations (owners and operators) of a specific resource (or resources) within the organization you are currently authenticated to.
`CheckPermissions`	Check 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.
`GetRegistryItem`	Get registry item by ID.
`CreateRegistryItem`	Create a registry item.
`UpdateRegistryItem`	Update a registry item.
`ListRegistryItems`	List the registry items in an organization.
`DeleteRegistryItem`	Delete a registry item.
`CreateModule`	Create a module under the organization you are currently authenticated to.
`UpdateModule`	Update the documentation URL, description, models, entrypoint, and/or the visibility of a module.
`UploadModuleFile`	Upload a module file.
`GetModule`	Get a module by its ID.
`ListModules`	List the modules under the organization you are currently authenticated to.
`CreateKey`	Create a new API key.
`DeleteKey`	Delete an API key.
`RotateKey`	Rotate an API key.
`ListKeys`	List all keys for the organization that you are currently authenticated to.
`CreateKeyFromExistingKeyAuthorizations`	Create a new API key with an existing key’s authorizations.

Data client API

The data client API supports the following methods:

Methods to upload data like images or sensor readings directly to the Viam app:

Method Name	Description
`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 to the Viam app.
`FileUpload`	Upload arbitrary files stored on your machine to the Viam app by file name.
`FileUploadFromPath`	Upload files stored on your machine to the Viam app by filepath.
`StreamingDataCaptureUpload`	Upload the contents of streaming binary data and the relevant metadata to the Viam app.

Methods to download, filter, tag, or perform other tasks on data like images or sensor readings:

Method Name	Description
`TabularDataByFilter`	Retrieve optionally filtered tabular data from the Viam app.
`TabularDataBySQL`	Obtain unified tabular data and metadata, queried with SQL.
`TabularDataByMQL`	Obtain unified tabular data and metadata, queried with MQL.
`BinaryDataByFilter`	Retrieve optionally filtered binary data from the Viam app.
`BinaryDataByIDs`	Retrieve binary data from the Viam app by `BinaryID`.
`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 by ids.
`RemoveTagsFromBinaryDataByFilter`	Remove tags from binary data by filter.
`TagsByFilter`	Get a list of tags using a filter.
`AddBoundingBoxToImageByID`	Add a bounding box to an image specified by its BinaryID.
`RemoveBoundingBoxFromImageByID`	Removes a bounding box from an image specified by its BinaryID.
`BoundingBoxLabelsByFilter`	Get a list of bounding box labels using a Filter.
`GetDatabaseConnection`	Get a connection to access a MongoDB Atlas Data federation instance.
`ConfigureDatabaseUser`	Configure a database user for the Viam organization’s MongoDB Atlas Data Federation instance.
`AddBinaryDataToDatasetByIDs`	Add the `BinaryData` to the provided dataset.
`RemoveBinaryDataFromDatasetByIDs`	Remove the BinaryData from the provided dataset.

Methods to work with datasets:

Method Name	Description
`CreateDataset`	Create a new dataset.
`DeleteDataset`	Delete a dataset.
`RenameDataset`	Rename a dataset specified by the dataset ID.
`ListDatasetsByOrganizationID`	Get the datasets in an organization.
`ListDatasetsByIDs`	Get a list of datasets using their IDs.

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
`SubmitTrainingJob`	Submit a training job.
`SubmitCustomTrainingJob`	Submit a training job from a custom training script.
`GetTrainingJob`	Get training job metadata.
`ListTrainingJobs`	Get training job metadata for all jobs within an organization.
`CancelTrainingJob`	Cancel the specified training job.
`DeleteCompletedTrainingJob`	Delete a completed training job from the database, whether the job succeeded or failed.

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.
`GetOrgBillingInformation`	Access billing information (payment method, billing tier, etc.) for a given org.
`GetInvoicesSummary`	Access total outstanding balance plus invoice summaries for a given org.
`GetInvoicePdf`	Access invoice PDF data and optionally save it to a provided file path.

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, relative to the base of the arm.
`MoveToJointPositions`	Move each joint on the arm to the position specified in `positions`.
`GetJointPositions`	Get the current position of each joint on the arm.
`GetKinematics`	Get the kinematics information associated with the arm as the format and byte contents of the kinematics file.
`IsMoving`	Get if the arm is currently moving.
`Stop`	Stop all motion of the arm.
`GetGeometries`	Get all the geometries associated with the arm in its current configuration, in the frame of the arm.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`FromRobot`	Get the resource from the provided robot with the given name.
`GetResourceName`	Get the `ResourceName` for this arm with the given name.
`Close`	Safely shut down the resource and prevent further use.

Base

The base component supports the following methods:

Method Name	Description	`viam-micro-server` Support
`MoveStraight`	Move the base in a straight line across the given distance (mm) at the given velocity (mm/sec).
`Spin`	Turn the base in place, rotating it to the given angle (degrees) at the given angular velocity (degrees/sec).
`SetPower`	Set the linear and angular power of the base, represented as a percentage of max power for each direction in the range of [-1.0 to 1.0].
`SetVelocity`	Set the linear velocity (mm/sec) and angular velocity (degrees/sec) of the base.
`GetProperties`	Get the width and turning radius of the model of base in meters.
`IsMoving`	Returns whether the base is actively moving (or attempting to move) under its own power.
`Stop`	Stop the base from moving immediately.
`GetGeometries`	Get all the geometries associated with the base in its current configuration, in the frame of the base.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`FromRobot`	Get the resource from the provided robot with the given name.
`GetResourceName`	Get the `ResourceName` for this base with the given name.
`Close`	Safely shut down the resource and prevent further use.

Board

The board component supports the following methods:

Method Name	Description	`viam-micro-server` Support
`SetGPIO`	Set the digital signal output of this pin to low (0V) or high (active, >0V).
`GetGPIO`	Get if the digital signal output of this pin is high (active, >0V).
`GetPWM`	Get the pin’s pulse-width modulation (PWM) duty cycle: a float [`0.0`, `1.0`] representing the percentage of time the digital signal output by this pin is in the high state (active, >0V) relative to the interval period of the PWM signal (interval period being the mathematical inverse of the PWM frequency).
`SetPWM`	Set the pin’s Pulse-width modulation (PWM) duty cycle: a float [`0.0`, `1.0`] indicating the percentage of time the digital signal output of this pin is in the high state (active, >0V) relative to the interval period of the PWM signal (interval period being the mathematical inverse of the PWM frequency).
`PWMFrequency`	Get the PWM frequency of the GPIO pin.
`SetPWMFrequency`	Set the pin to the given PWM `frequency` (in Hz). When `frequency` is 0, it will use the board’s default PWM frequency.
`AnalogNames`	Get the name of every configured `Analog` on the board.
`AnalogByName`	Get a configured `Analog` by `name`.
`Write`	Write an analog value to a pin on the board.
`GetDigitalInterruptValue`	Get a configured `DigitalInterrupt` by `name`.
`StreamTicks`	Start a stream of `DigitalInterrupt` ticks.
`SetPowerMode`	Set the board to the indicated `PowerMode`.
`GetGeometries`	Get all the geometries associated with the board in its current configuration, in the frame of the board.
`Read`	Read the current integer value of the digital signal output by the ADC.
`Value`	Get the current value of this interrupt.
`DigitalInterruptNames`	Get the name of every configured `DigitalInterrupt` on the board.
`GPIOPinByName`	Get a `GPIOPin` by pin number.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`FromRobot`	Get the resource from the provided robot with the given name.
`Name`	Get the name of the digital interrupt.
`GetResourceName`	Get the `ResourceName` for this board with the given name.
`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`	Get simultaneous images from different imagers, along with associated metadata.
`GetPointCloud`	Get a point cloud from the camera as bytes with a MIME type describing the structure of the data.
`GetProperties`	Get the camera intrinsic parameters and camera distortion, as well as whether the camera supports returning point clouds.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`GetGeometries`	Get all the geometries associated with the camera in its current configuration, in the frame of the camera.
`FromRobot`	Get the resource from the provided robot with the given name.
`GetResourceName`	Get the `ResourceName` for this camera with the given name.
`Close`	Safely shut down the resource and prevent further use.

Encoder

The encoder component supports the following methods:

Method Name	Description	`viam-micro-server` Support
`GetPosition`	Get the current position of the encoder in ticks or degrees.
`ResetPosition`	Set the current position of the encoder to be the new zero position.
`GetProperties`	Get a list of all the position types that are supported by a given encoder.
`GetGeometries`	Get all the geometries associated with the encoder in its current configuration, in the frame of the encoder.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`GetResourceName`	Get the `ResourceName` for this encoder with the given name.
`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 axis of the gantry (mm).
`MoveToPosition`	Move the axes of the gantry to the desired positions (mm) at the requested speeds (mm/sec).
`GetLengths`	Get the lengths of the axes of the gantry (mm).
`Home`	Run the homing sequence of the gantry to re-calibrate the axes with respect to the limit switches.
`GetGeometries`	Get all the geometries associated with the gantry in its current configuration, in the frame of the gantry.
`IsMoving`	Get if the gantry is currently moving.
`Stop`	Stop all motion of the gantry.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`FromRobot`	Get the resource from the provided robot with the given name.
`GetResourceName`	Get the `ResourceName` for this gantry with the given name.
`Close`	Safely shut down the resource and prevent further use.

Generic

The generic component supports the following methods:

Method Name	Description	`viam-micro-server` Support
`DoCommand`	Execute model-specific commands.
`GetGeometries`	Get all the geometries associated with the generic component in its current configuration, in the frame of the generic component.
`FromRobot`	Get the resource from the provided robot with the given name.
`GetResourceName`	Get the `ResourceName` for this generic component with the given name.
`Close`	Safely shut down the resource and prevent further use.

Gripper

The gripper component supports the following methods:

Method Name	Description
`Open`	Opens the gripper.
`Grab`	Closes the gripper until it grabs something or closes completely, and returns whether it grabbed something or not.
`IsMoving`	Returns whether the gripper is actively moving (or attempting to move) under its own power.
`Stop`	Stops the gripper.
`GetGeometries`	Get all the geometries associated with the gripper in its current configuration, in the frame of the gripper.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`FromRobot`	Get the resource from the provided robot with the given name.
`GetResourceName`	Get the `ResourceName` for this gripper with the given name.
`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 the Controls that your controller provides.
`GetEvents`	This 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.
`TriggerEvent`	Directly send an Event Object from external code.
`GetGeometries`	Get all the geometries associated with the input controller in its current configuration, in the frame of the input controller.
`RegisterControlCallback`	Defines a callback function to execute whenever one of the EventTypes selected occurs on the given Control.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`GetResourceName`	Get the `ResourceName` for this input controller with the given name.
`Close`	Safely shut down the resource and prevent further use.

Motor

The motor component supports the following methods:

Method Name	Description	`viam-micro-server` Support
`SetPower`	Set the portion of max power to send to the motor (between `-1` and `1`).
`SetRPM`	Spin the motor indefinitely at the specified speed, in revolutions per minute. If `rpm` is positive, the motor will spin forwards, and if `rpm` is negative, the motor will spin backwards.
`GoFor`	Spin the motor the specified number of revolutions at specified revolutions per minute.
`GoTo`	Turn the motor to a specified position (in terms of revolutions from home/zero) at a specified speed in revolutions per minute (RPM).
`ResetZeroPosition`	Set the current position (modified by `offset`) to be the new zero (home) position.
`GetPosition`	Report the position of the motor based on its encoder.
`GetProperties`	Report a dictionary mapping optional properties to whether it is supported by this motor.
`IsPowered`	Return 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`).
`GetGeometries`	Get all the geometries associated with the motor in its current configuration, in the frame of the motor.
`IsMoving`	Return whether the motor is actively moving (or attempting to move) under its own power.
`Stop`	Cut the power to the motor immediately, without any gradual step down.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`FromRobot`	Get the resource from the provided robot with the given name.
`GetResourceName`	Get the `ResourceName` for this motor with the given name.
`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
`ControllerInputs`	Get a list of inputs from the controller that are being monitored for that control mode.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`Close`	Close out of all remote control related systems.

Data Management

The data management service supports the following methods:

Method Name	Description	`viam-micro-server` Support
`Sync`	Sync data stored on the machine to the cloud.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`Close`	Safely shut down the resource and prevent further use.

Generic

The generic service supports the following methods:

Method Name	Description
`DoCommand`	Execute model-specific commands.
`GetResourceName`	Get the `ResourceName` for this instance of the generic service with the given name.
`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: name, data type, expected tensor/array shape, inputs, and outputs associated with the ML model.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`GetResourceName`	Get the `ResourceName` for this instance of the ML model service with the given name.
`Close`	Safely shut down the resource and prevent further use.

Motion

The motion service supports the following methods:

Method Name	Description
`Move`	The `Move` method is the primary way to move multiple components, or to move any object to any other location.
`MoveOnMap`	Move a base component to a destination pose on a SLAM map.
`MoveOnGlobe`	Move a base component to a destination GPS point, represented in geographic notation (latitude, longitude).
`GetPose`	`GetPose` gets the location and orientation of a component within the frame system.
`StopPlan`	Stop a base component being moved by an in progress `MoveOnGlobe` or `MoveOnMap` call.
`ListPlanStatuses`	Returns the statuses of plans created by `MoveOnGlobe` or `MoveOnMap` calls that meet at least one of the following conditions since the motion service initialized: - the plan’s status is in progress - the plan’s status changed state within the last 24 hours All repeated fields are in chronological order.
`GetPlan`	By default, returns the plan history of the most recent `MoveOnGlobe` or `MoveOnMap` call to move a base component.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`GetResourceName`	Get the `ResourceName` for this instance of the motion service with the given name.
`Close`	Safely shut down the resource and prevent further use.

The navigation service supports the following methods:

Method Name	Description
`GetMode`	Get the `Mode` the service is operating in.
`SetMode`	Set the `Mode` the service is operating in.
`GetLocation`	Get the current location of the robot in the navigation service.
`GetWaypoints`	Get an array of waypoints currently in the service’s data storage.
`AddWaypoint`	Add a waypoint to the service’s data storage.
`RemoveWaypoint`	Remove a waypoint from the service’s data storage.
`GetObstacles`	Get an array or list of the obstacles currently in the service’s data storage.
`GetPaths`	Get each path, the series of geo points the robot plans to travel through to get to a destination waypoint, in the machine’s motion planning.
`GetProperties`	Get information about the navigation service.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`GetResourceName`	Get the `ResourceName` for this instance of the navigation service with the given name.
`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 component the SLAM service is configured to source point cloud data from in the SLAM map as a `Pose`.
`GetPointCloudMap`	Get the point cloud map.
`GetInternalState`	Get the internal state of the SLAM algorithm required to continue mapping/localization.
`GetProperties`	Get information about the current SLAM session.
`InternalStateFull`	`InternalStateFull` concatenates the streaming responses from `InternalState` into the internal serialized state of the SLAM algorithm.
`PointCloudMapFull`	`PointCloudMapFull` concatenates the streaming responses from `PointCloudMap` into a full point cloud.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`GetResourceName`	Get the `ResourceName` for this instance of the SLAM service with the given name.
`Close`	Safely shut down the resource and prevent further use.

Vision

Different vision service models support different methods:

Method Name	Description
`GetDetectionsFromCamera`	Get a list of detections from the next image from a specified camera using a configured detector.
`GetDetections`	Get a list of detections from a given image using a configured detector.
`GetClassificationsFromCamera`	Get a list of classifications from the next image from a specified camera using a configured classifier.
`GetClassifications`	Get a list of classifications from a given image using a configured classifier.
`GetObjectPointClouds`	Get a list of 3D point cloud objects and associated metadata in the latest picture from a 3D camera (using a specified segmenter).
`CaptureAllFromCamera`	Get the next image, detections, classifications, and objects all together, given a camera name.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the service API.
`FromRobot`	Get the resource from the provided robot with the given name.
`GetResourceName`	Get the `ResourceName` for this instance of the Vision service with the given name.
`GetProperties`	Fetch information about which vision methods a given vision service supports.
`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): The name 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): The name 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.

Python
Go

Parameters:

name (str): The name of the resource.

Returns:

name (proto.common.ResourceName): The ResourceName of the resource, including string fields for the namespace, type, subtype, and name.

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:

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.

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:

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.

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:

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!

Interact with Resources with Viam's Client SDKs

Robot management APIs

Robot API

Fleet management API

Data client API

ML training API

Billing client API

Component APIs

Arm

Base

Board

Camera

Encoder

Gantry

Generic

Gripper

Input Controller

Motor

Movement Sensor

Power Sensor

Sensor

Servo

Service APIs

Base Remote Control

Data Management

Generic

ML Model

Motion

Navigation

SLAM

Vision

ResourceBase methods

FromRobot

Name

Info

DoCommand