Arm motion and the gripper

Move an arm to a pose, a joint configuration or a relative offset; set speeds; open and close the gripper; record holding and letting go; read the arm's state.

Every move function here plans the whole move and checks it for collisions before the arm moves, then blocks until the arm has reached the goal. A move that cannot be made raises a SkillError and nothing moves (see Errors). A move of one arm holds the other still. Each move call returns a MoveResult with the arm's final joints (q), the final tool pose (tcp) and the time it moved (duration_s).

Moving to a pose

move_arm(arm, target, *, straight_line=False, speed=None, tcp_speed=None, allow=None,
         keep_upright=False, stop=True, tolerance=None, constraints=None, via=None, posture=None,
         keep_vertical=None, vertical_deg=5.0)

Moves the tool (the TCP of the arm's gripper) to target, a Pose, an Anchor or a 4x4 matrix in the world frame.

  • Free move (default): the planner chooses the path through free space. Use it to get to a pre-approach pose and to carry.
  • straight_line=True: the tool moves along the straight line from where it is to the target. Use it for the last centimetres into a grasp or a seat and for lifts. A straight line that cannot be followed raises StraightLineImpossible.
  • keep_upright=True: the tool's z axis stays within 5 degrees of its direction at the start of the move (a number sets the cone in degrees). Start the move level to carry open labware level.
  • keep_vertical=AXIS: one axis stays pointing straight down within vertical_deg degrees (default 5) the whole move, the turn about vertical free. AXIS is a tool axis ("x", "-x", "y", "-y", "z", "-z"), a 3-vector in tool coordinates, or (held_object, axis) for an axis of the held object. Use it for a side grip, where keep_upright would freeze the heading; posture= picks which way round the arm turns. A start or goal outside the cone is refused before anything moves. Not with keep_upright.
  • allow=: contact this move is permitted to make. See Contact.
  • tolerance=: how exactly the goal must be reached. A number is a position tolerance in metres; FREE_YAW leaves the turn about the tool's z axis free (round plates, tubes); Tolerance(position=0.002, rotation=0.05) sets both. Import Tolerance and FREE_YAW by name from execution.skill_api.
  • via=[pose, ...]: intermediate targets, planned with the goal as one move.
  • stop=False: pass through the target without settling, so the next move blends into this one. Use it only for free-space legs; keep the default before a contact, a press or a gripper action. stop="loose" stops but returns once the arm is within about 2 mm of the goal instead of waiting for it to settle.
  • posture=: the joint configuration branch to resolve the goal on. See Paths, lids, and two arms.
grasp = anchor(plate, "grasp_short")
move_arm("right", grasp.preapproach(0.10))                         # free move to 10 cm above
move_arm("right", grasp, straight_line=True, tcp_speed=0.03)        # straight in, slowly

Moving to a joint configuration

move_arm_js(arm, q, *, speed=None, constraints=None, allow=None, stop=True, via=None)

Moves the arm to six joint values q (radians, joint 1 to joint 6), planned and collision-checked. via is a list of joint configurations passed through in order, planned as one move with the goal. Write joint configurations as literals in the skill:

HOME = [-0.218, -0.663, -0.989, -0.031, 1.682, 4.491]   # joint1..joint6, rad: the starter's right-arm home
move_arm_js("right", HOME)

End a skill with its arm at a known joint configuration so the next skill starts from a clear, predictable place.

Moving relative to where the tool is

move_relative(arm, dxyz=(0, 0, 0), drpy=(0, 0, 0), *, frame="world", straight_line=True,
              keep_upright=False, tolerance=None, constraints=None, speed=None, tcp_speed=None, allow=None,
              stop=True, posture=None, keep_vertical=None, vertical_deg=5.0)

Moves the tool by dxyz metres along the world axes (frame="world") or the tool's own axes (frame="tool"), and turns it by drpy radians. A straight line by default.

move_relative("right", (0.0, 0.0, 0.08), tcp_speed=0.08)   # lift 8 cm straight up
move_relative("right", (0.0, 0.0, -0.02), frame="tool")     # 2 cm back along the tool's own z

The offset is taken from the target of the previous move in the same skill run when there is one, otherwise from where the tool is. A world-frame offset is always along world axes, whatever the orientation of the object: derive a direction from anchors when you need an object-aligned slide.

Speed

ArgumentMeaning
speedA fraction in (0, 1] of the arm's joint-speed limit. Unset: the limit. A value outside (0, 1] raises ValueError.
tcp_speedMetres per second of the tool, for straight lines only (straight_line=True, move_relative, straight path steps). On a free move_arm it raises TcpSpeedOnFreeMove. It is the tool's speed along the line; when both are given, speed caps the joints.

Short direct lines

move_line_direct(arm, target, *, tcp_speed, accel=None, timeout=None, allow=None, constraints=None,
                 keep_upright=False, tolerance=None)
move_relative_direct(arm, dxyz=(0, 0, 0), drpy=(0, 0, 0), *, frame="world", tcp_speed, accel=None,
                     timeout=None, allow=None, constraints=None, keep_upright=False, tolerance=None)

A straight line run by the arm controller's own linear move, without the planner: for the short press and lift legs whose plan would take longer than the leg. Nothing checks clearance while it runs; only the arm's own limits and collision detection apply. Keep it to a few centimetres straight onto or off something the tool is already aligned over. tcp_speed is required and capped at 0.25 m/s; accel defaults to 0.5 m/s² (at most 1.0). In the simulator and inside run_parallel it runs as the planned move_arm(..., straight_line=True) instead, with the moving arm and what it holds unchecked, as on the robot: a clean simulated run does not show that a direct line is clear.

move_relative_direct("right", (0.0, 0.0, -0.012), tcp_speed=0.01)   # a 12 mm press down

The gripper

set_gripper(arm, width, *, wait=True)   # returns the measured width (m)

Moves the fingers to width metres apart: 0 is closed, 0.085 is fully open on the standard gripper. A wider value is clipped. Close to an anchor's stated width with set_gripper(arm, grasp.width).

Holding and letting go

The gripper call moves the fingers; these record what the arm holds, so that the planner checks the held object and the next skill finds it where it is.

attach(arm, obj, *, snap_anchor=None)
release(arm, *, width=None, onto=None, settle=None, settle_anchor=None)
holding(arm)   # the instance id the arm holds, or None
  • attach, after the gripper has closed on the object: records obj as held by arm. With snap_anchor="grasp_short", the object is recorded exactly at that anchor on the tool (the canonical grip, identical on every pick). Without it, the object is recorded where it is relative to the tool now. An object held by the other arm raises HeldByOtherArm.
  • release opens the gripper (to width, default fully open) and records the object as let go. onto=(holder, anchor) records it seated on that holder's anchor. settle=pose records it resting with its settle_anchor (default: the anchor it was grasped by) on that pose. Without settle, it is recorded where the gripper held it. Releasing with nothing held raises NotHolding.
set_gripper("right", grasp.width)
attach("right", plate, snap_anchor="grasp_short")
...
release("right", onto=(stand, "top_center"), settle=seat_anchor.pose, settle_anchor="bottom_center")

After release the open fingers still touch the object. The next move must allow that contact (allow=contact(arm, obj)) or it is refused before it starts. See Contact.

Reading the arm's state

FunctionReturns
get_tcp_pose(arm, *, fresh=True)The tool pose in the world (Pose).
get_joints(arm, *, fresh=True)The six joint values (rad).
get_gripper(arm, *, fresh=True)The gripper opening (m).
holding(arm)The instance id the arm holds, or None.

On a real rig, fresh=True waits for the arm's next reading and raises StaleArmState if the arm has stopped reporting; fresh=False returns the world model's last copy without waiting. In the simulator both read the world model.


Did this page help you?