Introduction to IVI Instrument Drivers

Instrument drivers are high-level function libraries for controlling specific GPIB, VXI, serial instruments, or other devices. With an instrument driver, you can control an instrument without knowing the low-level command syntax or I/O protocol. IVI instrument drivers apply an attribute-based approach to instrument control to deliver better run-time performance and more flexible instrument driver operation.

An IVI instrument driver specifies each readable or writable setting on the instrument, such as the vertical voltage range on an oscilloscope, as an attribute. The IVI Engine works in conjunction with IVI instrument drivers to manage the reading and writing of instrument attributes. The IVI Engine tracks the values of attributes in memory and controls when instrument drivers send and read settings from instruments. By managing instrument attributes and mandating a standard structure for the internal driver implementation, the IVI Engine adds many features to instrument drivers, including the following:

• State caching—You can avoid sending redundant commands to the instrument as the IVI Engine skips duplicate attribute value settings.
• Configurable range checking—Range checking verifies that a value you specify for an attribute is within the valid range for the attribute. You can disable this feature for faster execution speed.
• Configurable status query—The status query feature automatically checks the status register of the instrument after each operation. You can disable this feature for faster execution speed.
• Simulation—You can develop application code that uses an instrument driver even when the instrument is not available. When in simulation mode, the instrument driver range checks input parameters and generates simulated data for output parameters.

Enable or disable these features by setting special attribute values in the instrument driver. For example, you can set the FL45_ATTR_RANGE_CHECK or FL45_ATTR_ attributes of the Fluke 45 digital multimeter driver to VI_TRUE to enable range checking or simulation. These types of attributes are called inherent IVI attributes because every IVI instrument driver has them and because these attributes control how the instrument driver works rather than representing particular instrument settings.

How IVI Instrument Drivers Work

This section presents a simplified view of how the IVI Engine and driver work together. The actual process involves additional steps that implement other powerful features. The rest of This section discusses the entire process in detail.

The key to the IVI architecture is the manner in which the IVI Engine controls the reading and writing of attributes to and from the instrument. The instrument driver contains callback functions that read and write instrument settings and range tables that specify the valid range for each instrument attribute. The IVI Engine accesses the range tables and invokes the callbacks at the appropriate times. For example, suppose the instrument driver exports an niScope_ConfigureChannel function that configures the vertical subsystem of an oscilloscope. Suppose that you pass 5.0 to the verticalRange parameter of the function. The driver and the IVI Engine work together to execute the following steps:

1. The niScope_ConfigureChannel function calls the Ivi_SetAttributeViReal64 function in the IVI Engine to set the value of the verticalRange parameter to 5.0 volts.
2. If the IVI_ATTR_RANGE_CHECK inherent attribute is VI_TRUE, the IVI Engine uses the range table for the vertical range attribute to determine if 5.0 volts is a valid value. If 5.0 volts is outside the valid range for your particular oscilloscope, the Ivi_SetAttributeViReal64 function returns an error code. In some cases, the IVI Engine uses the range table to coerce the value you request to within a valid range for the instrument, regardless of whether you enable range checking.
3. If the IVI_ATTR_CACHE inherent attribute is VI_TRUE, the IVI Engine compares the requested value of the verticalRange parameter, 5.0 volts, to the value currently in the IVI Engine cache for the attribute. If the cache value equals 5.0 volts, Ivi_SetAttributeViReal64 returns the success completion code immediately, eliminating a redundant command.
4. If the IVI_ATTR_SIMULATE inherent attribute is VI_TRUE, Ivi_SetAttributeViReal64 returns the success completion code immediately.
5. The IVI Engine invokes the Scope_VerticalRangeWriteCallback function in the instrument driver. The write callback function sends a command string to the oscilloscope to set the verticalRange parameter to 5.0 volts. The IVI Engine updates the cache value for the vertical range attribute to 5.0 volts.
6. If the IVI_ATTR_QUERY_INSTR_STATUS inherent attribute is VI_TRUE and the IVI Engine invoked Scope_VerticalRangeWriteCallback or the write callback for any other attribute, Scope_ConfigureChannel calls the check status callback in the instrument driver. The check status callback reads the status register of the oscilloscope to check if an error condition occurred.

Notice that steps 1 through 5 repeat for each parameter that you pass to Scope_ConfigureChannel. The following figure illustrates this process.

Programming with IVI Instrument Drivers

Note  You must call an Initialize and a Close function for every instrument session to properly allocate and free system resources.

Each IVI instrument driver presents a set of high-level functions for controlling an instrument. The high-level functions are sufficient for most applications. Although each IVI instrument driver exports SetAttribute and GetAttribute functions, you typically do not use them in high-level application programs. When you call the configuration functions in the instrument driver, you specify configuration settings. The configuration functions pass these settings to SetAttribute function calls. In many cases, it is necessary to send settings to the instrument in a particular order. The high-level configuration functions handle these order dependencies for you.

To use an instrument driver for a particular instrument, you must first initialize an IVI instrument driver session. When you initialize an IVI session, the IVI Engine creates data structures to store all the information for the session. Each IVI instrument driver exports two functions for initializing an IVI session: Prefix_init and Prefix_InitWithOptions, where Prefix is the instrument prefix for the driver. Both functions require that you identify the physical device. The functions give you the option of performing ID query and reset operations on the device. The functions also initialize the device for correct operation of subsequent instrument driver function calls.

The Prefix_InitWithOptions function has a string parameter in which you can set the value of inherent attributes such as IVI_ATTR_RANGE_CHECK, IVI_ATTR_SIMULATE, and IVI_ATTR_QUERY_INSTR_STATUS. Set these attributes through the Prefix_InitWithOptions function so that the settings are in effect during the initialization procedure. It is particularly important to use the Prefix_InitWithOptions function if you want to enable simulation. The initialization procedure usually attempts to interact with the physical instrument. If the instrument is not available, you must enable simulation in the call to Prefix_InitWithOptions to prevent the initialization from failing.

The Prefix_init and Prefix_InitWithOptions functions return an IVI session handle that you pass to subsequent calls to instrument driver functions. If you want to use the same instrument driver for a separate physical device, you must call Prefix_init or Prefix_InitWithOptions again to initialize a different IVI session.

Do not open multiple IVI sessions to the same physical device because two separate cached states may not be identical and one may be out of sync with the instrument. If you want to use the same instrument in different execution threads, you can do so by sharing the same session handle across multiple threads in the same program. IVI instrument drivers functions are multithread safe. In some cases, however, you might have to lock a session around a sequence of calls to an IVI instrument driver. For example, if you call a configuration function and then take a reading in one thread, you must prevent calls to instrument driver functions in other threads from altering the configuration between the two function calls in the first thread. Each IVI instrument driver exports the Prefix_LockSession and Prefix_UnlockSession functions for this purpose.