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 raisesArmNotInSetup. - Objects are named by instance id. The motion and world functions that take an object also accept a display name, a
SkillObjector an{"object_ref": ...}dict;resolve()turns any of these into the id.get_world_state,set_world_stateandlocalize_object_tagsneed the instance id (passresolve(obj)). - Poses are
Posevalues. Wherever a function takes a pose it also takes anAnchoror 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
SkillErrorthat 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
ExecutionCancelledInSkillErrorthere. - Bookkeeping is explicit. There are no grasp or place functions. A skill moves the arm, sets the gripper, then records what happened:
attachafter closing on an object,releasewhen letting go. The planner and the next skill rely on that record.
The functions
| Page | What it covers |
|---|---|
| Cheat sheet | Every call on one page: signatures, key options, short examples. |
| Poses | Pose: build, combine, invert, offset and interpolate poses. |
| Objects, anchors, and the world | resolve, anchor, list_anchors, object poses, seats, articulations, adding and removing objects. |
| Arm motion and the gripper | move_arm, move_arm_js, move_relative, speeds, set_gripper, attach, release, reading the arm's state. |
| Paths, lids, and two arms | move_path with sweep_anchor_steps / interp_anchor_steps, run_parallel, posture=. |
| Contact | contact and only: declaring the touching a move is allowed to do. |
| Errors | SkillError and its kinds, and what to change for each. |
| Cameras | capture_image, capture_video, record_video, list_cameras, localize_object_tags. |
| Calling an external API | api_request and get_secret. |
| Pausing and operator prompts | pause_for_user, ask_user_slack, send_slack, pause points, cancellation. |
| Skill state and logging | print_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, mmdeg(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.
Updated 1 day ago