Skill API cheat sheet

Every skill API call on one page: its signature, what it does, the options that matter, and short examples.

Every call a skill can make, grouped by task. Signatures are as in the code: names after * are keyword-only. The other pages of this section explain each group in depth.

A skill gets all of these from one line in its modules.py:

from execution.skill_api import *

Units are metres, radians and seconds; quaternions are wxyz; poses are in the world frame. Arms are "left" and "right". Wherever a call takes a target pose it also takes an Anchor or a 4x4 matrix. Wherever it takes an object it also takes a display name, a SkillObject or an {"object_ref": ...} dict.

Moving

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)
move_arm_js(arm, q, *, speed=None, constraints=None, allow=None, stop=True, via=None)
move_relative(arm, dxyz=(0.0, 0.0, 0.0), drpy=(0.0, 0.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)
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.0, 0.0), drpy=(0.0, 0.0, 0.0), *, frame="world", tcp_speed, accel=None,
                     timeout=None, allow=None, constraints=None, keep_upright=False, tolerance=None)
move_path(arm, steps, *, speed=None, stop=True)
Step(target, *, straight_line=False, keep_upright=False, keep_vertical=None, vertical_deg=5.0, tolerance=None,
     constraints=(), allow=(), scene=None, speed=None, tcp_speed=None, label="", stop=True)
sweep_anchor_steps(obj, anchor_name, joint, start_angle, end_angle, steps, tcp_speed, end_dz=0.0, tolerance=None)
interp_anchor_steps(obj, a0, a1, joints, steps, tcp_speed, start_dz=0.0)
run_parallel(legs, *, timeout=600.0)
plan_scope(name, *values)          # a with-block
CallWhat it does
move_armMoves the tool to target. Planned and collision-checked before anything moves. A free move by default.
move_arm_jsMoves the arm to six joint values q (rad, joint 1 to 6). Planned and collision-checked. via: joint configurations passed through first, as one move.
move_relativeMoves the tool by dxyz metres along the world axes (frame="world") or the tool's own (frame="tool"), and turns it by drpy radians. A straight line by default.
move_line_directA short straight line run by the arm controller's own linear move. Not planned and not collision-checked while it runs. For press and lift legs of a few centimetres over a known clearance. tcp_speed is required.
move_relative_directmove_line_direct to an offset, built as move_relative builds it.
move_pathA list of Steps (or bare poses) planned and checked as one move.
StepOne waypoint of move_path. scene gives the object joint values predicted at that step ({"<object>/<joint>": value}); stop=False flows through it.
sweep_anchor_stepssteps straight steps that follow anchor anchor_name as joint turns from start_angle to end_angle (rad): a lid or door arc. end_dz raises the path by that much along world z by the last step.
interp_anchor_stepssteps straight steps from anchor a0 to anchor a1 of one object, its joints at joints: moving a grip along a lid.
run_parallel{"left": fn, "right": fn}: one zero-argument function per arm, run at once and planned together. Returns {arm: return value}; the first failure is raised once both legs have ended.
plan_scopewith plan_scope(name, *values): keys the cached plans of the moves inside by name and values (object ids, names, numbers) instead of by all the skill's inputs.

Every move returns a MoveResult (q, tcp, duration_s). A move of one arm holds the other still unless it runs inside run_parallel.

Key options

