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[source]

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[source]
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

classmethod with_api_key(api_key: str, api_key_id: str) → typing_extensions.Self[source]

Create RobotClient.Options with an API key for credentials and default values for other arguments.

Parameters:

  • api_key (str) – your API key

  • api_key_id (str) – your API key ID. Must be a valid UUID

Raises:

ValueError – Raised if the api_key_id is not a valid UUID

Returns:

the RobotClient.Options

Return type:

Self

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[source]

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[source]

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()[source]

Manually refresh the underlying parts of this robot

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

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[source]

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()[source]

Cleanly close the underlying connections and stop any periodic tasks

async __aenter__()[source]
async __aexit__(exc_type, exc_value, traceback)[source]
async get_status(components: Optional[List[viam.proto.common.ResourceName]] = None)[source]

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][source]

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)[source]

Cancels the specified operation on the robot.

Parameters:

id (str) – ID of operation to kill.

async block_for_operation(id: str)[source]

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][source]

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[source]

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()[source]
async discover_components(queries: List[viam.proto.robot.DiscoveryQuery]) → List[viam.proto.robot.Discovery][source]

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]] = {})[source]

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