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| Call | What it does |
|---|---|
move_arm | Moves the tool to target. Planned and collision-checked before anything moves. A free move by default. |
move_arm_js | Moves 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_relative | Moves 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_direct | A 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_direct | move_line_direct to an offset, built as move_relative builds it. |
move_path | A list of Steps (or bare poses) planned and checked as one move. |
Step | One waypoint of move_path. scene gives the object joint values predicted at that step ({"<object>/<joint>": value}); stop=False flows through it. |
sweep_anchor_steps | steps 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_steps | steps 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_scope | with 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
| Option | Meaning |
|---|---|
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. |
speed | A fraction in (0, 1] of the arm's joint-speed limit. Default: the limit. Any move. |
tcp_speed | Metres 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=True | The 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=AXIS | One 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
| Call | What 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
| Call | What 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
| Call | What 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
| Call | Returns |
|---|---|
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
| Call | What 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).
| Group | Kinds |
|---|---|
| Objects and anchors | ObjectNotFound, AmbiguousObject, AnchorNotFound, GripperMismatch |
| Holding and seats | AlreadyHolding, 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 setup | ArmNotInSetup, ArmNotInLeg, DualArmRequired, TcpSpeedOnFreeMove, StaleArmState |
| Availability | NotAvailableInSim, 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
| Group | Calls |
|---|---|
| Logging and folders | print_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) |
| Pausing | pause_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 Slack | ask_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 variables | set_skill_variable(key, value), get_skill_variable(key, default=None), clear_skill_variable(key) |
| Per-object live state | get_world_state(object_id), set_world_state(object_id, updates) (instance id: pass resolve(obj)) |
| Liquid ledger | record_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 APIs | get_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 pipette | init_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. |
| Localization | localize_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 types | is_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, mmdeg(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.
| Deprecated | Use 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 upThe 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)Updated 1 day ago