Using Callbacks in TestStand

Contents

What is a Callback?

Callbacks are sequences that TestStand calls under specific circumstances. You can create new callback sequences or you can override existing callbacks to customize the operation of the test station. TestStand defines three categories of callbacks: Model callbacks, Engine callbacks, and Front-End callbacks. The categories are based on the entity that invokes the callback and the location in which you define the callback. Model callbacks allow you to customize the behavior of a process model for each Main sequence that uses it. Engine callbacks are defined by the TestStand Engine and are invoked at specific points during execution. Front-End callbacks are called by user interface programs to allow multiple user interfaces to share the same behavior for a specific operation.

Using Model Callbacks

Use Model callbacks to customize the behavior of a process model for each client sequence file that the process model uses. By defining one or more Model callbacks in a process model, you can specify the process model operations you can customize in a client sequence file. When you define a Model callback in a client sequence file, the Model callback overrides the sequence in the process model so that the sequence the client file defines runs instead of the sequence in the model file.

Why Use a Model Callback?

The default process model is sufficient for most situations, but you might need to modify the default model by replacing certain behaviors with different behaviors. For example, the default process models define a TestReport callback that generates the test report for each UUT. Normally, the TestReport callback in the default process model file is sufficient because the TestReport callback handles many types of test results. You can, however, override the default TestReport callback by defining a different TestReport callback in a particular client sequence file using the Sequence File Callbacks dialog box.

Other common use cases for overriding a model callback include:

  • Changing the report options to always report in a certain format or location.
  • Changing the database options to specify how TestStand logs information to a database.
  • Changing the model options to always use a certain number of test sockets.
  • Adding initialization code that TestStand runs once before testing a set of UUTs.
  • Adding clean-up code that TestStand runs once after testing a set of UUTs.
  • Identifying the UUT serial numbers with a barcode scanner.
  • Changing how TestStand generates the report.

Modifying the Process Model vs. Using a Model Callback

You often must choose between modifying a process model directly and using a model callback when you decide how to handle custom behaviors. Although both options are feasible, consider the following scenarios to help you determine which alternative to use:

Scenario 1

Situation: You want to add behavior you designed to be common across all the sequence files you run.

Solution: Put the code in the process model.

Justification: If you put the code in a callback, you must do so for every sequence file you run. Developers can forget to do this which can cause incorrect behavior. If you must modify the code, you must search for all the copies in multiple sequence files.

Scenario 2

Situation: You want to add behavior that is mostly common across all the sequence files you run, but some sequence files require a different behavior.

Solution: Put the code in the process model.

Justification: This scenario is similar to Scenario 1, except sequence files that need a different behavior can use a callback to override the behavior.

Scenario 3

Situation: You have many different behaviors you want to occur at some point in a sequence, but not for a majority of the time.

Solution: Choose one (or none) of the behaviors as a default. If you choose to make one of the behaviors the default, put the behavior in the process model. Override the callback for the other sequence files.

Justification: In a situation that varies for individual situations, the model must do something because there is no true default behavior. This behavior can be one behavior designated default or nothing and require the sequence files to implement the behavior. If a behavior is repeated, NI recommends that you code the behavior in a separate sequence file so the code resides in only one place.

How to Use a Model Callback

Each process model can define any number of Model callbacks, which appear with a green icon in the sequence list. Right-click the Sequence View control and select Sequence File Callbacks from the context menu to launch the Sequence File Callbacks dialog box, in which you can view a list of all Model and Engine callbacks available (depending on the process model currently associated with the sequence file) and add model callbacks to normal sequence files. Double-click on the desired callback or click the Add button in the Sequence File Callbacks dialog box to add model callbacks. Notice that when you double-click on the desired callback the value of the Present column changes from No to Yes. After you add the desired callbacks, they appear in the sequence list. Users can also create model callbacks by creating a new sequence and naming the sequence with the same name as a callback.

