Manage Robots with Viam's Robot API

The robot API is the application programming interface that manages each of your robots running viam-server. It is the API for high level operations of each robot part. To interact with the robot API with Viam’s SDKs, instantiate a RobotClient (gRPC client) and use that class for all interactions.

These are some of the supported robot API methods. For a full list see GitHub.

Method Name	Description
`DiscoverComponents`	Get a list of discovered component configurations.
`FrameSystemConfig`	Get the configuration of a robot’s frame system.
`Status`	Get the status of each of the resources on the robot.
`Close`	Close the connections and stop periodic tasks across the robot.
`StopAll`	Cancel all operations for the robot and stop its movement.
`ResourceNames`	Get a list of all the robot’s resources.

DiscoverComponents

Get a list of discovered component configurations.

Parameters:

queries (List [viam.proto.robot.DiscoveryQuery]): A list of tuples of API and model that you want to retrieve the component configurations corresponding to.

Returns:

(List[viam.proto.robot.Discovery]): The list of discovered component configurations corresponding to queries.

# Define a new discovery query.
q = robot.DiscoveryQuery(subtype=acme.API, model="some model")

# Define a list of discovery queries.
qs = [q]

# Get component configurations with these queries.
component_configs = await robot.discover_components(qs)

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.
qs ([]resource.DiscoveryQuery): A list of tuples of API and model that you want to retrieve the component configurations corresponding to.

Returns:

([]resource.Discovery): The search query qs and the corresponding list of discovered component configurations as an interface called Results. Results may be comprised of primitives, a list of primitives, maps with string keys (or at least can be decomposed into one), or lists of the forementioned type of maps.
(error): An error, if one occurred.

// Define a new discovery query.
q := resource.NewDiscoveryQuery(acme.API, resource.Model{Name: "some model"})

// Define a list of discovery queries.
qs := []resource.DiscoverQuery{q}

// Get component configurations with these queries.
component_configs, err := robot.DiscoverComponents(ctx.Background(), qs)

For more information, see the Go SDK Docs.

Parameters:

queries (DiscoveryQuery[]): An array of tuples of API and model that you want to retrieve the component configurations corresponding to.

Returns:

(Discovery[]): List of discovered component configurations.

// Define a new discovery query.
const q = new proto.DiscoveryQuery(acme.API, resource.Model{Name: "some model"})

// Define an array of discovery queries.
let qs:  proto.DiscoveryQuery[] = [q]

// Get the array of discovered component configurations.
const componentConfigs = await robot.discoverComponents(queries);

For more information, see the Typescript SDK Docs.

FrameSystemConfig

Get the configuration of the frame system of a given robot.

Parameters:

additional_transforms (Optional[List[viam.proto.common.Transform]]): A optional list of additional transforms.

Returns:

frame_system (List[FrameSystemConfig]): The configuration of a given robot’s frame system.

# Get a list of each of the reference frames configured on the robot.
frame_system = await robot.get_frame_system_config()
print(f"frame system configuration: {frame_system}")

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.

Returns:

(error): An error, if one occurred.
(framesystem.Config): The configuration of the given robot’s frame system.

For more information, see the Go SDK Docs.

// Print the frame system configuration
frameSystem, err := robot.FrameSystemConfig(context.Background(), nil)
fmt.Println(frameSystem)

Parameters:

transforms (Transform[]): An optional array of additional transforms.

Returns:

(FrameSystemConfig[]): An array of individual parts that make up a robot’s frame system.

For more information, see the TypeScript SDK Docs.

// Get the frame system configuration.
console.log("FrameSytemConfig:", await robot.frameSystemConfig());

Status

Get the status of the resources on the robot. You can provide a list of ResourceNames for which you want statuses. If no names are passed in, the status of every resource configured on the robot is returned.

Parameters:

resourceNames (Optional[List[viam.proto.common.ResourceName]]): An optional list of ResourceNames for components you want the status of. If no names are passed in, all resource statuses are returned.

Returns:

(List[str]): A list containing the status of each resource.

For more information, see the Python SDK Docs.

# Get the status of the resources on the robot.
statuses = await robot.get_status()

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
resourceNames ([]resource.Name): An optional list of ResourceNames for components you want the status of. If no names are passed in, all resource statuses are returned.

Returns:

([]Status): Status of each resource.
(error): An error, if one occurred.

For more information, see the Go SDK Docs.

// Get the status of the resources on the robot.
status, err = robot.Status(ctx.Background())

Parameters:

resourceNames (commonApi.ResourceName[]): An optional array of ResourceNames for components you want the status of. If no names are passed in, all resource statuses are returned.

Returns:

(robotApi.Status[]): An array containing the status of each resource.

For more information, see the TypeScript SDK Docs.

// Get the status of the resources on the robot.
const status = await robot.getStatus();

Close

Close the underlying connections and stop any periodic tasks across all constituent parts of the robot.

Parameters:

None

Returns:

None

For more information, see the Python SDK Docs.

# Cleanly close the underlying connections and stop any periodic tasks.
await robot.close()

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

(error): An error, if one occurred.

For more information, see the Go SDK Docs.

// Cleanly close the underlying connections and stop any periodic tasks,
err := robot.Close(ctx.Background())

Parameters:

None

Returns:

None

For more information, see the TypeScript SDK Docs.

// Cleanly close the underlying connections and stop any periodic tasks
await robot.disconnect();

StopAll

Cancel all current and outstanding operations for the robot and stop all actuators and movement.

Parameters:

extra (Dict[viam.proto.common.ResourceName, Dict[str, Any]]): Any extra parameters to pass to the resources’ stop methods, keyed on each resource’s ResourceName.

Returns:

None

For more information, see the Python SDK Docs.

# Cancel all current and outstanding operations for the robot and stop all
# actuators and movement.
await robot.stop_all()

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
extra (map[resource.Name]map[string]interface{}): Any extra parameters to pass to the resources’ stop methods, keyed on each resource’s Name.

Returns:

(error): An error, if one occurred.

For more information, see the Go SDK Docs.

// Cancel all current and outstanding operations for the robot and stop all actuators and movement.
err := robot.StopAll(ctx.Background())

Parameters:

None

Returns:

None

For more information, see the TypeScript SDK Docs.

// Cancel all current and outstanding operations for the robot and stop all actuators and movement.
await robot.stopAll();

ResourceNames

Get a list of all known resource names connected to this robot.

Parameters:

None

Returns:

(List[viam.proto.common.ResourceName]): List of all known resource names. A property of a RobotClient

resource_names = robot.resource_names

Parameters:

None

Returns:

([]resource.Name): List of all known resource names.

resource_names := robot.ResourceNames()

For more information, see the Go SDK Docs.

Parameters:

None

Returns:

(ResourceName.AsObject[]): List of all known resource names.

// Get a list of all resources on the robot.
const resource_names = await robot.resourceNames();

For more information, see the Typescript SDK Docs.

Have questions, or want to meet other people working on robots? Join our Community Discord.

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!