# Arm API

The arm API allows you to give commands to your [arm components](https://docs.viam.com/hardware/common-components/add-an-arm/) for linear motion planning with self-collision prevention.
If you want the arm to avoid obstacles, or you want to plan complex motion in an automated way, use the [motion API](https://docs.viam.com/reference/apis/services/motion/).

The arm component supports the following methods:

| Method Name | Description |
| --- | --- |
| [`GetEndPosition`](https://docs.viam.com/reference/apis/components/arm/#getendposition) | Get the current position of the arm as a pose. |
| [`MoveToPosition`](https://docs.viam.com/reference/apis/components/arm/#movetoposition) | Move the end of the arm in a straight line to the desired pose, relative to the base of the arm. |
| [`MoveToJointPositions`](https://docs.viam.com/reference/apis/components/arm/#movetojointpositions) | Move each joint on the arm to the position specified in `positions`. |
| [`MoveThroughJointPositions`](https://docs.viam.com/reference/apis/components/arm/#movethroughjointpositions) | Move the arm’s joints through the given positions in the order they are specified. |
| [`GetJointPositions`](https://docs.viam.com/reference/apis/components/arm/#getjointpositions) | Get the current position of each joint on the arm. |
| [`Get3DModels`](https://docs.viam.com/reference/apis/components/arm/#get3dmodels) | Get the 3D models of the arm. |
| [`GetKinematics`](https://docs.viam.com/reference/apis/components/arm/#getkinematics) | Get the kinematics information associated with the arm as the format and byte contents of the kinematics file. |
| [`IsMoving`](https://docs.viam.com/reference/apis/components/arm/#ismoving) | Get if the arm is currently moving. |
| [`Stop`](https://docs.viam.com/reference/apis/components/arm/#stop) | Stop all motion of the arm. |
| [`GetGeometries`](https://docs.viam.com/reference/apis/components/arm/#getgeometries) | Get all the geometries associated with the arm in its current configuration, in the frame of the arm. |
| [`Reconfigure`](https://docs.viam.com/reference/apis/components/arm/#reconfigure) | Reconfigure this resource. |
| [`DoCommand`](https://docs.viam.com/reference/apis/components/arm/#docommand) | Execute model-specific commands that are not otherwise defined by the component API. |
| [`GetResourceName`](https://docs.viam.com/reference/apis/components/arm/#getresourcename) | Get the `ResourceName` for this arm. |
| [`Close`](https://docs.viam.com/reference/apis/components/arm/#close) | Safely shut down the resource and prevent further use. |

## API

### GetEndPosition

Get the current position of the arm as a [pose](https://docs.viam.com/motion-planning/reference/orientation-vectors/).

**Parameters:**

- `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**

- ( [viam.components.arm.Pose](https://python.viam.dev/autoapi/viam/components/arm/index.html#viam.components.arm.Pose)): : A representation of the arm’s current position as a 6 DOF (six degrees of freedom) pose. The `Pose` is composed of values for location and orientation with respect to the origin. Location is expressed as distance, which is represented by x, y, and z coordinate values. Orientation is expressed as an orientation vector, which is represented by o_x, o_y, o_z, and theta values.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.get_end_position).

### MoveToPosition

Move the end of the arm in a straight line to the desired [pose](https://docs.viam.com/motion-planning/reference/orientation-vectors/), relative to the base of the arm.

All arms have a `Home` position, which corresponds to setting all joint angles to 0.

**Parameters:**

- `pose` ( [viam.components.arm.Pose](https://python.viam.dev/autoapi/viam/components/arm/index.html#viam.components.arm.Pose)) (required): The destination Pose for the arm. The Pose is composed of values for location and orientation with respect to the origin. Location is expressed as distance, which is represented by x, y, and z coordinate values. Orientation is expressed as an orientation vector, which is represented by o_x, o_y, o_z, and theta values.
- `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**
- None.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.move_to_position).

### MoveToJointPositions

Move each joint on the arm to the position specified in `positions`.

#### Caution
Collision checks are not enabled when doing direct joint control with MoveToJointPositions().

**Parameters:**

- `positions` ( [viam.proto.component.arm.JointPositions](https://python.viam.dev/autoapi/viam/components/arm/index.html#viam.components.arm.JointPositions)) (required): The destination JointPositions for the arm.
- `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**
- None.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.move_to_joint_positions).

### MoveThroughJointPositions

Move the arm’s joints through the given positions in the order they are specified. This will block until done or a new operation cancels this one.

**Parameters:**
- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `positions` [([][]referenceframe.Input)](https://pkg.go.dev/go.viam.com/rdk/referenceframe#Input)
- `options` [(*MoveOptions)](https://pkg.go.dev/go.viam.com/rdk/components/arm#MoveOptions)
- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call.
**Returns:**
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.
**Example:**
```go

```
For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/arm#Arm).

### GetJointPositions

Get the current position of each joint on the arm.

**Parameters:**
- `extra` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**
- ( [viam.proto.component.arm.JointPositions](https://python.viam.dev/autoapi/viam/proto/component/arm/index.html#viam.proto.component.arm.JointPositions)): : The current `JointPositions` for the arm.`JointPositions` can have one attribute, `values`, a list of joint positions with rotational values (degrees) and translational values (mm).

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.get_joint_positions).

### Get3DModels

Get the 3D models of the arm.

**Parameters:**
- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call.

**Returns:**
- [(map[string]*commonpb.Mesh)](https://pkg.go.dev/go.viam.com/api/common/v1#Mesh)
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/arm#Arm).

### GetKinematics

Get the kinematics information associated with the arm as the format and byte contents of the [kinematics file](https://docs.viam.com/motion-planning/frame-system/overview/).

**Returns:**
- ( [viam.components.KinematicsReturn](https://python.viam.dev/autoapi/viam/components/index.html#viam.components.KinematicsReturn)): : A tuple containing two values; the first [0] value represents the format of the file, either in URDF format (`KinematicsFileFormat.KINEMATICS_FILE_FORMAT_URDF`) or Viam’s kinematic parameter format (spatial vector algebra) (`KinematicsFileFormat.KINEMATICS_FILE_FORMAT_SVA`), and the second [1] value represents the byte contents of the file.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.get_kinematics).

### IsMoving

Get if the arm is currently moving.

**Parameters:**
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**
- ( [bool](https://docs.python.org/3/library/stdtypes.html#boolean-type-bool)): : Whether the arm is moving.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.is_moving).

### Stop

Stop all motion of the arm.

**Returns:**
- None.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.stop).

### GetGeometries

Get all the geometries associated with the arm in its current configuration, in the [frame](https://docs.viam.com/reference/services/frame-system/) of the arm. The [motion](https://docs.viam.com/reference/services/motion/) and [navigation](https://docs.viam.com/reference/services/navigation/) services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning.

**Returns:**
- ( [List[viam.proto.common.Geometry]](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Geometry)): : The geometries associated with the Component.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.get_geometries).

### Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

**Parameters:**
- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `deps` [(Dependencies)](https://pkg.go.dev/go.viam.com/rdk/resource#Dependencies): The resource dependencies.
- `conf` [(Config)](https://pkg.go.dev/go.viam.com/rdk/resource#Config): The resource configuration.

**Returns:**
- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).

### DoCommand

Execute model-specific commands that are not otherwise defined by the component API. Most models do not implement `DoCommand`. Any available model-specific commands should be covered in the model’s documentation. If you are implementing your own arm and want to add features that have no corresponding built-in API method, you can implement them with [`DoCommand`](https://docs.viam.com/reference/sdks/docommand/).

**Parameters:**
- `command` (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), ValueTypes]) (required): The command to execute.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**
- (Mapping[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), viam.utils.ValueTypes]): : Result of the executed command.

**Raises:**
- (NotImplementedError): Raised if the Resource does not support arbitrary commands.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.do_command).

### GetResourceName

Get the `ResourceName` for this arm.

**Parameters:**
- `name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the Resource.

**Returns:**
- ( [viam.proto.common.ResourceName](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName)): : The ResourceName of this Resource.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.get_resource_name).

### Close

Safely shut down the resource and prevent further use.

**Parameters:**
- None.

**Returns:**
- None.

**Example:**
```python

```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/arm/client/index.html#viam.components.arm.client.ArmClient.close).