Integrating VXI Plug&Play Drivers with PAWS

The WCEM Wizard

The WCEM Wizard helps you create the interface layer of the WCEM that will be used to call the instrument driver functions for all your plug&play controlled instruments, as well as other ‘C’ controlled devices.

To create the WCEM interface, first select the instrument, in this case DMM. Next select the FNC number you want to create interface functions for. In our static description FNC 1 is DC SIGNAL / VOLTAGE. Third you select the single action verb you want to implement. Once you select a single action verb a list of modifiers for that verb/FNC will appear. You create an interface function or add a modifier to an exiting function by clicking on the modifier, and then click ‘Add’. If you want to add all the available modifiers for that verb/FNC, then click on

‘Add All’.

Note that the measured characteristic for a verb/FNC will show up as <modifier> max, and <modifier> min. This allows you to pass the range from the ATLAS sensor statement, or pass the driver function the maximum expected signal value.

The single action verbs available for analog sensor devices are (listed by function, not alphabetically):

Setup	The setup verb is the first step of all multiple action sensor statement. All modifiers are available in setup.
Connect	The switching action. This is called after setup, but the call should be to the switch driver, not the DMM.
Close	This function allows you to close any internal relays, or enable an output of a source signal.
Init	The init function triggers a measurement for a sensor statement.
Fetch	The fetch verb retrieves a measured value for an analog sensor statement.
Open	This function opens any internal relays or disables an output for analog source statements.
Disconnect	The switching action. This function opens the system relays. It should make a call to the switch driver if your switch is WCEM controlled.
Reset	This function returns the instrument to it’s reset state. This function de-allocates the resource. After reset an instrument may be used by another ATLAS statement.
Status	Allows you to use the SetFault() macro to assert an interrupt back to the Device Database where it can be processed by a Device Database macro.

You are not required to implement all of the single action verbs. For a sensor device you only need to implement the SETUP, FETCH, and RESET actions. For an analog source instrument you are only required to implement SETUP and RESET. The other single action verbs give you greater control over your instrument. And if you don’t implement an action, the ATLAS programmer can not use that single action verb in their ATLAS program.

Careful analysis of your system requirements will guide you in the right direction in deciding what functions to implement.

When you select to ‘Add’ a modifier when a function does not yet exist, a box will appear on screen prompting you to specify a name for the function or to accept the default name.

The default name is ‘do[inst name][FNC number][single action verb]. You are free to enter any name you like in this field. Once you add the function it appear in the ‘List of Interfaces’ on the Wizard. You then step through adding interface functions for all the single action verbs you wish to implement, and then proceed

to the next FNC number.

Figure 6 shows the first interface function, doDMM1Setup(), in the list of interfaces.

When you click on OK, the Wizard will create the source files Wrapper.c, Key.h,

Error.c, and DMM.c. They will appear in the PAWS Developer’s Studio project workspace in the ‘CEM Files’ folder.

The general functions of interface clear and device clear are added from the ‘General’ tab of the WCEM Wizard. All you need to do is check the box next to the function you want to add, and either accept the default function name or type in your own function name. When you click on ‘Apply’ or ‘OK’ the file ctlr.c will be created and added to the project.

These functions are called any time an ATLAS program is loaded or unloaded. You will make calls to all the plug&play instruments in your system and verify that they return a good status, and place them in a ready state.

Prior to building any of the files in the CEM you need to setup the WCEM environment. Selecting ‘CEM’ from the ‘Options’ menu accesses the WCEM options.

The first tab, ‘Options’, allows you to specify the output directory of the build process, any compiler options, and any linker options. Unless you have specific needs that require you to change or add to these lists, the defaults will be sufficient.

The ‘Files’ tab, as seen in figure 8, is used to setup the path names to search when

locating include files and library files. You also specify the names of any libraries to be included during the link phase.

For VXI plug&play drivers there are two directories you need to add to this list, and several files. In the ‘Include Path’ list, add the directory ‘c:\vxipnp\win95\include’, and in the library file list, add ‘c:\vxipnp\win95\<inst_directory>’, which in this example is: ‘c:\vxipnp\win95\hpe1412’. Remember that the ‘win95’ directory is only if you are using the WIN95 framework. If you are using a different framework, such as WINNT, examine your directory structure to be sure of the path name.

Unless you are using a different compiler and are sure about its usage, leave the ‘Compiler’ and ‘Linker’ fields alone. The ‘Include Path’ is where you will add the directories for include files, separated by semicolons. The same applies to the ‘Library Path’ field.

The ‘Objects/Libraries’ field is where you will add any libraries required for linking. You must add the import library for the visa32.dll, visa32.lib, and the import library for your plug&play driver, in this case hpe1412.lib.

At this point we’ve done our homework and studied the instrument and understand how to program it, what ATLAS code will be used to call it, and have created a resource static description that accurately describes the nouns and modifiers that the instrument supports. Using the WCEM Wizard we created the interface to the instrument, and now we’re ready to make calls to the plug&play driver to control the instrument.

To facilitate this process we will use LabWindowsâ /CVI. This tool allows you to load the plug&play drivers function panel, and insert the call directly into your ‘C’ file, as well as declare any variables required by the function call.

The first step in this process is to start CVI and create a new project workspace. Next, to load an instrument, click on ‘Load’ from the ‘Instrument’ menu. When the file selection menu appears change directory to where your plug&play driver is installed, in this case ‘c:\vxipnp\win95\hpe1412’. Click on the .FP file and ‘OK’, and the plug&play driver will now appear under the instrument menu as shown in figure 9.

