MATLAB Digest - May 2005

Simplify Instrument Communication: Using Instrument Drivers with the Instrument Control Toolbox

Instrument drivers simplify instrument control and communication for test and measurement application developers. These drivers hide the obscure syntax of low-level instrument messaging and often combine multiple command and/or query operations into a single function call. Some instrument driver standards offer additional benefits, such as the ability to swap instruments with minimal changes to application code.

The Instrument Control Toolbox 2 introduces support for two industry-standard driver formats provided by many instrument manufacturers:

Interchangeable Virtual Instruments (IVI) drivers
VXI plug&play drivers

In addition, the toolbox supports stand-alone MATLAB instrument drivers that do not require additional software or drivers to communicate with an instrument. These drivers are available on MATLAB Central (you can also create them yourself).

This article will examine some standard and advanced techniques for working with instrument drivers using the Instrument Control Toolbox. Although we focus primarily on VXI plug&play drivers for the purpose of examples, the sample code available on MATLAB Central includes functions related to IVI and stand-alone MATLAB instrument drivers.

Instrument Drivers in the Toolbox

The Instrument Control Toolbox still provides direct access to hardware interfaces such as GPIB, VXI, and network protocols such as TCP and UDP for ASCII and binary read and write commands. For certain applications, such as streaming data over a network, using these interfaces continues to be the best solution. In addition, this support is important for stand-alone MATLAB instrument drivers that we describe later in this section.

Follow these two steps to use a VXI plug&play or IVI driver in the toolbox:

Download and install the driver from the instrument manufacturer.
Create a MATLAB instrument driver wrapper from the manufacturer's driver.

This wrapper does not replace the original instrument driver. It is simply a lightweight layer that maps the information in the instrument driver to a variable you use in MATLAB.

In some situations an industry-standard driver may not be available for a particular instrument model. In such cases, you can create a MATLAB instrument driver that is more than just a wrapper and instead handles all the instrument communication. The stand-alone MATLAB instrument driver uses the low-level hardware interface objects in the toolbox for serial, GPIB, VXI, TCP, and UDP to handle the communication. Several examples of stand-alone MATLAB instrument drivers are installed with the toolbox.

In the next few sections we will walk through the basic steps of using a VXI plug&play driver. This process is very similar to using an IVI driver.

Installing a VXIplug&play Driver

To begin, install a VXI plug&play driver provided by the instrument manufacturer. In this example, we will use the Agilent AGE364XA driver for the E3648A DC Power Supply. Most manufacturers provide a standard installer package for their drivers—simply follow the instructions in the installer.

To verify the driver is installed and available in MATLAB, use the instrhwinfo function. The instrhwinfo function takes an optional argument, which can be a type of instrument driver. For example, for VXI plug&play drivers the argument is

driverinfo = instrhwinfo('vxipnp'); driverinfo =
InstalledDrivers: {1x8 cell} VXIPnPRootPath: 'C:\VXIPNP\WINNT'

The output of the function is a structure with two fields. The VXIPnPRootPath field identifies the main VXI plug&play install path. The InstalledDrivers field lists all of the VXI plug&play drivers that are installed in the root path. When a driver is correctly installed it displays in this field, for example

driverNames = driverinfo.InstalledDrivers driverNames =
Columns 1 through 6 'AG5462XX' 'AG875X' 'AGE364XA' 'VTVM1548' 'VTVM2716' 'VTVM48C' Columns 7 through 8 'ri1260' 'rssmiq'

On this machine, there are eight VXI plug&play drivers including the AGE364XA we will use in our example. For additional information on a particular driver, use the instrhwinfo function with the driver name as an additional argument

instrhwinfo('vxipnp', 'AGE364XA') ans = Manufacturer: 'Agilent Technologies' Model: 'Agilent Technologies E364XA' DriverVersion: '1.0' DriverDllName: 'C:\VXIPNP\WINNT\bin\age364xa_32.dll'

Creating the MATLAB Instrument Driver Wrapper

After installing the driver, you make the MATLAB instrument driver wrapper using the makemid function. Once the wrapper is created, you can use it any time you want to use the driver—you do not need to create it again.

makemid('AGE364XA');

By default, makemid will create a new file with the same name as the underlying VXIplug&play driver along with the extension .mdd. You can also use a custom name for the newly created wrapper.

