Pause and E-Stop

Most of your Recipes won't be as short or simple as our ramp up and ramp down demo. They may run for extended periods of time and you may find that you need to pause and resume your recipe prior to completion.

While a Recipe is active - Running, Paused, or E-Stopped - you can use the Recipe Control Buttons on the left sidebar menu to control the Recipe's state.

Let's see an example of interacting with a Recipe by writing a quick script for a Recipe that will never complete on its own. Let wrap the loop logic in our previous recipe in a while True: ... loop that will never return - it will run in a loop forever and change the pump's speed from 0 mL/min to 50 mL/min in each loop iteration.

from aqueduct.core.aq import Aqueduct
from aqueduct.core.aq import InitParams
from aqueduct.devices.pump import PeristalticPump

# parse initialization parameters and create Aqueduct instance
params = InitParams.parse()
aq = Aqueduct(params.user_id, params.ip_address, params.port)

# initialize the devices and set a command delay
aq.initialize(params.init)
aq.set_command_delay(0.05)

# get the peristaltic pump device and create a command object
pump: PeristalticPump = aq.devices.get("peristaltic_pump_000001")

commands = pump.make_commands()

command = pump.make_start_command(
    mode=pump.MODE.Continuous,
    rate_units=pump.RATE_UNITS.MlMin,
    rate_value=2,
    direction=pump.STATUS.Clockwise,
)

# set the command for the first (and only) node of the pump
pump.set_command(commands, 0, command)

# now send the start command
pump.start(commands)

# set the maximum speed and speed increment for the pump
MAX_SPEED: float = 50
INCREMENT: float = 1

# calculate the number of steps based on the maximum speed and increment
STEPS = int(MAX_SPEED / INCREMENT)

while True:  ## <---------- infinite loop
    # ramp up the speed to `top_speed_rpm`
    for i in range(0, STEPS):
        commands = pump.make_commands()

        # create a command to change the pump speed
        c = pump.make_change_speed_command(
            rate_value=i * INCREMENT, rate_units=pump.RATE_UNITS.MlMin
        )

        pump.set_command(commands, 0, c)

        pump.change_speed(commands)

        print(f"Ramping up to: {i * INCREMENT} mL/min")

    # ramp down the speed to `2 mL/min`
    for i in range(STEPS, 0, -1):
        commands = pump.make_commands()

        # create a command to change the pump speed
        c = pump.make_change_speed_command(
            rate_value=i * INCREMENT, rate_units=pump.RATE_UNITS.MlMin
        )

        pump.set_command(commands, 0, c)

        pump.change_speed(commands)

        print(f"Ramping down to: {i * INCREMENT} mL/min")

pump.stop()
print("Complete!")

Copy and paste the above code into the Editor Widget, queue the Recipe, and begin execution. You'll see the pump cycling between 0 and 50 mL/min.

Pausing a Recipe

We can Pause execution of our Recipe by pressing the Pause Recipe Button on the left sidebar menu:

Pause Recipe Button Menu

The Paused state indicates that your Recipe's Python process is active but has been temporarily paused to prevent further execution. The Recipe Status Indicator will display a yellow P badge:

Paused Recipe Status Indicator Paused

The Recipe transitions into the Paused state without any further input needed from the user and no Device actions are executed when a Recipe is paused.

Devices are left in the same state as they were in before the Pause Recipe Button was pressed. Notice that peristaltic_pump_000001 continued to operate at 12.5 mL/min.

To resume the Recipe, simply click the Start/Resume Recipe Button:

Start/Resume Recipe Button Menu

The Recipe will pick back up where it left off and peristaltic_pump_000001 will continue to cycle between 0 and 50 mL/min.

Emergency Stopping a Recipe

We can also issue an E-Stop command to our Recipe by pressing the E-Stop Recipe Button on the left sidebar menu:

E-Stop Recipe Button Menu

Just like Pausing your Recipe, E-Stopping pauses execution of your Recipe's Python process to prevent further execution.

However, an E-Stop command also issues stop commands to all Devices that are considered active when the E-Stop button is pressed. Active devices, such as operating pumps or robotic arms, are issued commands to stop any motion. Passive devices, such as balances, pH probes, or other sensors that simply transmit data and do not move, are left unaffected.

The Recipe Status Indicator will display a yellow ES badge:

E-Stopped Recipe Status Indicator E-Stopped

Notice that peristaltic_pump_000001 stopped operating when we pressed the E-Stop Recipe Button.

To resume the Recipe, click the Start/Resume Recipe Button. Because the Recipe is re-entering the Running state from the E-Stopped state, we will be asked to select which Devices are to resume operation before the Python process is restarted.

The Resume Recipe dialog displays a table with one or more rows for each Device. Each row specifies the action(s) that will be taken by default for that Device when the Recipe resumes, restoring the Device to the state it was in when the E-Stop button was pressed.

To ignore the default action, deselect the checkbox in the Resume? column.

Interacting with Devices while a Recipe is Paused or E-Stopped

All manual Device commands are accessible while a Recipe is Paused or E-Stopped.

You are free to use the controls from the Setup Menu on the left sidebar menu that we discussed in the Device Control section to manually control Devices as needed.

The following clip illustrates this functionality by:

  1. Pausing our infinite Recipe using the Pause Recipe Button
  2. Manually stopping peristaltic_pump_000001 using the Sandbox Widget stop button
  3. Running peristaltic_pump_000001 in continuous mode at 10 mL/min in the clockwise direction using the controls parameter inputs
  4. Resuming the infinite Recipe using the Start/Resume Recipe Button

Wrapping Up

In summary, the basics of interacting with an active recipe are:

  1. Pausing a Recipe temporarily stops execution of the Recipe's Python process without affecting the state of any Devices
  2. E-Stopping a Recipe temporarily stops execution of the Recipe's Python process AND stops any active Devices
  3. All manual Device commands - the buttons accessible on the left sidebar menu and the buttons associated with a Device in the Sandbox Widget - remain accessible when a Recipe is Paused or E-Stopped

Now, let's continue to build on our infinite while loop script...