# Manage machines with Viam's machine management API

The _machine API_ allows you to connect to your machine from within a supported [Viam SDK](https://docs.viam.com/reference/apis/), retrieve status information, and send commands remotely.

The machine API is supported for use with the [Viam Python SDK](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient), the [Viam Go SDK](https://pkg.go.dev/go.viam.com/rdk/robot/client#RobotClient), and the [Viam C++ SDK](https://cpp.viam.dev/classviam_1_1sdk_1_1RobotClient.html).

The machine API supports the following methods:

| Method Name | Description |
| --- | --- |
| [`GetOperations`](https://docs.viam.com/reference/apis/robot/#getoperations) | Get the list of operations currently running on the machine. |
| [`GetMachineStatus`](https://docs.viam.com/reference/apis/robot/#getmachinestatus) | Get status information about the machine including the status of the machine and its resources and the revision of the machine config. |
| [`GetSessions`](https://docs.viam.com/reference/apis/robot/#getsessions) | Get the list of sessions currently connected to the robot. |
| [`ResourceNames`](https://docs.viam.com/reference/apis/robot/#resourcenames) | Get a list of all known resource names connected to this machine. |
| [`ResourceRPCSubtypes`](https://docs.viam.com/reference/apis/robot/#resourcerpcsubtypes) | Get a list of all resource types. |
| [`CancelOperation`](https://docs.viam.com/reference/apis/robot/#canceloperation) | Cancel the specified operation on the machine. |
| [`BlockForOperation`](https://docs.viam.com/reference/apis/robot/#blockforoperation) | Blocks on the specified operation on the machine. |
| [`FrameSystemConfig`](https://docs.viam.com/reference/apis/robot/#framesystemconfig) | Get the configuration of the frame system of a given machine. |
| [`TransformPose`](https://docs.viam.com/reference/apis/robot/#transformpose) | Transform a given source Pose from the original reference frame to a new destination reference frame. |
| [`TransformPCD`](https://docs.viam.com/reference/apis/robot/#transformpcd) | Transforms the pointcloud to the desired frame in the robot’s frame system. |
| [`GetModelsFromModules`](https://docs.viam.com/reference/apis/robot/#getmodelsfrommodules) | Get a list of all models provided by local and registry modules on the machine. |
| [`StopAll`](https://docs.viam.com/reference/apis/robot/#stopall) | Cancel all current and outstanding operations for the machine and stop all actuators and movement. |
| [`RestartModule`](https://docs.viam.com/reference/apis/robot/#restartmodule) | Reload a module as if its config changed. |
| [`Log`](https://docs.viam.com/reference/apis/robot/#log) | Create a LogEntry object from the log to send to the RDK over gRPC. |
| [`GetCloudMetadata`](https://docs.viam.com/reference/apis/robot/#getcloudmetadata) | Get app-related information about the robot. |
| [`GetVersion`](https://docs.viam.com/reference/apis/robot/#getversion) | Return version information about the machine. |
| [`Options.with_api_key`](https://docs.viam.com/reference/apis/robot/#optionswith_api_key) | Create a `RobotClient.Options` using an API key as credentials. |
| [`AtAddress`](https://docs.viam.com/reference/apis/robot/#ataddress) | Create a RobotClient that is connected to the machine at the provided address. |
| [`WithChannel`](https://docs.viam.com/reference/apis/robot/#withchannel) | Create a RobotClient that is connected to a machine over the given channel. |
| [`Refresh`](https://docs.viam.com/reference/apis/robot/#refresh) | Manually refresh the underlying parts of this machine. |
| [`Shutdown`](https://docs.viam.com/reference/apis/robot/#shutdown) | Shutdown shuts down the machine. |
| [`Close`](https://docs.viam.com/reference/apis/robot/#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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-1-0)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-1-1)

**Parameters:**

- None.

**Returns:**

- ( [List[viam.proto.robot.Operation]](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.Operation)): : The list of operations currently running on a given machine.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.get_operations).

### GetMachineStatus

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

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-2-0)
- [Go](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-2-1)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-2-2)
- [Flutter](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-2-3)

**Parameters:**

- None.

**Returns:**

- ( [viam.proto.robot.GetMachineStatusResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-3-0)

**Parameters:**

- None.

**Returns:**

- (Promise< [Session](https://ts.viam.dev/classes/robotApi.Session.html)[]>)

### ResourceNames

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

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-4-0)
- [Go](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-4-1)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-4-2)

**Parameters:**

- None.

**Returns:**

- None.

### ResourceRPCSubtypes

Get a list of all resource types.

- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-5-0)

**Parameters:**

- None.

**Returns:**

- (Promise< [ResourceRPCSubtype](https://ts.viam.dev/classes/robotApi.ResourceRPCSubtype.html)[]>)

### CancelOperation

Cancel the specified operation on the machine.

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-6-0)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-6-1)

**Parameters:**

- `id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-7-0)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-7-1)

**Parameters:**

- `id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): ID of operation to block on.

**Returns:**

- None.

### FrameSystemConfig

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

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-8-0)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-8-1)

**Parameters:**

- `additional_transforms` ( [List[viam.proto.common.Transform]](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Transform)) (optional): Any additional transforms.

**Returns:**

- ( [List[viam.proto.robot.FrameSystemConfig]](https://python.viam.dev/autoapi/viam/proto/robot/index.html#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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-9-0)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-9-1)

**Parameters:**

- `query` ( [viam.proto.common.PoseInFrame](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.PoseInFrame)) (required): The pose that should be transformed.
- `destination` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the reference frame to transform the given pose to.
- `additional_transforms` ( [List[viam.proto.common.Transform]](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Transform)) (optional): Any additional transforms.

**Returns:**

- ( [viam.proto.common.PoseInFrame](https://python.viam.dev/autoapi/viam/proto/common/index.html#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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-10-0)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-10-1)

**Parameters:**

- `point_cloud_pcd` ( [bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)) (required): The point cloud data to transform, in PCD format.
- `source` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The reference frame of the point cloud.
- `destination` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The reference frame to transform the point cloud into.

**Returns:**

- ( [bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)): 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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-11-0)
- [Go](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-11-1)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-11-2)
- [Flutter](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-11-3)

**Parameters:**

- None.

**Returns:**

- ( [List[viam.proto.robot.ModuleModel]](https://python.viam.dev/autoapi/viam/proto/robot/index.html#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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-12-0)
- [Go](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-12-1)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-12-2)

**Parameters:**

- `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (required): Extra options to pass to the underlying RPC call.

**Returns:**

- None.

### RestartModule

Reload a module as if its config changed.

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-13-0)
- [Go](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-13-1)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-13-2)

**Parameters:**

- `id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (optional): The id matching the module_id field of the registry module in your part configuration.
- `name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-14-0)

**Parameters:**

- `name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The logger’s name.
- `level` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The level of the log.
- `time` ( [datetime.datetime](https://docs.python.org/3/library/datetime.html)) (required): The log creation time.
- `message` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The log message.
- `stack` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The stack information of the log.

**Returns:**

- None.

### GetCloudMetadata

Get app-related information about the robot.

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-15-0)
- [Go](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-15-1)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-15-2)
- [Flutter](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-15-3)

**Parameters:**

- None.

**Returns:**

- ( [viam.proto.robot.GetCloudMetadataResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#viam.proto.robot.GetCloudMetadataResponse)): : App-related metadata.

### GetVersion

Return version information about the machine.

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-16-0)
- [Go](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-16-1)
- [TypeScript](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-16-2)

**Parameters:**

- None.

**Returns:**

- ( [viam.proto.robot.GetVersionResponse](https://python.viam.dev/autoapi/viam/proto/robot/index.html#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`](https://docs.viam.com/reference/apis/robot/#ataddress).

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-17-0)

**Parameters:**

- `api_key` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): your API key.
- `api_key_id` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-18-0)
- [Flutter](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-18-1)

**Parameters:**

- `address` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): Address of the machine (IP address, URL, etc.).
- `options` ( [Options](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-19-0)

**Parameters:**

- `channel` ( [grpclib.client.Channel | viam.rpc.dial.ViamChannel](https://python.viam.dev/autoapi/viam/rpc/dial/index.html#viam.rpc.dial.ViamChannel)) (required): The channel that is connected to a machine, obtained by viam.rpc.dial.
- `options` ( [Options](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.Options)) (required): Options for refreshing. Any connection options will be ignored.

**Returns:**

- (Self)

### Refresh

Manually refresh the underlying parts of this machine.

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-20-0)
- [Flutter](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-20-1)

**Parameters:**

- None.

**Returns:**

- None.

### Shutdown

Shutdown shuts down the machine.

- [Python](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-21-0)
- [Go](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-21-1)

**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](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-22-0)
- [Go](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-22-1)
- [Flutter](https://docs.viam.com/reference/apis/robot/#tabset-referenceapisrobot-22-2)

**Parameters:**

- None.

**Returns:**

- None.