Purpose

This example demonstrates how to implement a TestStand HP34401a instrument control step type in LabWindows/CVI. You can use the step type to access commonly-used functionality of the HP34401a multimeter from a TestStand sequence.

Example File Location

<TestStand Public>\Examples\Interfacing with Hardware\Instrument Control Step Types - HP34401a\Instrument Control Step Types - HP34401a.seq

Highlighted Features

TestStand step types

Major API

N/A

Prerequisites

You must install the HP34401a IVI instrument driver from the Instrument Driver Network at ni.com/devzone/idnet before running this example.

How to Use This Example

This example demonstrates optional features you can include in step types you create. You can decide which, if any, of the following features to support in step types you create:

• Tabbed editing dialog box
• Multiple selectable run-time operations
• Configuration settings you can specify with TestStand expressions
• Groups of configuration settings you can load or save to a TestStand custom data type, which you can then execute according to a group of settings you store in a local variable or receive as a sequence parameter
• Instrument driver session obtained from the Session Manager to maximize the sharing of the instrument handle between steps and other code modules
• Multiple language string support

Installation Issues

Step types might depend on files such as code modules, icon files, or string resource files. For TestStand to locate these files, the files must reside in specific directories.

• Code Module Files (.dll, .vi, and so on)—Place step type code module files in a subdirectory you create in the <TestStand Public>\Components\StepTypes directory. TestStand finds code modules you place in this directory because the TestStand default search paths include all directories under the <TestStand Public>\Components directory. Although this example does not install its code module, HP34401aStepType.dll, to the <TestStand Public>\Components directory, TestStand can find the step type code module because the step type specifies a relative path from the <TestStand Public>\Examples\Interfacing with Hardware\Instrument Control Step Types - HP34401a directory.
• Icon Files—Place icon files for step types in the <TestStand Public>\Components\Icons directory. TestStand loads icons from this directory and the <TestStand>\Components\Icons directory. TestStand installs the icon for this example to <TestStand Public>\Components\Icons\NI_Examples\Example_HP34401a.ico.
• String Resource Files—Place string resource files you create in the <TestStand Public>\Components\Language\<language>\TestStandExamples.ini file.

The HP34401a_StepTypeExample.seq example sequence file contains the example step type definition. You can store step type definitions you create in any sequence file, and you can add a step type to a new or existing TestStand type palette file. You can install a type palette file on another computer by placing the file in the <TestStand Public>\Components\TypePalettes directory. You must prefix the filenames of the type palettes you install with Install_. At startup, TestStand searches the TypePalettes directory for type palette files with the Install_ prefix. When TestStand finds a palette file to install and the base filename is not the same as any existing palette file, TestStand removes the Install_ prefix and adds the palette to the palette list. When TestStand finds a palette file to install and the base filename is the same as an existing palette file, TestStand merges the types from the Install_ prefixed file with the existing palette file and deletes the Install_ file.

Step Type Implementation

Complete the following steps to implement a step type.

