Edit

Arm API

The arm API allows you to give commands to your arm components 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.

The arm component supports the following methods:

Method Name	Description
`GetEndPosition`	Get the current position of the arm as a pose.
`MoveToPosition`	Move the end of the arm in a straight line to the desired pose, relative to the base of the arm.
`MoveToJointPositions`	Move each joint on the arm to the position specified in `positions`.
`MoveThroughJointPositions`	Move the arm’s joints through the given positions in the order they are specified.
`GetJointPositions`	Get the current position of each joint on the arm.
`GetKinematics`	Get the kinematics information associated with the arm as the format and byte contents of the kinematics file.
`IsMoving`	Get if the arm is currently moving.
`Stop`	Stop all motion of the arm.
`GetGeometries`	Get all the geometries associated with the arm in its current configuration, in the frame of the arm.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`GetResourceName`	Get the `ResourceName` for this arm with the given name.
`Close`	Safely shut down the resource and prevent further use.

Establish a connection

To get started using Viam’s SDKs to connect to and control your arm and the rest of your machine, go to your machine’s page on the Viam app, Navigate to the CONNECT tab’s Code sample page, select your preferred programming language, and copy the sample code.

To show your machine’s API key in the sample code, toggle Include API key.

Caution: Keep your API key and machine address safe

We strongly recommend that you add your API key and machine address as an environment variable. Anyone with these secrets can access your machine, and the computer running your machine.

When executed, this sample code creates a connection to your machine as a client.

The following examples assume you have an arm called "my_arm" configured as a component of your machine. If your arm has a different name, change the name in the code.

Import the arm package for the SDK you are using:

Python
Go

from viam.components.arm import Arm
# To use move_to_position:
from viam.proto.common import Pose
# To use move_to_joint_positions:
from viam.proto.component.arm import JointPositions

import (
  "go.viam.com/rdk/components/arm"
  // To use MoveToPosition:
  "go.viam.com/rdk/referenceframe"
  "go.viam.com/rdk/spatialmath"
  // To use MoveToJointPositions ("armapi" name optional, but necessary if importing other packages called "v1"):
  armapi "go.viam.com/api/component/arm/v1"
)

API

GetEndPosition

Get the current position of the arm as a pose.

Parameters:

extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (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): 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:

my_arm = Arm.from_robot(robot=machine, name="my_arm")

# Get the end position of the arm as a Pose.
pos = await my_arm.get_end_position()

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:

(spatialmath.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.
(error): An error, if one occurred.

Example:

myArm, err := arm.FromRobot(machine, "my_arm")
// Get the end position of the arm as a Pose.
pos, err := myArm.EndPosition(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise<commonApi.Pose>)

Example:

const arm = new VIAM.ArmClient(machine, 'my_arm');
const pose = await arm.getEndPosition();

For more information, see the TypeScript SDK Docs.

Parameters:

extra Map<String, dynamic>? (optional)

Returns:

Future<Pose>

Example:

final currentPose = await myArm.endPosition();

For more information, see the Flutter SDK Docs.

MoveToPosition

Move the end of the arm in a straight line to the desired pose, 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) (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, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (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:

my_arm = Arm.from_robot(robot=machine, name="my_arm")

# Create a Pose for the arm.
examplePose = Pose(x=5, y=5, z=5, o_x=5, o_y=5, o_z=5, theta=20)

# Move your arm to the Pose.
await my_arm.move_to_position(pose=examplePose)

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.
pose (spatialmath.Pose): A representation of the arm’s destination 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.
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(error): An error, if one occurred.

Example:

myArm, err := arm.FromRobot(machine, "my_arm")
// Create a Pose for the arm.
examplePose := spatialmath.NewPose(
        r3.Vector{X: 5, Y: 5, Z: 5},
        &spatialmath.OrientationVectorDegrees{OX: 5, OY: 5, Theta: 20},
)

// Move your arm to the Pose.
err = myArm.MoveToPosition(context.Background(), examplePose, nil)

For more information, see the Go SDK Docs.

Parameters:

pose (PlainMessage) (required): The destination pose for the arm.
extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise)

Example:

const arm = new VIAM.ArmClient(machine, 'my_arm');

// Create a pose for the arm to move to
const pose: Pose = {
  x: -500,
  y: -200,
  z: 62,
  oX: 1,
  oY: 0,
  oZ: 1,
  theta: 90,
};

// Move the arm to the pose
await arm.moveToPosition(pose);

For more information, see the TypeScript SDK Docs.

Parameters:

pose Pose (required)
extra Map<String, dynamic>? (optional)

Returns:

Future

Example:

// Create a pose for the arm to move to
final targetPose = Pose.fromBuffer([12, 0, 400, 0, 0, 1, 90]);

// Move the arm to the pose
await myArm.moveToPosition(targetPose);

For more information, see the Flutter SDK Docs.

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) (required): The destination JointPositions for the arm.
extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (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:

my_arm = Arm.from_robot(robot=machine, name="my_arm")

# Declare a list of values with your desired rotational value for each joint on
# the arm. This example is for a 5dof arm.
degrees = [0.0, 45.0, 0.0, 0.0, 0.0]

# Declare a new JointPositions with these values.
jointPos = JointPositions(values=degrees)

# Move each joint of the arm to the position these values specify.
await my_arm.move_to_joint_positions(positions=jointPos)

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

Returns:

(error): An error, if one occurred.

Example:

myArm, err := arm.FromRobot(machine, "my_arm")

// Declare an array of values with your desired rotational value (in radians) for each joint on the arm.
inputs := referenceframe.FloatsToInputs([]float64{0, math.Pi/2, math.Pi})

// Move each joint of the arm to the positions specified in the above slice
err = myArm.MoveToJointPositions(context.Background(), inputs, nil)

For more information, see the Go SDK Docs.

Parameters:

jointPositionsList (number) (required): List of angles (0-360) to move each joint to.
extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise)

