Manage machines with Viam's machine management API

The machine API allows you to connect to your machine from within a supported Viam SDK, retrieve status information, and send commands remotely.

The machine API is supported for use with the Viam Python SDK, the Viam Go SDK, and the Viam C++ SDK.

The machine API supports the following methods:

Establish a connection

To use the machine management API, navigate to the CONNECT tab of one of your machines to get sample code.

API

GetOperations

Get the list of operations currently running on the machine.

• Python
• TypeScript

Parameters:

• None.

Returns:

• ( List[viam.proto.robot.Operation]): : The list of operations currently running on a given machine.

Example:

For more information, see the Python SDK Docs.

GetMachineStatus

Get status information about the machine including the status of the machine and its resources and the revision of the machine config.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• None.

Returns:

• ( viam.proto.robot.GetMachineStatusResponse): : current status of the machine (initializing or running), current status of the resources (List[ResourceStatus]) and the revision of the config of the machine.

GetSessions

Get the list of sessions currently connected to the robot.

• TypeScript

Parameters:

• None.

Returns:

• (Promise< Session[]>)

ResourceNames

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

• Python
• Go
• TypeScript

Parameters:

• None.

Returns:

• None.

ResourceRPCSubtypes

Get a list of all resource types.

• TypeScript

Parameters:

• None.

Returns:

• (Promise< ResourceRPCSubtype[]>)

CancelOperation

Cancel the specified operation on the machine.

• Python
• TypeScript

Parameters:

• id ( str) (required): ID of operation to cancel.

Returns:

• None.

BlockForOperation

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

• Python
• TypeScript

Parameters:

• id ( str) (required): ID of operation to block on.

Returns:

• None.

FrameSystemConfig

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

• Python
• TypeScript

Parameters:

• additional_transforms ( List[viam.proto.common.Transform]) (optional): Any additional transforms.

Returns:

• ( List[viam.proto.robot.FrameSystemConfig]): : The configuration of a given machine’s frame system.

TransformPose

Transform a given source Pose from the original reference frame to a new destination reference frame.

• Python
• TypeScript

Parameters:

• query ( viam.proto.common.PoseInFrame) (required): The pose that should be transformed.
• destination ( str) (required): The name of the reference frame to transform the given pose to.
• additional_transforms ( List[viam.proto.common.Transform]) (optional): Any additional transforms.

Returns:

• ( viam.proto.common.PoseInFrame): : The pose and the reference frame for the new destination.

TransformPCD

Transforms the pointcloud to the desired frame in the robot’s frame system. Do not move the robot between the generation of the initial pointcloud and the receipt of the transformed pointcloud, as doing so will make the transformations inaccurate.

• Python
• TypeScript

Parameters:

• point_cloud_pcd ( bytes) (required): The point cloud data to transform, in PCD format.
• source ( str) (required): The reference frame of the point cloud.
• destination ( str) (required): The reference frame to transform the point cloud into.

Returns:

• ( bytes): The point cloud data relative to the destination reference frame.

GetModelsFromModules

Get a list of all models provided by local and registry modules on the machine. This includes models that are not currently configured on the machine.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• None.

Returns:

• ( List[viam.proto.robot.ModuleModel]): : A list of discovered models.

StopAll

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

• Python
• Go
• TypeScript

Parameters:

• extra (Mapping[ str, Any]) (required): Extra options to pass to the underlying RPC call.

Returns:

• None.

RestartModule

Reload a module as if its config changed.

• Python
• Go
• TypeScript

Parameters:

• id ( str) (optional): The id matching the module_id field of the registry module in your part configuration.
• name ( str) (optional): The name matching the name field of the local/registry module in your part configuration.

Log

Create a LogEntry object from the log to send to the RDK over gRPC.

• Python

Parameters:

• name ( str) (required): The logger’s name.
• level ( str) (required): The level of the log.
• time ( datetime.datetime) (required): The log creation time.
• message ( str) (required): The log message.
• stack ( str) (required): The stack information of the log.

Returns:

• None.

GetCloudMetadata

Get app-related information about the robot.

• Python
• Go
• TypeScript
• Flutter

Parameters:

• None.

Returns:

• ( viam.proto.robot.GetCloudMetadataResponse): : App-related metadata.

GetVersion

Return version information about the machine.

• Python
• Go
• TypeScript

Parameters:

• None.

Returns:

• ( viam.proto.robot.GetVersionResponse): : Machine version related information.

Options.with_api_key

Create a RobotClient.Options using an API key as credentials. Pass these options to AtAddress.

• Python

Parameters:

• api_key ( str) (required): your API key.
• api_key_id ( str) (required): your API key ID. Must be a valid UUID.

Returns:

• (Self): : the RobotClient.Options.

Raises:

• (ValueError): Raised if the api_key_id is not a valid UUID.

AtAddress

Create a RobotClient that is connected to the machine at the provided address.

• Python
• Flutter

Parameters:

• address ( str) (required): Address of the machine (IP address, URL, etc.).
• options ( Options) (required): Options for connecting and refreshing.

Returns:

• (Self)

WithChannel

Create a RobotClient that is connected to a machine over the given channel. Any machines created using this method will NOT automatically close the channel upon exit.

• Python

Parameters:

• channel ( grpclib.client.Channel | viam.rpc.dial.ViamChannel) (required): The channel that is connected to a machine, obtained by viam.rpc.dial.
• options ( Options) (required): Options for refreshing. Any connection options will be ignored.

Returns:

• (Self)

Refresh

Manually refresh the underlying parts of this machine.

• Python
• Flutter

Parameters:

• None.

Returns:

• None.

Shutdown

Shutdown shuts down the machine.

• Python
• Go

Parameters:

• None.

Returns:

• None.

Raises:

• (GRPCError): Raised with DeadlineExceeded status if shutdown request times out, or if the machine server shuts down before having a chance to send a response. Raised with status Unavailable if server is unavailable, or if machine server is in the process of shutting down when response is ready.

Close

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

• Python
• Go
• Flutter

Parameters:

• None.

Returns:

• None.