makemid('AGE364XA', 'MyPSDriver');

Using this feature, you can create multiple wrappers for the same driver. We will see how this can be useful when we look at customizing the MATLAB instrument driver wrapper.

Using the Driver in MATLAB

All MATLAB instrument drivers, regardless of whether they are stand-alone or wrap an underlying manufacturer's driver, are used to instantiate an icdevice object in MATLAB. This object is a MATLAB variable that has a set of properties and methods for communicating with the instrument.

Some properties and methods are common across all objects independent of the driver type and instrument model, for example, the driver name and connect/disconnect methods. In addition, the object will have properties and methods that are unique to the instrument based on the information in the driver. In the following example we will create an icdevice object and connect to the instrument, which is connected to the computer through a GPIB interface with a primary address 6.

deviceObj = icdevice('MyPSDriver', 'GPIB0::6::INSTR');

connect(deviceObj);

You can view some basic information about the icdevice object and the associated driver and instrument by looking at the icdevice object’s display.

display(deviceObj) Instrument Device Object Using Driver : Age364xa

Instrument Information Type: VXIPnPInstrument Manufacturer: Agilent Technologies Model: Agilent Technologies E364XA Driver Information DriverType: MATLAB VXIplug&play DriverName: Age364xa DriverVersion: 1.0 Communication State Status: open

For a detailed look at the properties and methods at the root level of the object, use the get and methods functions.

get(deviceObj) ConfirmationFcn = DriverName = Age364xa DriverType = MATLAB VXIplug&play InstrumentModel = Interface = 1.12356e+006 LogicalName = Name = VXIPnPInstrument-Age364xa ObjectVisibility = on RsrcName = GPIB0::6::INSTR Status = open Tag = Timeout = 10 Type = VXIPnPInstrument UserData = [] VXIPNPINSTRUMENT specific properties: Application = [1x1 icapplication] Display = [1x1 icdisplay] Driverstatus = [1x1 icdriverstatus] Drivertimeout = [1x1 icdrivertimeout] Error = [1x1 icerror] Measure = [1x1 icmeasure] Passthrough = [1x1 icpassthrough] Source = [1x1 icsource] Synchronization = [1x1 icsynchronization] Utility = [1x1 icutility]
methods(deviceObj) Driver specific methods for class icdevice: dodelay

Most of the instrument functionality is typically contained below the root level of the object in groups related to specific functionality. These groups are properties of the object and have their own properties and functions. The following code examines the methods of the Application group for this driver.

groupObj = get(deviceObj, 'Application');

methods(groupObj)

Driver specific methods for class icapplication: outputvoltcurr readoutputstatus stepvoltagerange

Often, the default method names are somewhat vague or condensed. The instrhelp function, called on the object with a property or method name, returns help information that is contained in the driver file.

instrhelp(deviceObj.Application, 'outputvoltcurr') This function programs the output current level, the output voltage level, and enables the output.

Executing a method on the object is very similar to using the COM interface in MATLAB. The invoke method is used. For example

invoke(groupObj, 'outputvoltcurr', 5, 1);

will set the voltage level to 5V and the current limit to 1A and enable the output. You can find additional information on group objects, getting and setting properties, and invoking methods in the toolbox documentation.

Advanced Techniques: Modifying the MATLAB Instrument Driver Wrapper

One of the more powerful features of the instrument driver support in the toolbox is the ability to alter the MATLAB instrument driver wrapper that transforms the information in the original manufacturer's driver into the object you see and use in MATLAB. This can be useful if you need to

Remove instrument functions or properties from a driver. Even if you do not have access to the source code for the original driver, if you remove them from the MATLAB instrument driver wrapper, they will not appear in MATLAB. This may be useful in a laboratory or manufacturing setting where accessing the wrong functionality could damage your components.
Change limits on instrument properties. Many instrument properties have default limits, such as a power supply that can output 0–24 volts. You can artificially reduce this limit in the MATLAB instrument driver layer without access to the source code for the original driver. Modifying the limit in this way can prevent unintentional damage to components. Any application in MATLAB that uses the modified MATLAB instrument driver will not be able to exceed the limits that you impose.
Accommodate deficiencies in drivers. If a driver has any errors or deficiencies, for example, applying incorrect scaling to waveform data, you can compensate for this in the MATLAB instrument driver layer. Rather than working around this problem in every MATLAB function that uses that driver function, you can fix it once in the MATLAB instrument driver.
Add your MATLAB analysis to the instrument driver. You can incorporate your MATLAB analysis into the MATLAB instrument driver, making it accessible to anyone using your driver. This can be as simple as adding additional waveform measurement functions to a low-end oscilloscope that does not have a full suite of built-in measurements, or as involved as adding complex custom analysis code.