Example:

const arm = new VIAM.ArmClient(machine, 'my_arm');

// Move an arm with 6 joints (6 DoF)
await arm.moveToJointPositions([90, 0, 0, 0, 15, 0]);

For more information, see the TypeScript SDK Docs.

Parameters:

positions List<double> (required)
extra Map<String, dynamic>? (optional)

Returns:

Future

Example:

// Create a list of joint angles for each arm joint
List<double> targetPositions = [180, 90, 15.75, 30, 90, 0];

// Move the arm joints to those angles
await myArm.moveToJointPositions(targetPositions);

For more information, see the Flutter SDK Docs.

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): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
positions ([][]referenceframe.Input)
options (*MoveOptions)
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(error): An error, if one occurred.

Example:

myArm, err := arm.FromRobot(machine, "my_arm")

// Declare a 2D array of values with your desired rotational value (in radians) for each joint on the arm.
inputs := [][]referenceframe.Input{
  referenceframe.FloatsToInputs([]float64{0, math.Pi/2, math.Pi})
  referenceframe.FloatsToInputs([]float64{0, 0, 0})
}

// Move each joint of the arm through the positions in the slice defined above
err = myArm.MoveThroughJointPositions(context.Background(), inputs, nil, nil)

For more information, see the Go SDK Docs.

GetJointPositions

Get the current position of each joint on the arm.

Parameters:

extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (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): 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:

my_arm = Arm.from_robot(robot=machine, name="my_arm")

# Get the current position of each joint on the arm as JointPositions.
pos = await my_arm.get_joint_positions()

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:

([]referenceframe.Input)
(error): An error, if one occurred.

Example:

myArm , err := arm.FromRobot(machine, "my_arm")

// Get the current position of each joint on the arm as JointPositions.
pos, err := myArm.JointPositions(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise<JointPositions>)

Example:

const arm = new VIAM.ArmClient(machine, 'my_arm');
const jointPositions = await arm.getJointPositions();

For more information, see the TypeScript SDK Docs.

Parameters:

extra Map<String, dynamic>? (optional)

Returns:

Future<List<double>>

Example:

List<double> currentJointPositions = await myArm.moveToJointPosition();

For more information, see the Flutter SDK Docs.

GetKinematics

Note

This method is not yet available with the Viam Go SDK.

Get the kinematics information associated with the arm as the format and byte contents of the kinematics file.

Python

Parameters:

extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(Tuple[KinematicsFileFormat.ValueType, bytes]): 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:

my_arm = Arm.from_robot(robot=machine, name="my_arm")

# Get the kinematics information associated with the arm.
kinematics = await my_arm.get_kinematics()

# Get the format of the kinematics file.
k_file = kinematics[0]

# Get the byte contents of the file.
k_bytes = kinematics[1]

For more information, see the Python SDK Docs.

IsMoving

Get if the arm is currently moving.

Parameters:

timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(bool): Whether the arm is moving.

Example:

my_arm = Arm.from_robot(robot=machine, name="my_arm")

# Stop all motion of the arm. It is assumed that the arm stops immediately.
await my_arm.stop()

# Print if the arm is currently moving.
print(await my_arm.is_moving())

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:

(bool): Whether this resource is moving (true) or not (false).
(error): An error, if one occurred.

Example:

// This example shows using IsMoving with an arm component.
myArm, err := arm.FromRobot(machine, "my_arm")

// Stop all motion of the arm. It is assumed that the arm stops immediately.
myArm.Stop(context.Background(), nil)

// Log if the arm is currently moving.
is_moving, err := myArm.IsMoving(context.Background())
logger.Info(is_moving)

