Creating Step Types - A Tutorial Using the CVI Standard Prototype Adapter

This tutorial demonstrates how to make a custom step type using the CVI Standard Prototype Adapter. Before starting, it is important to differentiate between the terms step and step type. A sequence developer creates (instantiates) steps of a particular Step Type in a sequence file. This is analogous to creating a variable of an integer or boolean data type. Sometimes, the default Step Types do not provide the necessary features for a test application. TestStand allows you to create custom step types for your application.

The step type that you will create in this tutorial is similar to the Numeric Limit Test step type, with a couple exceptions.

1. The code module must return a numeric array to a step property, Step.Waveform.
2. A Post Substep is used to evaluate the status rather than the Status expression.
3. This step type contains a custom step property, Step.Result.RMSvalue, which you will display in the report.

Setting Up the Example
Create a new directory named Waveform in your TestStand\Components\USER\StepTypes directory. Copy the contents of this zip file to your new directory. This zip file contains a LabWindows/CVI project, WaveformStepType.prj and WaveformStep.dll. EditLimitsDialog.c is the source to display an edit dialog. SetStatus.c is the source to set the step status. GetWaveform.c is the source for the step’s code module. The GetWaveform function displays a dialog and creates a sinusoidal waveform which is returned to the step property, Step.Waveform.

Creating the Waveform Step Type
1. In the sequence file window, click the Type Palette button in the toolbar or select View>>Type Palette. If you create the custom step type in the Type Palette, it will be available in all sequence files. You can also create a step type in the Sequence File Types view by selecting Sequence File Types in the pull down View ring of the Sequence File window. However, a step type that is created in a Sequence File Types view will only be available in that sequence file. Of course, you can copy that step type to the Type Palette or to other sequence files.

2. In the Type Palette, right-click in the right pane of the Step Types tab and select Insert Step Type. Name this step type, “Waveform” as shown below. 3. Under the Waveform step type, create a new container property named Limits. Under the Limits container, create two new numeric fields. Name them High and Low as shown below. You can assign initial values to Limits.High and Limits.Low if you like. 4. Under the Waveform step type, create a new numeric array property. Use the default values in the Array Bounds dialog. Name the array Waveform.

5. Under the Waveform step type, create a new string property. Name the string property Comp. Give the string property a default value of “GELT” which corresponds to Greater than or Equal – Less Than. This matches the comparison that is done in the SetStatus function.
RMSvalue >= lowLimit && RMSvalue < highLimit
The Comp property will be used to evaluate the precondition when the report includes the high and low limits.

6. Under the Result container, insert a new numeric property and name it RMSvalue. When the step executes, the TestStand engine automatically copies any step properties under the Result container to the ResultList. The report generation sequence creates the report from the entries in the ResultList. Later in this tutorial, you will modify the report generation sequence to include RMSvalue in the report.

7. Your new step type properties should appear as shown below. 8. Save the Type Palette.

Configuring the Waveform Step Type Properties
1. In the Type Palette, right-click on the Waveform step type in the right pane and select Properties from the context menu. This displays the Step Type Properties dialog. The Step Type Properties dialog box is for configuring the properties, code modules, and default actions for a step type and is explained in detail in Chapter 9 of the TestStand User Manual. You will now examine several tabs and configure the properties for the new step type.

General Tab
This tab contains the default name, description, icon, and adapter type associated with a step type.

2. In the Default Step Name Expression control, enter “Waveform”, as shown below. When a step is created from this custom step type it will have this default name, which the sequence developer can then change.
3. In this tutorial, leave the Step Description Expression as “%adapter”. When a step of this step type is created, the description will be the name of the code module that the step calls.

4. If you designate an adapter for this step type, any steps created from this step type can only use the specified adapter. If you designate an adapter, you could further restrict the step type to call a specific code module of your choice. Under the Disable Properties tab, you can check Specify Module which prevents sequence developers from specifying a different code module. If you don’t want to call any code module from your step type, designate the None adapter.

Menu Tab
5. Click on the Menu tab. The menu tab specifies the text that appears in the Insert Step submenu when a step is inserted into the sequence file. Enter "Waveform" in the Item Name Expression control as shown below.

6. The Menu tab contains other controls. When a string is placed in the Submenu Name Expression control, the value of Item Name Expression appears under a submenu in the Insert Step context menu. The Singular Item Name Expression control on the Menu tab replaces the submenu name if only one item exists under the submenu.

If you examine any of the default TestStand step types, you will notice that the function ResStr() is used in the expression controls on the General and Menu tabs. The ResStr() function looks up resource strings in language resource files. You can easily translate the resource files to another language, i.e. German, and all of the displayed strings will then appear in German.

Substeps Tab
7. Click on the Substeps tab. This tab specifies substeps for the step type. It is possible to call code modules as Pre Steps and Post Steps for each step type. This is not the same code module that can be specified for each step instance. The sequence developer cannot customize the substeps for a particular step. If a Pre Step or Post Step is specified, that code module is called at every execution in every instance of the step type. During execution, TestStand calls the Pre Step substep before calling the step module and the Post Step substep after calling the step module. You can use any of the TestStand adapters when specifying code modules in the Substeps.

8. The default step types use the Status Expression to set the step status at runtime. In this tutorial, you will use the Post Substep to set the step status of the Waveform step type. In the Post Step area, click on the Create button. In the Create New Substep dialog, select the C/CVI Standard Prototype Adapter and click OK.