You can also add new model callbacks to the process model by adding a sequence to the sequence list. After you add the sequence, you must designate the sequence as a Model callback by right-clicking on the sequence and selecting Sequence Properties from the context menu. You must change the Type from Normal to Callback on the Model tab of the Sequence Properties dialog box. The Type option is only available when the sequence is in a process model.

Using Engine Callbacks

The TestStand Engine defines a set of Engine callbacks and invokes the Engine callbacks at specific points during execution. Use Engine callbacks to configure TestStand to call certain sequences at various points during a test, including before and after the execution of individual steps, before and after interactive executions, after loading a sequence file, or before unloading a sequence file. TestStand defines the set of Engine callbacks and their names because the TestStand Engine controls the execution of steps and the loading and unloading of sequence files. You cannot add new Engine callbacks.

Why Use an Engine Callback?

Use Engine callbacks for any behavior you want to execute based on a certain engine behavior. Common use cases include:

  • Initializing instruments when TestStand loads a sequence file.
  • Adding custom information to the ResultList after every execution.
  • Allowing an operator to retry a test if the test fails.
  • Handling errors after a step.
  • Logging to a database or report after every step.

How to Use an Engine Callback

You can add Engine callbacks in the same manner as Model callbacks to sequence files. You can define Engine callbacks in normal sequence files, process models, and a station callback file. Callbacks you define in the sequence file only affect that particular sequence. Process model callbacks that execute on steps affect either the model itself or the client sequence file (depending on which callback you use), and callbacks you define in the station callback sequence file affect either the station callback file itself or any other file you run on the station (depending on which callback you use). All callbacks which you added to the process model file that begin with the prefix “SequenceFile” affect the process model itself, and all callbacks that begin with the prefix “ProcessModel” affect the client sequence files. All callbacks which you used in the station callback that begin with the prefix “SequenceFile” affect only the Station Callback file, and all callbacks that begin with the prefix “Station” affect any sequence file loaded on the station.

The Station Callback is a special file located in the <TestStand>\Components\<NI or User>\Callbacks\Station\StationCallbacks.seq file and holds station callbacks. The location in which you place your callback depends on how global you want the behavior to be. If you only want the behavior to be present in a certain sequence file, place the callback in the sequence file. If you want the behavior to happen for every file using a process model, place the callback in the process model. If you want the behavior to happen no matter what model a sequence file uses, place the callback in the station callback. Defining an Engine callback in multiple files does not override behavior. The TestStand Engine calls each callback in this case.

Front-End Callbacks

Front-End callbacks are sequences in the FrontEndCallbacks.seq file, located in the <TestStand>\Components\<NI or User>\Callbacks\FrontEnd directory, the user interface applications call. Front-End callbacks allow multiple user interfaces to share the same implementation for a specific operation. The version of FrontEndCallback.seq TestStand installs contains one Front-End callback sequence, the LoginLogout callback, that the sequence editor and all user interfaces included with TestStand call.

Why Use Front-End Callbacks?

Use Front-End callbacks when you must call a particular sequence based on a user action in a user interface. Since the Front-End callback sequence file implements the LoginLogout callback , any changes you make to the LoginLogout callback you must also make in the Front-End callbacks. You can implement any similar features that do not depend on a Process Model as Front-End callbacks.

How to Use a Front-End Callback

The FrontEndCallbacks.seq file contains sequence files that TestStand can call from user interfaces. You can add any additional sequences you want to this file so you can use or modify the existing callback. After you create the desired behavior, you must call the Front-End callback by calling the Engine.CallFrontEndCallbackEx method, which you can use to pass a sequence name and a list of parameters to the executing sequence file. You can also call the LoginLogout Front-End callback using the ApplicationMgr.Login and ApplicationMgr.Logout methods.

Summary

Callbacks provide useful functionality you can use to modify TestStand behavior based on certain events. Proper use of callbacks can lead to a more robust test station and more maintainable code, and provides an easy way to add many powerful features to your test station.

Was this information helpful?

Yes

No