1. Create a new step type in the Types window. The example step type is named HP34401aStepType, which you can view in the Types window for the Instrument Control Step Types - HP34401a.seq file.
2. Determine the data requirements for the step. Analyze the data inputs and outputs the step requires at run time.
3. Create input properties. Create a step subproperty for each data input. Select the appropriate data type and set the default value. The example step type uses the following data input properties: Step.LogicalNameStep.OperationStep.SettingSourceStep.Configuration.MeasFunctionStep.Configuration.RangeStep.Configuration.ACMinFreqStep.Configuration.ACMaxFreqStep.Configuration.ResolutionStep.Configuration.TriggerSourceStep.Configuration.TriggerDelayStep.Read.DestStep.Read.TimeoutStep.SelfTest.DestStep.SelfTest.Message
4. Create output properties. Create a step subproperty for each data output. If you want an output property to automatically appear in the sequence result list, create the output property under the Step.Result property. The example step type uses the following data output properties: Step.Read.DestStep.SelfTest.DestStep.Result.SinglePointStep.Result.SinglePoint.TypeStep.Result.SinglePoint.ChannelStep.Result.SinglePoint.Measurement
5. Designate an adapter, if appropriate. If the step is not designed to call user-written code, enable the Designate an Adapter option on the General tab of the Step Type Properties dialog box and select the <None> Adapter. The example step type does not require you to write any code to access the instrument. Thus, the example step type designates the <None> Adapter as the appropriate module adapter.
6. Define run-time functionality. Create a Pre- or Post-Step substep to call a code module you write. Each instance of the step type calls the code module when the step executes. The code module call is transparent to the user. If the step type calls user-written code, define a Pre- or Post-Step substep, depending on whether you want to call the code module before or after the step executes. If the step type does not call user-written code, you can use a Pre- or Post-Step substep to call the code module. The example step type defines a Post-Step substep that calls the ExecuteHP34401aStep DLL function when an instance of the step type executes. The ExecuteHP34401aStep DLL function accepts a SequenceContext parameter, which the function uses with the TestStand API to access the properties of the step. You can also define the function to accept a separate parameter for each step property the function uses.
7. Define an editing dialog box. Configure the Edit substep to call a code module that launches the dialog box, which shows step property values in a controlled and organized manner. When the user finishes editing, the dialog box stores the edited property values in the step and marks the sequence file that contains the step as modified. The Edit substep for the example step type calls the EditHP34401aStep DLL function to launch a dialog box in which the user selects the action the step executes at run time and configures the parameters the action requires. The ExecuteHP34401aStep DLL function accepts a SequenceContext parameter, which the function uses with the TestStand API to access the properties of the step. You can also define the function to accept a separate parameter for each step property the function uses.
8. Configure built-in step type properties. Use the Step Type Properties dialog box to configure the default values of built-in step type properties and other settings. Typically, you configure the following settings for a step type:
   • Designate an Icon—If the step does not call user-written code, select an icon that represents its functionality. You can select from the icon files in the <TestStand Public>\Components\Icons and <TestStand>\Components\Icons directories. If the step calls user-written code, do not designate an icon. The step displays the icon that represents the adapter that calls the user-written code. The example step type specifies <TestStand Public>\Components\Icons\NI_Examples\Example_HP34401a.ico as its icon file.
   • Default Step Name Expression—The default step name expression determines the name the sequence editor assigns to a new instance of the step type. You can use the ResStr expression function in the default name expression to specify a name that changes depending on the selected language. The example step type specifies the following expression as its default step name expression: ResStr("HP34401_STEP_TYPE_EXAMPLE", "DEFAULT_NAME")If the step type does not need to account for the selected language, you can enter a default step name in quotes, such as "HP34401a Step".
   • Step Description Expression—The step description expression determines the description that Description column on the Steps pane and the Description control on the General panel of the Properties tab of the Step Settings pane show for the step. The description expression can refer to and show the values of step properties. You can use the ResStr expression function in the description expression to specify a description that changes depending on the selected language. The example step type uses a lengthy expression to vary the description depending on the step configuration and the selected language. If the step type description does not need to account for the step configuration or the selected language, you can enter a fixed description in quotes, such as "HP33401a DMM Instrument Control".
   • Menu Item Name—Use the Item Name Expression control on the Menu tab of the Step Type Properties dialog box to specify the item name expression for the step type. The expression determines the name of the menu item in the Insert Step submenu that inserts an instance of the step type into a sequence. You can use the ResStr expression function in the item name expression to specify an item name that changes depending on the selected language. The example step type specifies the following item name expression: ResStr("HP34401_STEP_TYPE_EXAMPLE", "MENU_NAME")If the menu item does not need to account for the selected language, you can enter an item name in quotes, such as "HP34401a".
   • Other Items—Depending on the step type, you can also use the following features. The example step type does not configure any other step type settings.
     • Configure the default values of built-in properties, such as the run options or loop options.
     • Use the Disable Properties tab of the Step Type Properties dialog box to prevent users of the step type from editing the values of built-in properties you select.
     • Specify code templates to assist the user in creating code modules that you designed the step type to call.

Suggestions for Implementing Instrument Control Step Types

To increase performance, do not initialize and close the instrument driver each time the step executes. Instead, use DLL global variables or another method to maintain the instrument instance between steps.

One option is to use the Session Manager to initialize and share instrument driver handles between multiple instances of the step type. The example step type obtains an instrument session from the Session Manager and attaches the instrument session to the current TestStand execution object by dynamically creating an ActiveX reference subproperty. In this way, the driver for the session stays open for the duration of the execution and all steps that can run during the execution share the same driver instance handle. You can also use the Session Manager to obtain a list of available instrument connections from which the step user can select.

To increase the flexibility of the step type, allow the user to specify the values of important settings with an expression. The user can then store the setting value in a variable and alter it at run time. The example step type allows the user to specify almost all setting values with an expression.

For groups of related settings, consider allowing the user to load or store the values in a variable of a custom data type that you define. The user can then specify a group of settings in a variable and pass the variable as a parameter to subsequences that contain the steps that apply the setting values. The example step type allows the user to specify a setting source variable to which the step loads or stores the settings for the selected operation.

Suggestions for Implementing Step Type Editing Dialog Boxes in LabWindows/CVI

The <TestStand>\API\CVI\TSUtil.fp instrument driver contains the following functions to help create a step type editing dialog box:

• If the text labels that appear on the step type editing dialog box must appear in the selected language, call the TS_LoadPanelResourceStrings function to load the language-specific dialog strings.
• Call the TS_StartModalDialog and TS_EndModalDialog functions to ensure that the editing dialog box is modal to the sequence editing application.
• Call the TS_ExprCtrl_Create function to convert a string control into an expression editing control.
• Call the TS_ExchangePropertyAndCtrlVals function to transfer values between step properties and dialog box controls.
• Call the TS_IncSequenceFileChangeCount function if the editing dialog box modifies the step.