When you click on the entry for your instrument, in our case the HPE1412, the function panel tree for the instruments plug&play driver will appear. This will be used when you open the ‘C’ file created by the PAWS WCEM Wizard with CVI to insert function calls into the interface file.

The function panel is displayed in a tree format, with the initialize and close functions on the top level, just like in the plug&play specification architecture, with additional categories containing functions as shown in figure 10.

Figure 10 shows the function categories of ‘High Level Control…’, ‘Low Level Control…’, ‘Status…’, and ‘Utility…’. The options for the function panel viewer allow you to specify a flat list, meaning all functions will be shown in the same level, and you can also alphabetize the list.

The next step is to put add the instrument function calls. First, load the <instrument>.c file that was created by the WCEM Wizard into the CVI editor.

We need to add several #include statements to our ‘C’ file. First, add the header file for the plug&play driver, in this case ‘hpe1412.h’. You also need to add the visa data type header ‘visatype.h’. This contains the definitions of all the NI-VISA data types that are referenced in the plug&play drivers.

The programming technique used in this example for each WCEM interface function will be to:

• open a session to the instrument with the initialize function
• configure the instrument
• close the session to the instrument

To insert a function call in the CVI editor, place the cursor where you want the function call to go, and select the instrument from the ‘Instrument’ menu in the editor. The function panel tree will appear as previously seen in figure 10. The first step in to open a session to the instrument, so we will select the initialize function.

The format of the function panel provides a window or a control for each parameter required. Right clicking on the body of the function panel provides overall help on the function, including a brief description and the function prototype. Right clicking on a field or control provides help on the field.

The parameters for the initialize function allow you to perform an ID query and reset the instrument. The parameter ‘vi’ returns a ViSession handle to the instrument, passed by reference. This handle is used by other function calls to specify the hpe1412. The instrument description describes the type of controller and the logical address. This field is dependent on the controller you are using, so check your documentation for the specifics on the handle.

When you need to declare a variable for an argument to a function, such as the vi handle, or a status variable, or can do it right from the function panel. If you place the cursor in a field, you can select ‘Declare Variable’ from the ‘Code’ menu. The ‘Declare Variable’ window will appear on screen.

This feature will declare a variable of the correct type, and allows you to place the declaration at the top of the target file, or in the current function. In this example we are declaring a ViSession variable which will hold the handle to the hpe1412. As this will be referenced by all the functions it is placed at the top of the file as a static variable.

When you have declared all the variables and filled in all the fields on the function panel, you can insert the code into the source file by clicking on the toolbar icon or selecting ‘Insert Function Call’ from the ‘Code’ menu on the function panel. Figure 13 shows the ‘doDMM1Setup()’ call with the initialize call inserted. Note that the two variable declarations created by the function panel are inserted at the top of the file. The #include statements have been added for the required libraries. Also the string "GPIB-VXI0::24::INSTR" has been assigned as a #define constant. The string "GPIB-VXI0" implies this is a GPIB to VXI controller, number 0. The string "24" states that the Logical Unit Address of the DMM is 24, and the string "INSTR" states that this is an instrument. Again, this string is dependent on the type of controller, so check with your documentation.

Now we’ll fill in the remaining implementation details for this interface function. We need to place the DMM in DC Voltage mode, and set the range to the correct value. Under the low level function/configuration functions we find a function called ‘hpe1412_voltDcRang()’. This function sets up the DMM in DC Voltage mode, and configures the range. On the function panel for this function the voltage range is by default set by a slider control. If you click on the control, then go to the options menu you will find a selection called ‘Toggle Control Style’. This changes the control from a slider to a field where you can enter the variable name.

The setup interface function receives two arguments, the MaxVOLT and MinVOLT. These will be the high and low end of the VOLTAGE RANGE in the ATLAS statement. ATLAS determines the max and min values by value, not by magnitude, so we’ll need to compare the absolute values of the two variables to make sure we pass the greater of the two. This will protect against an ATLAS statement with a voltage range field ‘VOLTAGE RANGE –75.0 v to 1.0 V’. In this case the max value would be -1, and the min value would be –75. This would be a problem if we only passed the MAX value to the hpe1412 function. You would set the instrument to a 3.0 v range, when the max expected signal value is 75.0 volts.

You may also want to check the return values of each of the plug&play calls to insure that no errors occur. An easy method is to define a common error handling function that can be called after any function returns a code other than VI_SUCCESS. In this example there is an external function defined called PlugNPlayError(). This function would be placed in the file Error.c, and could be called by any function where a plug&play driver returns an error code. You can decide what the best method for processing errors is in your system. You may want to halt the RTS and display an error message so that the ATE maintenance engineers can troubleshoot the failure.

After configuring the DMM we close the session to the device. We place a call to the close function for the hpe1412 at the end of our interface function, and return with a zero(0) status. If you return a negative value, the Wrapper.c function that dispatched the call to doDMM1Setup() will call a default error handling routine and report a bus error for the device DMM. You may wish to use this default error reporting mechanism and just return a –1 when an error is detected in an interface function.

The completed interface function is shown in figure 14.

The only time you will not return 0 from an interface function is the fetch functions. In the fetch functions the RTS expects the return code to be the number of values returned. For an analog sensor like the DMM the return code from the fetch function should be a 1, informing the RTS that one value was returned. If you return a zero, the RTS will assume that no data was returned.