Pausing and operator prompts

Pause points and pause-aware waits, pausing for a person, custom resume actions, asking the operator a question, Slack notifications, and how a cancel reaches a skill.

A run can be paused, resumed and stopped from the app while a skill is running. A skill sees those requests at pause points: every motion and gripper call is one, and the functions below add more. This page covers the skill side; what the operator sees is described in Running a workflow on real hardware.

Pause points and waits

FunctionEffect
pause_checkpoint()A pause point. Blocks while the run is paused. Call it inside long stretches of Python that make no API calls.
pause_aware_sleep(seconds, *, poll_s=0.1)Waits seconds, checking for a pause every poll_s. A pause blocks the wait until resume; paused time counts toward seconds. Use it instead of time.sleep.

Outside a run there is nothing to pause: pause_checkpoint returns at once and pause_aware_sleep only sleeps.

Pausing for a person

pause_for_user(message, on_resume=None, *, slack_channel=None, files=None)

Pauses the run and blocks until someone resumes it, for a step a person must do by hand (refill a tip rack, clear a jam). When Slack is configured on the rig, message is also posted to Slack first, with files attached. on_resume, a function with no arguments, runs after a plain Resume.

pause_for_user("Refill the tip rack in position 3, then resume.")

Custom resume actions

register_custom_resume(label, callback)
unregister_custom_resume(label)

While the skill runs, each registered label appears as an extra button beside Resume when the run is paused. Choosing it runs callback on the skill's thread as the pause ends; on_resume of pause_for_user is then skipped. "Resume" is reserved. Registering a label again replaces its callback. An exception raised by the callback propagates out of the pause point.

def regrip():
    ...  # move back and grasp again

register_custom_resume("Grip again", regrip)
try:
    pause_for_user("The grip looks off. Fix it and resume, or choose Grip again.")
finally:
    unregister_custom_resume("Grip again")

Asking the operator a question

ask_user_slack(question, options=None, *, image=None, channel_id=None, timeout_s=600.0, default=None)

Shows question with one button per option and blocks the skill until an answer arrives, then returns it. The prompt appears in the live run in the app and, when Slack is configured on the rig, as a Slack message with the same buttons. From the CLI, zeon answer ID shows the open prompt of run ID and zeon answer ID CHOICE answers it. The first answer from any of these wins.

ArgumentMeaning
optionsA list of labels (each label is also the returned value), or a dict {label: value}. Default ["Yes", "No"]. An empty list or dict raises ValueError.
imageAn image path, a list of paths, or a folder (every .png, .jpg, .jpeg in it). A capture_image result can be passed directly.
channel_idThe Slack channel to post in, instead of the rig's default channel.
timeout_sHow long to wait for an answer, in seconds. Time the run spends paused does not count.
defaultReturned when the wait times out. Without it, a timeout raises TimeoutError.
  • A pause while the prompt is open stops the timeout from counting; the prompt stays answerable in the app and in Slack.
  • A Stop while the prompt is open ends the prompt: the call raises ExecutionCancelledInSkillError and the run ends cancelled. The Slack message is updated to say the run was stopped.
  • Outside a run with no Slack configured there is nowhere to ask: the call returns default, or raises RuntimeError without one.
choice = ask_user_slack("Did the plate seat correctly?",
                        {"Yes, continue": "ok", "No, seat it again": "retry"},
                        timeout_s=300, default="retry")
if choice == "retry":
    ...

Notifications

send_slack(text, channel=None, username=None, icon_emoji=None, blocking=False, files=None, channel_id=None,
           runlog=True)

Posts text to Slack without waiting for a reply. By default it posts in the background so it never delays the arm; blocking=True waits for delivery. files attaches local files (to channel_id, or the rig's default channel). A Slack failure never raises; a sent message is noted in the run log (runlog=False keeps the note out of it).

Where Slack works

Slack is configured per lab machine, in Secrets. In the cloud there are no secrets, so Slack is off: send_slack does nothing, pause_for_user only pauses, and ask_user_slack prompts in the app only.

The Slack functions have no simulator branch. On a lab machine with Slack configured they post from a simulated run too. Guard them when that is not wanted:

if not is_sim_mode():
    send_slack("Plate run finished.")

Cancellation

When a run is stopped, the next pause point raises ExecutionCancelledInSkillError (a move already in progress may instead end with MotionAborted). Pause points are a motion call, pause_checkpoint, pause_aware_sleep, pause_for_user while paused, or an open ask_user_slack prompt. Let it propagate. If the skill must clean up, catch it, clean up, and raise it again:

try:
    pause_for_user("Reset the deck, then resume.")
except ExecutionCancelledInSkillError:
    print_log("stopped while waiting for the deck reset")
    raise

Swallowing it keeps the skill running after the operator asked it to stop.


Did this page help you?