For more information, see the Go SDK Docs.

Parameters:

callOptions (CallOptions) (optional)

Returns:

(Promise)

Example:

const arm = new VIAM.ArmClient(machine, 'my_arm');
const isMoving = await arm.isMoving();
console.log(isMoving);

For more information, see the TypeScript SDK Docs.

Parameters:

None.

Returns:

Future<bool>

Example:

bool isArmMoving = await myArm.isMoving();

For more information, see the Flutter SDK Docs.

Stop

Stop all motion of the arm.

Parameters:

extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (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:

my_arm = Arm.from_robot(robot=machine, name="my_arm")

# Stop all motion of the arm. It is assumed that the arm stops immediately.
await my_arm.stop()

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:

// This example shows using Stop with an arm component.
myArm, err := arm.FromRobot(machine, "my_arm")

// Stop all motion of the arm. It is assumed that the arm stops immediately.
err = myArm.Stop(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise)

Example:

const arm = new VIAM.ArmClient(machine, 'my_arm');
await arm.stop();

For more information, see the TypeScript SDK Docs.

Parameters:

extra Map<String, dynamic>? (optional)

Returns:

Future

Example:

await myArm.stop();

For more information, see the Flutter SDK Docs.

GetGeometries

Get all the geometries associated with the arm in its current configuration, in the frame of the arm. The motion and navigation services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning.

Parameters:

extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(List[viam.proto.common.Geometry]): The geometries associated with the Component.

Example:

my_arm = Arm.from_robot(robot=machine, name="my_arm")
geometries = await my_arm.get_geometries()

if geometries:
    # Get the center of the first geometry
    print(f"Pose of the first geometry's centerpoint: {geometries[0].center}")

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:

([]spatialmath.Geometry): The geometries associated with this resource, in any order.
(error): An error, if one occurred.

Example:

// This example shows using Geometries with an arm component.
myArm, err := arm.FromRobot(machine, "my_arm")

geometries, err := myArm.Geometries(context.Background(), nil)

if len(geometries) > 0 {
   // Get the center of the first geometry
   elem := geometries[0]
   fmt.Println("Pose of the first geometry's center point:", elem.Pose())
}

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise<commonApi.Geometry[]>)

Example:

const arm = new VIAM.ArmClient(machine, 'my_arm');
const geometries = await arm.getGeometries();
console.log(geometries);

For more information, see the TypeScript SDK Docs.

Reconfigure

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

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
deps (Dependencies): The resource dependencies.
conf (Config): The resource configuration.

Returns:

(error): An error, if one occurred.

For more information, see the Go SDK Docs.

DoCommand

Execute model-specific commands that are not otherwise defined by the component API. For built-in models, model-specific commands are covered with each model’s documentation. If you are implementing your own arm and add features that have no built-in API method, you can access them with DoCommand.

Parameters:

command (Mapping[str, ValueTypes]) (required): The command to execute.
timeout (float) (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, viam.utils.ValueTypes]): Result of the executed command.

Raises:

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

Example:

my_arm = Arm.from_robot(robot=machine, name="my_arm")
command = {"cmd": "test", "data1": 500}
result = await my_arm.do_command(command)

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.
cmd (map[string]interface{}): The command to execute.

Returns:

(map[string]interface{}): The command response.
(error): An error, if one occurred.

Example:

myArm, err := arm.FromRobot(machine, "my_arm")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myArm.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

Parameters:

command (Struct) (required): The command to execute.
callOptions (CallOptions) (optional)

Returns:

(Promise<JsonValue>)

Example:

const result = await resource.doCommand({
  name: 'myCommand',
  args: { key: 'value' },
});

For more information, see the TypeScript SDK Docs.

Parameters:

command Map<String, dynamic> (required)

Returns:

Future<Map<String, dynamic>>

Example:

// Example using doCommand with an arm component
const command = {'cmd': 'test', 'data1': 500};
var result = myArm.doCommand(command);

For more information, see the Flutter SDK Docs.

GetResourceName

Get the ResourceName for this arm with the given name.

Python
Flutter

Parameters:

name (str) (required): The name of the Resource.

Returns:

(viam.proto.common.ResourceName): The ResourceName of this Resource.

Example:

my_arm_name = Arm.get_resource_name("my_arm")

For more information, see the Python SDK Docs.

Parameters:

name String (required)

Returns:

ResourceName

Example:

final myArmResourceName = myArm.getResourceName("my_arm");

For more information, see the Flutter SDK Docs.

Close

Safely shut down the resource and prevent further use.

Python
Go

Parameters:

None.

Returns:

None.

Example:

my_arm = Arm.from_robot(robot=machine, name="my_arm")
await my_arm.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:

myArm, err := arm.FromRobot(machine, "my_arm")

err = myArm.Close(context.Background())

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