Pause and resume a Zaber Console script

I've written a script using Zaber Console to control a Zaber device that executes several steps in a loop. How can I pause it in the middle of the loop and resume it without having to go back to the start?

Solution

I can think of four options to support this.

Make your script somehow detect the current state when it starts and figure out what part of the routine it should start with. Depending on your routine, you might be able to read the current position to tell what step you are at. If not, you could also use user memory or write the current state to a text file. One of the example scripts shows how to write to a text file.
In addition to your main script, write a pause script and a resume script. The main script notices the responses from the other two scripts. I'll include an example below.
Instead of separate scripts to pause and resume, use a Zaber Joystick and program the buttons to send the pause and resume commands. The example below will cover that as well.
Convert your script to a plug in that runs the main routine in a BackgroundWorker. Then you can hold the state in the control class, and add a Pause/Resume button.

Here's an example of using separate scripts to pause and resume your routine. It also describes how to use Joystick buttons.

The Original Routine

To start with, I created this simple routine.

/* C# example of how to pause and resume a Zaber Console script.
 * This script is the original routine without the pause and resume logic.
 * It moves to position zero, then makes four moves of 10000 microsteps each 
 * and goes back to zero. This loops forever.
 */
#template(simple)

while (true)
{
    for (var i = 0; i < 5; i++)
    {
        var position = i*10000;
        Output.WriteLine("moving to {0}", position);
        Conversation.Request(Command.MoveAbsolute, position);
    }
}

The Pause

Here's the script to pause the routine.

/* C# example of how to pause and resume a Zaber Console script.
 * This script pauses the main routine by sending a Stop command. Running this 
 * script twice will stop the routine.
 */
#template(simple)

Conversation.Request(Command.Stop);

The stop command will cause an error in the main script, but we'll change the main script to catch that error and add the pause/resume logic.

The Resume

Here's the script to resume the routine.

/* C# example of how to pause and resume a Zaber Console script.
 * This script resumes the main routine by sending an EchoData command with a
 * magic number.
 */
#template(simple)

const int RESUME_NUMBER = 42;// Matches the main routine.
Conversation.Request(Command.EchoData, RESUME_NUMBER);

The Routine Plus Pause Logic

The pause and resume scripts are pretty trivial; the real work is in making the main script listen for the error from the stop command and the magic number to resume. Here's the new version of the routine with all that added. Run this script in the main Script Editor window and run the other two from the grid in the Scripts tab of the main window.

/* C# example of how to pause and resume a Zaber Console script.
 * This script is the main routine that moves to position zero, then makes four
 * moves of 10000 microsteps each and goes back to zero. This loops forever.
 * To pause the routine, run the Pause.cs script. To resume the routine, run
 * the Resume.cs script. Running the pause script twice will stop the routine.
 */
#template(methods)

/* We switched to the methods template so we can put the move with pause and
 * resume into a helper method.
 */
public override void Run()
{
    while ( ! IsCanceled)
    {
        for (var i = 0; i < 5 && ! IsCanceled; i++)
        {
            var position = i*10000;
            MoveTo(position);
        }
    }
}

/* This wraps the pause and resume logic around a simple MoveAbsolute command.
 * If your resume logic is more complicated, you can put more commands inside 
 * the try/catch block, or use the return value of this function to tell the
 * main routine what to do next.
 * When this method returns, either the move has successfully completed, or
 * IsCanceled is true.
 */
private void MoveTo(int position)
{
    bool isComplete = false;
    while ( ! isComplete && ! IsCanceled)
    {
        try
        {
            Output.WriteLine("moving to {0}", position);
            Conversation.Request(Command.MoveAbsolute, position);
            isComplete = true;
        }
        catch (RequestReplacedException ex)
        {
            Pause();
        }
        catch (RequestCollectionException ex)
        {
            /* If you are running against device number zero
             * or some other alias, you get a slightly
             * different exception.
             */
            Pause();
        }
    }
}

/* Just wait for responses from your device. If a response is an EchoData 
 * command with the magic number, then this method will return. If the response
 * is a Stop command, then IsCanceled is set to true and this method will 
 * return. All other responses are ignored.
 */
private void Pause()
{
    Output.WriteLine("paused");

    /* Let the device finish processing the current stop command before
     * you start listening, otherwise you sometimes see the stop command
         * again.
         */
    Sleep(100); 

    const int RESUME_NUMBER = 42;// Matches the resume script.
    var listener = new DeviceListener(Conversation.Device);
    bool isPaused = ! IsCanceled;// Don't pause if already canceled.
    while (isPaused)
    {
        var response = listener.NextResponse();// wait
        if (response.Command == Command.EchoData && 
            response.Data == RESUME_NUMBER)
        {
            isPaused = false;
            Output.WriteLine("resumed");
        }
        else if (response.Command == Command.Stop)
        {
            isPaused = false;
            IsCanceled = true;
            Output.WriteLine("stopped");
        }
    }
}

The Joystick

If you have a Zaber joystick, it can be more convenient to tap a couple of joystick buttons than it is to run the pause and resume scripts in Zaber Console. The default command for button 1 on a joystick is Stop, so you've already got the pause taken care of. If you program one of the other buttons to send Echo Data 42, that can resume your script. The final script above will run the routine with pause and resume logic whether you use separate scripts to send the pause and resume commands or use joystick buttons to send them.