Editing the MATLAB Instrument Driver

The MATLAB Instrument Driver Editor (MIDEdit) is a graphical user interface for editing MATLAB instrument drivers. Provided with the Instrument Control Toolbox, MIDEdit is accessible from the Start menu or using the midedit function at the command line. Figure 1 shows MIDEdit after we open the MyPSDriver driver file that we created.

Figure 1. MIDedit with MyPSDriver open. Click on image to see enlarged view.

We will start with a simple improvement to the driver wrapper. The Instrument type is set to VXIPNPInstrument (Figure 1) because the original VXI plug&play driver does not contain information on the specific instrument class the driver supports. We can fix this by selecting one of the defaults from the drop-down list, as seen in Figure 2, or by entering our own custom type.

Figure 2. Selecting an instrument type. Click on image to see enlarged view.

After saving the driver, if we move back to the command line and create a new icdevice object based on the updated driver, we can see our change in the basic display.

deviceObj = icdevice('MyPSDriver', 'GPIB0::6::INSTR') Instrument Device Object Using Driver : Age364xa

Instrument Information Type: DC Power Supply Manufacturer: Agilent Technologies Model: Agilent Technologies E364XA Driver Information DriverType: MATLAB VXIplug&play DriverName: Age364xa DriverVersion: 1.0 Communication State Status: closed

Next, we expand the tree on the left side of the editor and look at the functions in the Application group (Figure 3).

Figure 3. Application group function list. Click on image to see enlarged view.

If we select the outputvoltcurr function used earlier, the detail panel on the right will update to show the MATLAB code that was created to call that function in the VXI plug&play driver (Figure 4).

Figure 4. MATLAB function definition in the detail panel. Click on image to see enlarged view.

Although we cannot cover everything that is happening in the code in this article, we will highlight a few important points. The function has a standard MATLAB function line that defines the function name and arguments. The next two lines of code prepare for the call to the underlying driver. Line 6 is the actual call to the VXI plug&play driver. If you wanted to manipulate the input arguments before calling the underlying driver, you could insert custom MATLAB code before line 6. Similarly, if this function returned data, you could change the output after line 6 as well.

Figure 5. Modifying the driver to limit the voltage level. Click on image to see enlarged view.

In this example we modified the driver to impose a limit on the output voltage level of 4 volts (Figure 5). (We save this modified driver as “MyPSDriver2” in case we want to access the original driver.) If we create a new icdevice object using this modified driver, we see the following result when attempting to set the output voltage to 5 volts, even though the original VXI plug&play driver would have allowed up to 20 volts.

deviceObj = icdevice('MyPSDriver2', 'GPIB0::6::INSTR');;

connect(deviceObj)

groupObj = get(deviceObj, 'Application');

invoke(groupObj, 'outputvoltcurr', 5, 4)

??? Error using ==> icgroup.invoke The output voltage cannot be greater than 4 volts.

Additional Examples

The example code for this article is available on MATLAB Central. In addition to the two driver files created for this article (MyPSDriver.mdd and MyPSDriver2.mdd) you will find example MATLAB functions that use both VXI plug&play and IVI drivers, as well as pointers to several stand-alone MATLAB drivers.

Summary

Instrument drivers simplify instrument control and communication for test and measurement application developers. The Instrument Control Toolbox 2 supports both the IVI and VXI plug&play industry standard formats commonly used by instrument manufacturers. The toolbox also supports stand-alone MATLAB instrument drivers (available on MATLAB Central) or you can create drivers yourself. The MATLAB Instrument Driver Editor enables you to modify instrument drivers to prevent instruments from unintentionally damaging components, to accommodate driver deficiencies, and to incorporate custom analysis routines directly into the drivers.