Edit

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:

Method Name	Description
`GetOperations`	Get the list of operations currently running on the machine.
`GetMachineStatus`	Get status information about the machine including the status of the machine and its resources and the revision of the machine config.
`GetSessions`	Get the list of sessions currently connected to the robot.
`ResourceNames`	Get a list of all known resource names connected to this machine.
`ResourceRPCSubtypes`	Get a list of all resource types.
`CancelOperation`	Cancel the specified operation on the machine.
`BlockForOperation`	Blocks on the specified operation on the machine.
`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.
`GetModelsFromModules`	Get a list of all models provided by local and registry modules 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.

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:

operations = await machine.get_operations()

For more information, see the Python SDK Docs.

Parameters:

None.

Returns:

(Promise<Operation[]>)

Example:

const operations = await machine.getOperations();

For more information, see the TypeScript 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.

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.

Example:

machine_status = await machine.get_machine_status()
machine_state = machine_status.state
resource_statuses = machine_status.resources
cloud_metadata = machine_status.resources[0].cloud_metadata
config_status = machine_status.config

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:

(MachineStatus)
(error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

(Promise<GetMachineStatusResponse>)

Example:

const machineStatus = await machine.getMachineStatus();

For more information, see the TypeScript SDK Docs.

Parameters:

None.

Returns:

Future<GetMachineStatusResponse>

Example:

var machineStatus = await machine.getMachineStatus();

For more information, see the Flutter SDK Docs.

GetSessions

Get the list of sessions currently connected to the robot.

TypeScript

Parameters:

None.

Returns:

(Promise<Session[]>)

Example:

const sessions = await machine.getSessions();

For more information, see the TypeScript SDK Docs.

ResourceNames

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

Parameters:

None.

Returns:

None.

Example:

resource_names = machine.resource_names

For more information, see the Python SDK Docs.

Parameters:

None.

Returns:

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

Example:

resource_names := machine.ResourceNames()

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

(Promise<commonApi.ResourceName[]>)

Example:

const resourceNames = await machine.resourceNames();

For more information, see the TypeScript SDK Docs.

ResourceRPCSubtypes

Get a list of all resource types.

TypeScript

Parameters:

None.

Returns:

(Promise<ResourceRPCSubtype[]>)

Example:

const resourceRPCSubtypes = await machine.resourceRPCSubtypes();

For more information, see the TypeScript SDK Docs.

CancelOperation

Cancel the specified operation on the machine.

Python
TypeScript

Parameters:

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

Returns:

None.

Example:

await machine.cancel_operation("INSERT OPERATION ID")

For more information, see the Python SDK Docs.

Parameters:

id (string) (required): ID of operation to kill.

Returns:

(Promise)

Example:

await machine.cancelOperation('INSERT OPERATION ID');

For more information, see the TypeScript SDK Docs.

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.

Example:

await machine.block_for_operation("INSERT OPERATION ID")

For more information, see the Python SDK Docs.

Parameters:

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

Returns:

(Promise)

Example:

await machine.blockForOperation('INSERT OPERATION ID');

For more information, see the TypeScript SDK Docs.

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.

Example:

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

For more information, see the Python SDK Docs.

Parameters:

transforms (commonApi) (required)

Returns:

(Promise<FrameSystemConfig[]>)

Example:

const frameSystemConfig = await machine.frameSystemConfig();

For more information, see the TypeScript SDK Docs.

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.

Example:

from viam.proto.common import Pose, PoseInFrame

pose = Pose(
    x=1.0,    # X coordinate in mm
    y=2.0,    # Y coordinate in mm
    z=3.0,    # Z coordinate in mm
    o_x=0.0,  # X component of orientation vector
    o_y=0.0,  # Y component of orientation vector
    o_z=0.0,  # Z component of orientation vector
    theta=0.0 # Orientation angle in degrees
)

pose_in_frame = PoseInFrame(
    reference_frame="world",
    pose=pose
)

transformed_pose = await machine.transform_pose(pose_in_frame, "world")

For more information, see the Python SDK Docs.

Parameters:

source (commonApi) (required)
destination (string) (required): The name of the reference frame to transform the given.
supplementalTransforms (commonApi) (required): Pose information on any additional reference frames that are needed to perform the transform.

Returns:

(Promise<commonApi.PoseInFrame>)

For more information, see the TypeScript SDK Docs.

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.

TypeScript

Parameters:

pointCloudPCD (Uint8Array) (required): The point clouds to transform. This should be in the PCD format encoded into bytes.
source (string) (required): The reference frame of the point cloud.
destination (string) (required): The reference frame into which the source data should be transformed, if unset this defaults to the “world” reference frame. Do not move the robot between the generation of the initial pointcloud and the receipt of the transformed pointcloud because that will make the transformations inaccurate.

Returns:

(Promise)

For more information, see the TypeScript SDK Docs.

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.

Parameters:

None.

Returns:

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

Example:

# Get module models
module_models = await machine.get_models_from_modules(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.

Returns:

([]resource.ModuleModel)
(error): An error, if one occurred.

Example:

//Get a list of models found in configured modules.
models, err := machine.GetModelsFromModules(ctx)

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

(Promise<ModuleModel[]>)

Example:

const models = await machine.getModelsFromModules();

For more information, see the TypeScript SDK Docs.

Parameters:

None.

Returns:

Future<List<ModuleModel>>

Example:

var modelsFromModules = await machine.getModelsFromModules();

For more information, see the Flutter SDK Docs.

StopAll

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

Parameters:

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

Returns:

None.

Example:

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

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.
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(error): An error, if one occurred.

Example:

// Cancel all current and outstanding operations for the machine and stop all actuators and movement.
err := machine.StopAll(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

(Promise)

Example:

await machine.stopAll();

For more information, see the TypeScript SDK Docs.

RestartModule

Reload a module as if its config changed.

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.

Returns:

None.

Raises:

(GRPCError): If a module can’t be found matching the provided ID or name.

Example:

await machine.restart_module(id="namespace:module:model", name="my_model")

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.
req (RestartModuleRequest)

Returns:

(error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

(Promise)

Example:

await machine.restartModule('namespace:module:model', 'my_model_name');

For more information, see the TypeScript SDK Docs.

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.

For more information, see the Python SDK Docs.

GetCloudMetadata

Get app-related information about the robot.

Parameters:

None.

Returns:

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

Example:

metadata = await machine.get_cloud_metadata()
print(metadata.machine_id)
print(metadata.machine_part_id)
print(metadata.primary_org_id)
print(metadata.location_id)

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:

(cloud.Metadata): App-related metadata containing the primary organization ID, location ID, and robot part ID for a machine running on Viam.
(error): An error, if one occurred.

Example:

metadata, err := machine.CloudMetadata(context.Background())
primary_org_id := metadata.PrimaryOrgID
location_id := metadata.LocationID
machine_id := metadata.MachineID
machine_part_id := metadata.MachinePartID

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

(Promise<GetCloudMetadataResponse>)

Example:

const cloudMetadata = await machine.getCloudMetadata();

For more information, see the TypeScript SDK Docs.

Parameters:

None.

Returns:

Future<CloudMetadata>

Example:

var metadata = await machine.getCloudMetadata();

For more information, see the Flutter SDK Docs.

GetVersion

Return version information about the machine.

Parameters:

None.

Returns:

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

Example:

result = await machine.get_version()
print(result.platform)
print(result.version)
print(result.api_version)

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:

(VersionResponse)
(error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

(Promise<GetVersionResponse>)

For more information, see the TypeScript SDK Docs.

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.

Example:

# Replace "<API-KEY>" (including brackets) with your machine's API key
api_key = '<API-KEY>'
# Replace "<API-KEY-ID>" (including brackets) with your machine's API key ID
api_key_id = '<API-KEY-ID>'

opts = RobotClient.Options.with_api_key(api_key, api_key_id)

machine = await RobotClient.at_address('<ADDRESS-FROM-THE-VIAM-APP>', opts)

For more information, see the Python SDK Docs.

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)

Example:

async def connect():

    opts = RobotClient.Options.with_api_key(
        # Replace "<API-KEY>" (including brackets) with your machine's API key
        api_key='<API-KEY>',
        # Replace "<API-KEY-ID>" (including brackets) with your machine's API key ID
        api_key_id='<API-KEY-ID>'
    )
    return await RobotClient.at_address('MACHINE ADDRESS', opts)


async def main():
    # Make a RobotClient
    machine = await connect()

For more information, see the Python SDK Docs.

Parameters:

url String (required)
options RobotClientOptions (required)

Returns:

Future<RobotClient>

Example:

// Example usage; see your machine's CONNECT tab for your machine's address and API key.

Future<void> connectToViam() async {
  const host = '<YOUR ROBOT ADDRESS>.viam.cloud';
  // Replace "<API-KEY-ID>" (including brackets) with your machine's API key ID
  const apiKeyID = '<API-KEY-ID>';
  // Replace "<API-KEY>" (including brackets) with your machine's API key
  const apiKey = '<API-KEY>';

  final machine = await RobotClient.atAddress(
    host,
    RobotClientOptions.withApiKey(apiKeyID, apiKey),
  );
}

For more information, see the Flutter SDK Docs.

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)

Example:

from viam.robot.client import RobotClient
from viam.rpc.dial import DialOptions, dial


async def connect_with_channel() -> RobotClient:
    async with await dial('ADDRESS', DialOptions()) as channel:
        return await RobotClient.with_channel(channel, RobotClient.Options())

machine = await connect_with_channel()

For more information, see the Python SDK Docs.

Refresh

Manually refresh the underlying parts of this machine.

Python
Flutter

Parameters:

None.

Returns:

None.

Example:

await machine.refresh()

For more information, see the Python SDK Docs.

Parameters:

None.

Returns:

Future

Example:

await machine.refresh();

For more information, see the Flutter SDK Docs.

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.

Example:

await machine.shutdown()

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.

Example:

// Shut down the robot.
err := machine.Shutdown(context.Background())

For more information, see the Go SDK Docs.

Close

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

Parameters:

None.

Returns:

None.

Example:

await machine.close()

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.

Example:

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

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

Future

Example:

await machine.close();

For more information, see the Flutter 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!