Arm motion and the gripper

These functions drive the two robot arms and their grippers. You use them to send an arm to a pose, nudge it a small distance, read where its tool is right now, and set how far the gripper is open. They are imported into your skill with from execution.execution_functions import *.

Most functions here take an arm argument (the exception is detach_object_from_arm, which takes only object_id). Where an arm argument is present, the only valid values are the strings "left_arm" and "right_arm". Any other value is treated as "right_arm".

Cartesian moves

move_arm

move_arm(arm, position, orientation, speed=100, wait=True, *, max_ik_retries=3)

Moves the arm's tool centre point (TCP) to a Cartesian pose in the world frame. Commands motion.

Parameters:

• arm (str): "left_arm" or "right_arm".
• position (list of 3 floats): [x, y, z] target position in metres, world frame.
• orientation (list of 3 floats): [roll, pitch, yaw] target orientation in radians. This is an intrinsic roll-pitch-yaw convention (it is converted to a quaternion internally).
• speed (default 100): speed parameter. The unit is not stated in source, so treat it as a relative value rather than a physical speed.
• wait (bool, default True): block until the move completes before returning.
• max_ik_retries (keyword-only int, default 3): total number of attempts when the move fails because no inverse-kinematics solution was reached. See below.

Returns: None on success.

Fails when:

• The pose cannot be reached (inverse kinematics fails, or the straight-line move is infeasible). The call retries up to max_ik_retries times, backing off briefly between attempts, then raises RuntimeError. The message contains failed after N IK retries, followed by the underlying error detail.
• Any non-IK failure (for example a communication or mode error) raises RuntimeError immediately without retrying.

# Send the right arm to a pose 40 cm forward, 25 cm up, pointing straight down.
import math
move_arm("right_arm", [0.40, 0.0, 0.25], [math.pi, 0.0, 0.0])

move_relative

move_relative(arm, delta_xyz, delta_rpy=None, speed=100, wait=True)

Moves the arm by an offset relative to its current TCP pose. Commands motion.

Parameters:

• arm (str): "left_arm" or "right_arm".
• delta_xyz (list of 3 floats): [dx, dy, dz] position offset in metres, world frame.
• delta_rpy (list of 3 floats, optional): [droll, dpitch, dyaw] orientation offset in radians. If omitted, orientation is held. If given, it must have length 3 or the call raises ValueError.
• speed (default 100): speed parameter (unit not stated in source; treat as relative).
• wait (bool, default True): block until the move completes.

Returns: None on success.

This reads the current pose, adds your offsets, and then performs a move_arm to the result, so it can raise the same RuntimeError on an unreachable target.

# Lift the tool 2 cm straight up without changing orientation.
move_relative("left_arm", [0.0, 0.0, 0.02])

get_arm_pose

get_arm_pose(arm)

Reads the arm's current TCP pose. Does not move the arm.

Parameters:

• arm (str): "left_arm" or "right_arm".

Returns: a NumPy array of six values, [x, y, z, roll, pitch, yaw]. Position is in metres and orientation is in radians, world frame. This is the same layout move_arm accepts, so you can slice the first three values for position and the last three for orientation.

pose = get_arm_pose("right_arm")
position = pose[:3]        # [x, y, z] in metres
orientation = pose[3:]     # [roll, pitch, yaw] in radians

Joint moves

move_arm_js

move_arm_js(arm, joint_angles, speed=None)

Moves the arm to a specific joint configuration. Commands motion.

Parameters:

• arm (str): "left_arm" or "right_arm".
• joint_angles (list or tuple of 6 floats): the six joint angles in radians, in the arm's joint order.
• speed (default None): speed parameter. When None, a conservative default is used. The unit is not stated in source; treat it as a relative value.

Returns: None on success.

Fails when: the joint move cannot be executed. The call raises RuntimeError with a message that begins move_arm_js(<arm>) failed.

This call always blocks until the move completes.

Gripper

set_gripper

set_gripper(arm, width_m)

Sets the gripper opening to a target width. Commands motion (the gripper fingers move).

Parameters:

• arm (str): "left_arm" or "right_arm".
• width_m (float): opening width in metres. 0.0 is fully closed; larger values open the gripper (for example 0.08 is an 8 cm opening).

Returns: None.

The call blocks until the gripper reaches the width, then settles briefly before returning.

set_gripper("left_arm", 0.08)   # open to 8 cm
# ... position the arm over the object ...
set_gripper("left_arm", 0.0)    # close to grasp

Carrying an object

When an arm picks something up, tell the world model so that later motion planning accounts for the object riding on the tool. These two calls update that model. They do not move the arm.

attach_object_to_arm

attach_object_to_arm(object_id, arm)

Marks an object as held by the arm's TCP, so that from now on the object travels with the tool.

Parameters:

• object_id (str): the UUID of the object to attach.
• arm (str): "left_arm" or "right_arm".

Returns: None.

Call this right after you close the gripper on the object.

detach_object_from_arm

detach_object_from_arm(object_id)

Releases the object from the arm so it no longer travels with the tool.

Parameters:

• object_id (str): the UUID of the object to detach.

Returns: None.

Call this right after you open the gripper to release the object.

set_gripper("right_arm", 0.0)
attach_object_to_arm(my_object_id, "right_arm")
# ... move the arm; the object moves with it ...
set_gripper("right_arm", 0.08)
detach_object_from_arm(my_object_id)

Related