Skill API

The functions a skill calls, the conventions they share, and where each group is documented.

A skill gets the skill API from one line in its modules.py:

from execution.skill_api import *

robotic_code.py then imports the names it uses from .modules. The names documented in these pages are the supported API; nothing else in the platform is.

Conventions

  • Units: metres, radians, seconds. Speeds are a fraction of the arm's speed limit (speed) or metres per second of the tool tip (tcp_speed).
  • Frames: every pose is in the world frame unless a function says otherwise. Quaternions are wxyz (scalar first). Roll-pitch-yaw is extrinsic x-y-z.
  • Arms are named "left" and "right". "left_arm" and "right_arm" are accepted. An arm the setup does not have raises ArmNotInSetup.
  • Objects are named by instance id. The motion and world functions that take an object also accept a display name, a SkillObject or an {"object_ref": ...} dict; resolve() turns any of these into the id. get_world_state, set_world_state and localize_object_tags need the instance id (pass resolve(obj)).
  • Poses are Pose values. Wherever a function takes a pose it also takes an Anchor or a 4x4 matrix.

How the functions behave

  • Every motion function plans the whole move and checks it for collisions before the arm moves, then blocks until the arm reaches the goal. When the move cannot be made, nothing moves and the call raises a SkillError that says why. See Errors.
  • A move of one arm holds the other arm still, unless the two moves run inside run_parallel.
  • Every motion function is a pause point. A pause requested in the app takes effect at the next call; a cancel raises ExecutionCancelledInSkillError there.
  • Bookkeeping is explicit. There are no grasp or place functions. A skill moves the arm, sets the gripper, then records what happened: attach after closing on an object, release when letting go. The planner and the next skill rely on that record.

The functions

PageWhat it covers
Cheat sheetEvery call on one page: signatures, key options, short examples.
PosesPose: build, combine, invert, offset and interpolate poses.
Objects, anchors, and the worldresolve, anchor, list_anchors, object poses, seats, articulations, adding and removing objects.
Arm motion and the grippermove_arm, move_arm_js, move_relative, speeds, set_gripper, attach, release, reading the arm's state.
Paths, lids, and two armsmove_path with sweep_anchor_steps / interp_anchor_steps, run_parallel, posture=.
Contactcontact and only: declaring the touching a move is allowed to do.
ErrorsSkillError and its kinds, and what to change for each.
Camerascapture_image, capture_video, record_video, list_cameras, localize_object_tags.
Calling an external APIapi_request and get_secret.
Pausing and operator promptspause_for_user, ask_user_slack, send_slack, pause points, cancellation.
Skill state and loggingprint_log, skill variables, run and project folders, per-object live state, is_sim_mode.

Names imported by name

A few helpers are not part of the star import. Import them explicitly 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, for writing literals. Tolerance and FREE_YAW are described on Arm motion and the gripper.

On a real rig these functions move real hardware. A move that plans cleanly is checked against the world model, not against the physical bench: an object that is not where the world says it is can still be hit. Run in the simulator first and keep the world model accurate.


Did this page help you?