OptionMeaning
straight_line=TrueThe 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.
speedA fraction in (0, 1] of the arm's joint-speed limit. Default: the limit. Any move.
tcp_speedMetres per second of the tool along a straight line (straight_line=True, move_relative, straight steps, the direct lines). On a free move_arm it raises TcpSpeedOnFreeMove. With both, speed caps the joints.
allow=Contact this one move may make: a contact(...) value, or a list of them. See Contact.
keep_upright=TrueThe tool's z axis stays within 5 degrees of where it points at the start (a number sets the cone in degrees). For a top-down grip: a plate carried level.
keep_vertical=AXISOne axis stays pointing straight down within vertical_deg (default 5) the whole move; the turn about vertical is free. AXIS is "x", "-x", "y", "-y", "z", "-z", a 3-vector in tool coordinates, or (held_object, axis). For a side grip, where keep_upright would freeze the heading. Not with keep_upright. A start or goal outside the cone is refused before anything moves.
posture=The joint configuration branch a free move_arm / move_relative resolves on: {"q": [6 values], "prefer": {"joint5": "positive"}, "off_branch": None}. See Paths, lids, and two arms. Straight lines, keep_upright, via and move_path take none.
tolerance=How exactly the goal must be reached: metres, (metres, radians), a Tolerance, or FREE_YAW (the turn about the tool's z axis free).
via=Intermediate targets, planned with the goal as one move.
stop=True (default): settle at the goal. False: pass through it so the next move blends in; free-space legs only. "loose": stop, but return once within about 2 mm of the goal.
constraints=Library goal types (Keep, Hold, ...) imported by name, for what the options above do not cover.

Direct lines (move_line_direct, move_relative_direct): tcp_speed is capped at 0.25 m/s, accel defaults to 0.5 m/s² (at most 1.0). In the simulator and inside run_parallel they run as the planned straight move_arm 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. Nothing checks clearance while a direct line runs on a real arm: keep them short.

Gripper and holding

CallWhat it does
set_gripper(arm, width, *, wait=True)Moves the fingers to width metres apart (0 closed, 0.085 fully open on the standard gripper; wider is clipped). Returns the measured width.
get_gripper(arm, *, fresh=True)The gripper opening (m).
attach(arm, obj, *, snap_anchor=None)Records obj as held, after the gripper closed on it. snap_anchor="grasp_short" records it exactly at that anchor on the tool; without it, where it is relative to the tool now.
release(arm, *, width=None, onto=None, settle=None, settle_anchor=None)Opens the gripper (width, default fully open) and records the object as let go: onto=(holder, anchor) seats it there; settle=pose with settle_anchor (default the anchor it was grasped by) records where it comes to rest.
holding(arm)The instance id the arm holds, or None.

There are no grasp or place calls: a skill moves, sets the gripper, then records with attach / release. After release the open fingers still touch the object, so the retreat must allow that contact.

Contact

CallWhat it does
contact(arm, *targets, parts="fingers", floor=None, side_floor=None)Permits parts of arm to touch targets. As with contact(...): it covers every move of arm in the block (and holds the arm while the other arm moves); as allow=contact(...) it covers one move.
only(obj, link=None)A target that is obj alone (or one link of it, such as "drawer"), not what sits on it or what it sits on.
seat_contact(arm, holder, slot, *labware, size=(0.16, 0.11, 0.04), dz=0.01)An allow= value: inside a box at holder's anchor slot only, the fingers, fingertip parts and held labware are not checked against holder and the named labware. Everything else keeps its check.
tips_floor(arm, *targets, floor=0.0)An allow= value: the fingers and fingertip parts may come floor metres from the labware standing in or on targets, still checked against its exact meshes.
collision_sensitivity(arm, level, *, restore=3)A with-block: the arm controller's own collision sensitivity (0 off to 5 most sensitive) inside, set back to restore on the way out. For a deliberate press on a direct line. Real arms only; does nothing in the simulator.

Targets: an object (with what sits in or on it and what it sits on), an Anchor (its object), a named support surface such as "table", or only(...).

parts: "fingers" (default: fingers and fingertips unchecked, the rest of the gripper within 5 mm, the held object unchecked), "palm", "gripper", "held", "arm", "camera", "stand", "side" (as "fingers", plus the arm's links, camera and mount within side_floor, default 5 mm), or one part by name ("link2", "left_outer_knuckle"). Several: a tuple. floor=f turns "unchecked" into "may come within f metres". With no targets, contact(arm, parts=(a, b), floor=f) pairs the parts with each other. allow= values combine: seat_contact(...) + tips_floor(...), or a list. Everything not named stays fully checked. Details: Contact.

World

CallWhat it does
resolve(obj)The instance id of obj. Raises ObjectNotFound or AmbiguousObject. Call it on every object parameter.
name_of(obj)The display name.
list_objects(type=None)The sorted instance ids, or those of one object type.
anchor(obj, name, *, joints=None)An Anchor where the object is now, or with its joints at joints (the world is not changed). Fields: pose, width, standoff, kind, link, gripper_variant. Methods: preapproach(standoff=None) (backed off along the anchor's -z; default its standoff, else 0.05 m), offset(dxyz, frame="local").
get_anchor_pose(obj, name, *, joints=None)anchor(...).pose.
get_object_pose(obj)The pose of the object's placement frame (its object anchor).
list_anchors(obj)The object's anchor names.
spawn(object_type, *, name=None, pose=None, on=None, style="aligned", joints=None, id=None)Adds an object at pose, or seated on=(holder, anchor). Returns its instance id.
despawn(obj)Removes an object from the world (consumed, discarded). Refused while held or while things sit on it.
replace(obj, object_type, *, pose=None)Same id, new type (an uncapped tube is the same tube).
set_object_pose(obj, pose, *, anchor="object")Records the object's anchor at pose, no motion. Refused while an arm holds it.
seat(obj, holder, anchor="top_center", *, style="aligned")Records obj's bottom_center seated on holder's anchor, no motion. style: "aligned" or "flipped_180".
seat_of(obj)A Seat (holder, anchor, style), or None.
set_articulation(obj, preset_or_joints)Sets the object's joints in the world model: a preset name ("open") or {joint: value}. Moving the physical part is the skill's job.
get_articulation(obj){joint: value}.

spawn, despawn and replace change the world in memory for the run; the saved world files are not edited.

Arm state

CallReturns
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).
tool_frame(arm)The name of the arm's active tool frame, for a library Keep or Target.
holding(arm)The instance id the arm holds, or None.

fresh=True on a real arm waits for its next reading and raises StaleArmState if it stopped reporting; fresh=False reads the world model's copy. In the simulator both read the world model.

Cameras

CallWhat it does
capture_image(camera=None, name=None, *, depth=True, quality="normal", profile=None, lens_position=None, export=False, save_to_project=None, arm=None, capture_name=None)One posed still. Returns a Capture (also a str: the folder the frame was saved to) or None. quality="best" or profile= switches the camera for this one frame; lens_position (0-255, needs profile) holds the focus. arm= and capture_name= are accepted for camera and name; save_to_project is ignored.
capture_video(camera_or_cameras, name, seconds, *, fps=None, depth=False, export=False)Records seconds of video from one camera or a list, in sync, blocking. Returns a Recording or None.
record_video(camera_or_cameras, name, *, fps=None, depth=False, export=False)with record_video(...) as rec: records while the block runs.
list_cameras()The camera names available now.

Cameras are named "left" / "right" (wrist cameras) or by another camera's name. They never raise on a camera failure: they log and return None. Every capture is written to data/captures/<execution_id>/<name>/ in the project. export=True also uploads it when data export is set up. Details: Cameras.

Errors

Failures are raised, never returned. SkillError (a RuntimeError) carries hint (what to change), details (every problem, one line each) and cause (the underlying motion error).

GroupKinds
Objects and anchorsObjectNotFound, AmbiguousObject, AnchorNotFound, GripperMismatch
Holding and seatsAlreadyHolding, NotHolding, HeldByOtherArm, HeldByArm, SeatOccupied, SeatMismatch, HolderHasOccupants
Motion (MotionFailed and its kinds)Unreachable, WouldCollide, JointLimit, StraightLineImpossible, NoRoute, ConstraintViolated, MotionStalled, MotionAborted; on real hardware only: ContactDetected, GraspFailed, GripperFault
Arms and setupArmNotInSetup, ArmNotInLeg, DualArmRequired, TcpSpeedOnFreeMove, StaleArmState
AvailabilityNotAvailableInSim, PeripheralUnavailable, MotionUnavailable

A refused move has not moved anything. Read the reason and change the target, the approach or the placement; retrying the same move gets the same answer. Details: Errors.

Carried helpers

GroupCalls
Logging and foldersprint_log(*args, **kwargs) (runlog=True also writes the run log; runlog_type="transfer"; export=False), execution_dir(create=False), project_data_dir(subdir=None, create=False)
Pausingpause_for_user(message, on_resume=None, *, slack_channel=None, files=None), register_custom_resume(label, callback), unregister_custom_resume(label), pause_checkpoint(), pause_aware_sleep(seconds, *, poll_s=0.1)
Operator prompts and Slackask_user_slack(question, options=None, *, image=None, channel_id=None, timeout_s=600.0, default=None) returns the answer (answered in Slack, the app, or with zeon answer); send_slack(text, channel=None, username=None, icon_emoji=None, blocking=False, files=None, channel_id=None, runlog=True)
Skill variablesset_skill_variable(key, value), get_skill_variable(key, default=None), clear_skill_variable(key)
Per-object live stateget_world_state(object_id), set_world_state(object_id, updates) (instance id: pass resolve(obj))
Liquid ledgerrecord_transfer(rxn_well, kind, *, index=None, part=None, vol=None), is_transfer_done(rxn_well, kind, index=None), load_liquid_state(), liquid_state_path(): the run's liquid_transfer.json, so a resumed run skips transfers already done
Secrets and external APIsget_secret(name, default=None), api_request(url, method="GET", *, json_body=None, params=None, headers=None, save_name=None, save_to_project=False, export=False, timeout=30, auth_secret=None); neither raises (check result["success"] and None)
Electronic pipetteinit_epipette(name, ble_device_name="picus", debug=True), epipette_aspirate(name, volume=5, speed=5), epipette_dispense(name, volume=5, speed=5), epipette_blow_out(name, speed=10), epipette_tip_eject(name), epipette_home(name), epipette_status(), configured_epipettes(), require_epipette(name); constants EPIPETTE, EPIPETTE_10UL, EPIPETTE_120UL; EpipetteNotConfiguredError. In the simulator the motor calls log and return a simulated success.
Localizationlocalize_object_tags(object_name, viewpoints=None, *, arm=None, use_prior=True, prior_std_pos_mm=20.0, prior_std_rot_deg=10.0, tag_edge_m=None, collection=None, sigma_px=0.5, huber_px=None, pos_sigma_gate_mm=15.0, min_detections=2, max_move_mm=None, max_fitness_mm=None, index=None, mode="corner", use_full_theta=None): re-measures a tagged object from a wrist-camera image; never raises, returns a dict. See Localizing an object.
Mode and typesis_sim_mode(), SkillObject, ExecutionInfoContext, ExecutionCancelledInSkillError

Imported by name

Not in the star import; import them where you need them:

from execution.skill_api import FREE_YAW, Tolerance, deg, mm

deg(x) converts degrees to radians and mm(x) millimetres to metres. Tolerance(position=0.0, rotation=0.0) and FREE_YAW are tolerance= values; Posture is a posture= value; Keep, Hold, Target, Axis, Region and facing are library goal types for constraints=. Pose is in the star import (Poses).

Deprecated names

They still work and log one warning per process. Do not use them in new code.

DeprecatedUse instead
place_object(obj, pose, *, anchor="object")set_object_pose(obj, pose, anchor=...)
Allow(a, b, floor=None, within=None)contact(arm, *targets, parts=..., floor=...)
tcp(arm)tool_frame(arm)
arms()Name the arms the skill moves.

Examples

Pick and place with contact

from .modules import (anchor, attach, contact, get_anchor_pose, get_tcp_pose, move_arm, move_arm_js,
                      move_relative, release, resolve, set_gripper)

ARM = "right"
HOME = [-0.218, -0.663, -0.989, -0.031, 1.682, 4.491]   # joint1..joint6, rad

def move_plate(plate, source, dest):
    plate, source, dest = resolve(plate), resolve(source), resolve(dest)
    grasp = anchor(plate, "grasp_short")
    set_gripper(ARM, 0.085)
    move_arm(ARM, grasp.preapproach(0.10))                         # free move to 10 cm back
    with contact(ARM, plate, source):                               # opened in free space
        move_arm(ARM, grasp, straight_line=True, tcp_speed=0.03)
        set_gripper(ARM, grasp.width)
        attach(ARM, plate, snap_anchor="grasp_short")
        move_relative(ARM, (0.0, 0.0, 0.10), tcp_speed=0.08)       # lift straight up

    top = anchor(dest, "top_center")
    grip = get_tcp_pose(ARM).inverse() @ get_anchor_pose(plate, "bottom_center")
    seat = top.pose @ grip.inverse()                                # the tool pose that seats the plate
    above = seat.translated((0.0, 0.0, 0.10), frame="world")
    move_arm(ARM, above, keep_upright=True)                         # carry level
    with contact(ARM, dest, plate):
        move_arm(ARM, seat, straight_line=True, tcp_speed=0.03)
        release(ARM, onto=(dest, "top_center"), settle=top.pose, settle_anchor="bottom_center")
    move_arm(ARM, above, straight_line=True, tcp_speed=0.08, allow=contact(ARM, plate))   # fingers still touch
    move_arm_js(ARM, HOME)

A direct line into a seat

seat = anchor(holder, "slot_1").pose @ grip.inverse()        # the tool pose that seats the held plate (grip as above)
over = seat.translated((0.0, 0.0, 0.03), frame="world")
move_arm(ARM, over, keep_upright=True)                                      # planned, checked
allow = seat_contact(ARM, holder, "slot_1", plate) + tips_floor(ARM, holder)
move_relative_direct(ARM, (0.0, 0.0, -0.03), tcp_speed=0.01, allow=allow)    # 3 cm down, unplanned
release(ARM, onto=(holder, "slot_1"))
move_relative_direct(ARM, (0.0, 0.0, 0.03), tcp_speed=0.02, allow=allow)     # straight back up

The direct legs are not collision-checked while they run. Pass the contact they need as allow anyway: when the arm controller refuses a direct leg before moving, it runs as a planned, checked straight line with that allow.

A lid arc with move_path

start = get_articulation(shaker)["lid_joint"]
grip = anchor(shaker, "lid_grip")
set_gripper(ARM, 0.085)
move_arm(ARM, grip.preapproach())
with contact(ARM, shaker):
    move_arm(ARM, grip, straight_line=True, tcp_speed=0.02)
    set_gripper(ARM, grip.width)
    move_path(ARM, sweep_anchor_steps(shaker, "lid_grip", "lid_joint", start, 1.3, 13, 0.05))
    set_gripper(ARM, 0.085)
move_arm(ARM, anchor(shaker, "lid_grip").preapproach(), straight_line=True, tcp_speed=0.02,
         allow=contact(ARM, shaker))

The world model's lid angle follows the path; no set_articulation is needed.

keep_vertical for a side grip

# a pipette held sideways, its nozzles along the tool's -x axis: flipped over the rack, nozzles down throughout
move_arm(ARM, over_rack, keep_vertical="-x", posture=APPROACH_POSTURE)
# the held object's own -z kept within 3 degrees of straight down
move_arm(ARM, over_plate, keep_vertical=(pipette, "-z"), vertical_deg=3)

Did this page help you?