viam.robot.client

Module Contents

Classes

RobotClient

gRPC client for a Robot. This class should be used for all interactions with a robot.

Attributes

LOGGER

viam.robot.client.LOGGER

class viam.robot.client.RobotClient

gRPC client for a Robot. This class should be used for all interactions with a robot.

There are 2 ways to instantiate a robot client:

RobotClient.at_address(...)
RobotClient.with_channel(...)

You can use the client standalone or within a context:

robot = await RobotClient.at_address(...)
async with await RobotClient.with_channel(...) as robot: ...

You must close() the robot to release resources.

Note: Robots used within a context are automatically closed UNLESS created with a channel. Robots created using with_channel are not automatically closed.

class Options

refresh_interval: int = 0

How often to refresh the status/parts of the robot in seconds. If not set, the robot will not be refreshed automatically

dial_options: Optional[viam.rpc.dial.DialOptions]

Options used to connect clients to gRPC servers

log_level: int

The log level to output

check_connection_interval: int = 10

The frequency (in seconds) at which to check if the robot is still connected. 0 (zero) signifies no connection checks

attempt_reconnect_interval: int = 1

The frequency (in seconds) at which to attempt to reconnect a disconnected robot. 0 (zero) signifies no reconnection attempts

disable_sessions: bool = False

Whether sessions are disabled

property resource_names: List[viam.proto.common.ResourceName]

Get a list of all resource names

Returns:

The list of resource names

Return type:

List[viam.proto.common.ResourceName]

async classmethod at_address(address: str, options: Options) → typing_extensions.Self

Create a robot client that is connected to the robot at the provided address.

Parameters:

• address (str) – Address of the robot (IP address, URL, etc.)

• options (Options) – Options for connecting and refreshing

Returns:

the RobotClient

Return type:

Self

async classmethod with_channel(channel: Union[grpclib.client.Channel, viam.rpc.dial.ViamChannel], options: Options) → typing_extensions.Self

Create a robot that is connected to a robot over the given channel.

Any robots created using this method will NOT automatically close the channel upon exit.

Parameters:

• channel (ViamChannel) – The channel that is connected to a robot, obtained by viam.rpc.dial

• options (Options) – Options for refreshing. Any connection options will be ignored.

Returns:

the RobotClient

Return type:

Self

async refresh()

Manually refresh the underlying parts of this robot

get_component(name: viam.proto.common.ResourceName) → viam.components.component_base.ComponentBase

Get a component using its ResourceName.

This function should not be called directly except in specific cases. The method Component.from_robot(...) is the preferred method for obtaining components.

arm = Arm.from_robot(robot=robot, name="my_arm")

Because this function returns a generic ComponentBase rather than the specific component type, it will be necessary to cast the returned component to the desired component. This can be done using a few different methods:

• Assertion:

  arm = robot.get_component(Arm.get_resource_name("my_arm"))
  assert isinstance(arm, Arm)
  end_pos = await arm.get_end_position()
  

• Explicit cast:

  from typing import cast
  arm = robot.get_component(Arm.get_resource_name("my_arm"))
  arm = cast(Arm, arm)
  end_pos = await arm.get_end_position()
  

• Declare type on variable assignment.

  • Note: If using an IDE, a type error may be shown which can be ignored.

  arm: Arm = robot.get_component(Arm.get_resource_name("my_arm"))  # type: ignore
  end_pos = await arm.get_end_position()
  

Parameters:

name (viam.proto.common.ResourceName) – The component’s ResourceName

Raises:

• ValueError – Raised if the requested resource is not a component

• ComponentNotFoundError – Error if component with the given type and name does not exist in the registry

Returns:

The component

Return type:

ComponentBase

get_service(name: viam.proto.common.ResourceName) → viam.services.service_base.ServiceBase

Get a service using its ResourceName

This function should not be called directly except in specific cases. The method Service.from_robot(...) is the preferred method for obtaining services.

service = MyService.from_robot(robot=robot, name="my_service")

Because this function returns a generic ServiceBase rather than a specific service type, it will be necessary to cast the returned service to the desired service. This can be done using a few methods:

• Assertion:

  service = robot.get_service(MyService.get_resource_name("my_service"))
  assert isinstance(service, MyService)
  

• Explicit cast:

  from typing import cast
  service = robot.get_service(MyService.get_resource_name("my_service"))
  service = cast(MyService, my_service)
  

• Declare type on variable assignment

  • Note: If using an IDE, a type error may be shown which can be ignored.

  service: MyService = robot.get_service(MyService.get_resource_name("my_service"))  # type: ignore
  

Parameters:

name (viam.proto.common.ResourceName) – The service’s ResourceName

Raises:

• ValueError – Raised if the requested resource is not a component

• ComponentNotFoundError – Error if component with the given type and name does not exist in the registry

Returns:

The service

Return type:

ServiceBase

async close()

Cleanly close the underlying connections and stop any periodic tasks

async __aenter__()

async __aexit__(exc_type, exc_value, traceback)

async get_status(components: Optional[List[viam.proto.common.ResourceName]] = None)

Get the status of the robot’s components. You can optionally provide a list of ResourceName for which you want statuses.

Parameters:

components (Optional[List[viam.proto.common.ResourceName]]) – Optional list of ResourceName for components you want statuses.

async get_operations() → List[viam.proto.robot.Operation]

Get the list of operations currently running on the robot.

Returns:

The list of operations currently running on a given robot.

Return type:

List[viam.proto.robot.Operation]

async cancel_operation(id: str)

Cancels the specified operation on the robot.

Parameters:

id (str) – ID of operation to kill.

async block_for_operation(id: str)

Blocks on the specified operation on the robot. This function will only return when the specific operation has finished or has been cancelled.

Parameters:

id (str) – ID of operation to block on.

async get_frame_system_config(additional_transforms: Optional[List[viam.proto.common.Transform]] = None) → List[viam.proto.robot.FrameSystemConfig]

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

Returns:

The configuration of a given robot’s frame system.

Return type:

List[viam.proto.robot.FrameSystemConfig]

async transform_pose(query: viam.proto.common.PoseInFrame, destination: str, additional_transforms: Optional[List[viam.proto.common.Transform]] = None) → viam.proto.common.PoseInFrame

Transform a given source Pose from the reference frame to a new specified destination which is a reference frame.

Parameters:

• query (viam.proto.common.PoseInFrame) – The pose that should be transformed.

• destination (str) – The name of the reference frame to transform the given pose to.

abstract async transform_point_cloud()

async discover_components(queries: List[viam.proto.robot.DiscoveryQuery]) → List[viam.proto.robot.Discovery]

Get the list of discovered component configurations.

Parameters:

queries (List[viam.proto.robot.DiscoveryQuery]) – The list of component models to lookup configurations for.

async stop_all(extra: Dict[viam.proto.common.ResourceName, Dict[str, Any]] = {})

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 the resource’s ResourceName