9. In the Post Step area, click Specify Module. Click the Browse button and browse for WaveformStepType-CVIAdapter.dll in the TestStand\Components\USER\StepTypes\Waveform directory. If prompted, select Use a Relative Path for the file shown above, and click OK to return to the Edit C/CVI Module Call dialog. Select SetStatus as the Function Name and check the Pass Sequence Context checkbox. Press OK to return to the WaveformStepType Container, Type Definition Properties dialog.
10. The SetStatus function gets Step.Waveform and estimates the AC content of the waveform. The RMS Value is stored in the step property, Step.Result.RMSvalue. The RMS Value is compared to the high and low limits. If the RMS Value is within the high and low limits, the status is set to “Passed”, otherwise the status is set to “Failed”. Look at the source code for SetStatus().

11. In the Waveform Step Type Properties dialog, click on Create in the Edit Step area. In the Create New Substep dialog, select the C/CVI Standard Prototype Adapter and click OK.

12. The Menu Item Name Expression control specifies the text that appears on the Edit Limits button in the Properties dialog for the step type. Change this text to “Edit Limits”.

13. Click Specify Module. Click the Browse button and browse for WaveformStepType-CVIAdapter.dll in the TestStand\Components\USER\StepTypes\Waveform directory. If prompted, select Use a Relative Path for the file shown above, and click OK to return to the Edit C/CVI Module Call dialog. Select EditLimits as the Function Name and check the Pass Sequence Context checkbox.

14. The EditLimits function displays the dialog shown below. All edit substeps must be modal to the sequence editor.




Disable Properties Tab
15. The Disable Properties tab allows you to prevent sequence developers from modifying certain step properties. In this example, you will prevent sequence developers from setting a Status Expression because that would override the status that is set in the SetStatus function. Check Status Expression in the Disable Properties tab.

16. Finally, click OK to close the Waveform Step Type properties dialog and save the Type Pallette.

Creating a Step from the Waveform Step Type
1. Create a new sequence file. Set the Adapter Selector ring to C/CVI Standard Prototype Adapter and insert a new step of the Waveform step type.

2. Select Edit Limits and ensure that it works as you expect. Set the High Limit to 1.0 and the Low Limit to 0.0.

3. Click the Browse button and browse for WaveformStepType-CVIAdapter.dll in the TestStand\Components\USER\StepTypes\Waveform directory. If prompted, select Use a Relative Path for the file shown above, and click OK to return to the Edit C/CVI Module Call dialog. Select GetWaveform as the Function Name and check the Pass Sequence Context checkbox.
4. GetWaveform will pass a sinusoidal waveform to Step.Waveform. At runtime, the user specifies the amplitude and number of cycles for the waveform.

5. When you run your sequence, the status will be “Passed” if the RMS Value is greater than or equal to the Low Limit and less than the High Limit. The report includes the limits because the default process model calls the Include Limits in Results step. The report also includes the comparison property, Comp, because the default process model calls Include Comparison Type in Results. However, Step.Result.RMSvalue is not included in the report. You will include this in the next section.

Including Step.Result.RMSvalue in the Text Report
In this section, you will modify the text report generation sequence in the TestStand process model. If you don’t want to modify the process model, you can use the ModifyReportEntry callback. Refer to the solution to this tutorial which uses the ModifyReportEntry callback.

1. Select Configure>>Report Options. In the Select a Report Generator for Producing the Report Body section, select Sequence. As you may know, the report body may be generated in either a DLL or a sequence, but this tutorial does not discuss modifying the DLL. If you want to ensure that the report body is always generated with a sequence, you may use a ReportOptions callback. Refer to the solution to this tutorial to see how that is done. Ensure that the Report Format: control is set to ASCII Text File. Finally, close the Report Options dialog.

2. Do not modify the default process model, but make a copy of the default process model and modify the copy. To copy the process model use Windows Explorer and browse to TestStand\Components\NI\Models\. Select and copy the TestStandModel folder. Browse to the directory, TestStand\Components\USER\Models\. If the TestStandModel directory already exists, delete it or move it to a temporary directory. Paste the TestStandModel folder that you just copied. By default, TestStand will use files from the Components\USER directory before those kept in the Components\NI directory.

3. With the sequence editor, open the sequence file ReportGen_txt.seq in the TestStand\Components\User\Models\TestStandModel\ directory. This sequence file generates the text report. Select PutOneResultInReport from the sequence file View selector ring.

4. Each time the PutOneResultInReport sequence executes it adds a single step’s result entry to the report. For every step result in the main sequence, this sequence is executed. Click the Parameters tab to see that the details of the report are passed in the Result container, shown below. Data is placed into this container during execution. Each Statement step (e.g. Add Status step) in this sequence concatenates a string to the ReportEntry string. After this sequence executes, the completed ReportEntry parameter is returned to the calling sequence.


5. Click on the Main tab of the sequence window. Right-click on the Add Numeric Measurement step and insert a Statement step. Name this new step Add RMS Value.

6. Enter the Expression for the Add RMS Value step as follows:
7. For the Add RMS Value step, set the Preconditions as follows. Click on the Insert New Expression button and set the expression as shown below:
This precondition ensures that this step executes only if Parameters.Result.RMSvalue exists and the user has selects the Include Measurements report option.

8. Notice that the Preconditions for the Add High Limit and Add Low Limit steps refers to the Comp step property. This is the primary reason that you added the Comp property to the Waveform step type. If you didn’t add the Comp property, the preconditions for Add High Limit and Add Low Limit wouldn’t have allowed these steps to execute and include the limits in the report.

9. Save ReportGen_txt.seq.

10. When you run your new sequence file, you should see RMS Value included in the text report.

Summary
You may refer to the solution in the Solution directory. The sequence file included in the solution uses a different name for the step type. If you want to use this step type in other sequence files, you can select Sequence File Types from the View ring, and copy the step type to your Type Palette.

You can apply the concepts used in this tutorial when you create your own step types. You can use the step type template example to help when making your own step types. Refer to the examples in the example programs database.