Driver Architecture and API Design

Doing so ensures consistency within the API itself and with the API for drivers for similar instruments.

Develop your instrument driver so it is consistent with the other VIs in your API and consistent with other instrument drivers that control similar instruments. Developing VIs that deviate from established conventions can detract from the user experience, even if your design improves usability, because users must relearn a user interface.

Follow these guidelines to create an instrument driver that provides a consistent API.

When designing your instrument driver API, make common functions obvious to users, but allow for advanced applications. Design your API so the most common instrument driver functions are the easiest for the user to find. Simple tasks should require only a few VIs and not include obscure controls. Less common use cases might require more VIs and more obscure controls. The API might require the user to read more documentation for information about more advanced functions.

• (Recommended) If VISA is not applicable as the I/O interface, use other NI communication technologies, such as TCP/IP, Telnet, .NET, and so on.

VISA (Virtual Instrument Software Architecture) is the I/O software standard for instrument drivers. VISA supports multiple bus-types in one instrument driver because VISA abstracts the low-level bus protocol differences. The function calls to interface with the instruments (the write calls, read calls, etc.) are the same regardless of your instrument bus type (VXI, GPIB, Serial, Ethernet, USB). LabVIEW and VISA are platform independent, which ensures your instrument driver can be used on all the platforms that LabVIEW supports. NI-VISA is the National Instruments' implementation of VISA.

Use other NI communication technologies if VISA is not applicable. For example, use DataSocket write and read functions to interface to an OPC Server. In this case, DataSocket write and read functions replace VISA write and read calls.

An instrument driver with a few high-level VIs might not give the user enough control of the instrument operation. An instrument driver with many low-level VIs might be too complicated for users unfamiliar with instrument rules regarding command order and interaction. Understanding the application needs of your customer can help you define the correct level of granularity for developing VIs as subVIs. Therefore, when using a measurement device such as an oscilloscope, the user typically configures the instrument once and takes many measurements. In this case, you should write high-level configuration VIs that group dependent or related configuration settings in a single VI. Users typically want to enable a stimulus system or initiate a measurement at a different point in their application. Therefore, VIs that Enable Output or Initiate Acquisition typically have one or no input parameters.

It is acceptable to include low-level VIs that allow users more control over instrument operations. However, if included, they should not cause confusion to the majority of users. Place low-level VIs several layers down the VI hierarchy. Generally, include a high-level VI that incorporates several similar low-level VIs.

Sometimes you can exclude documented functions not appropriate for programmatic use. For example, most message-based devices have both a set and query version of each command. The set version often is needed for configuration of the instrument, but the query function is not needed. If calls to set the instrument are successful, users can know the state of the instrument.

In general, do not implement an instrument function that LabVIEW can perform. For example, some instruments can save waveforms to disk. However, it is likely that users would rather save data through a LabVIEW interface rather than the through the instrument driver. Therefore, evaluate functionality like file storage and analysis capabilities to determine if users would be more likely to perform these tasks within LabVIEW.

LabVIEW customers typically want to customize the user interface of their VI and not the instrument display. Therefore, do not include functionality to change the instrument display. For example, do not include functionality in an oscilloscope driver that lets users change colors of the waveform on the instrument display.

Recommended

To the extent that it is possible, design configuration VIs so no prior instrument state is assumed. This allows the configuration VIs to be called in any order. Order independent configuration VIs are much easier for end-users. For example, when configuring an oscilloscope, the interface should let a user configure the horizontal settings before or after the vertical settings. Order dependency issues frequently occur when the instrument driver API is too low-level.

Consider the measurement function and range settings on a digital multi-meter (DMM). Most SCPI-based DMMs include an independent measurement function setting, such as "FUNC:"VOLT:DC". However, to set the range, you need to specify the measurement function, such as "VOLT:DC:RANGE <value>". Combine these settings into one configure VI. Separating these two settings into two VIs requires the user to call the measurement function VI before calling the range VI. Also, you would need to design the range VI to determine the function before sending the range command string.

If you cannot avoid VI order dependency, be sure to document the dependencies on the front panel (using free labels) or in the context help for the VIs that rely on a specific VI calling sequence. Also organize order dependent VIs in the Functions palette in the order in which users would place them on the block diagram.

Design the data types and terminal patterns of each VI to work well together. For example, use a consistent channel control throughout the driver VIs for a channel-based instrument. Ensure the channel parameter appears on the connector pane in the same terminal position on each VI. In the following block diagram, all VIs use a common channel control.

The following block diagram consists of subVIs designed with inconsistent terminal patterns, which leads to inconsistent controls and wiring.

When adding support for channel-based instrument settings, avoid creating a separate control for each channel. Rather than duplicating controls for each channel, include a control to that lets users select the channel to configure. The user can use this control to change the settings for an individual channel, rather than configuring every channel each time the VI is called.

Another approach is to use a polymorphic VI to handle both the single-channel and multi-channel use cases. Customers interested in reading from a single channel can wire a single channel to an input on the VI, while customers interested in reading from multiple channels can wire an array of channels to the same input on the VI. This design does not burden single-channel users with arrays and reduces the number of calls multichannel users need to make.

LabVIEW instrument drivers are not intended to be interactive reproductions of the instrument's front panel (often referred to as soft front panels). While you can run instrument driver VIs interactively, the VIs should not contain continuous loops that read input settings and send instrument commands in response to real-time dynamic user input. Rather, they read front panel controls, format and send command strings, read the responses to instrument queries, and update front panel indicators once per VI execution. This is a very important concept. Construct the VI so user interaction is not required for it to run to completion and so the VI works programmatically. You cannot use file dialogs, pop-up text dialogs, or VI execution properties that open a VI when it is called.

As part of their application user interface, end users will develop the interactive panels they require. Strict interactive operation does not add much value to an instrument driver VI. (Users could just press buttons on the instrument panel rather than run the VI.) When building your LabVIEW instrument driver, remember that it must work programmatically as well as interactively. Wire all controls and indicators in an instrument driver to the VI connector panes so all data pass into and out of the instrument driver subVIs in a larger application.

Users often use the same instrument driver to control several instruments, so ensure your VIs are reusable with multiple instruments simultaneously. Do not use global or local variables. Generally, do not use uninitialized shift registers in your VIs as these can cause data reuse problems. Use the VISA I/O library because the API supports the creation of multi-instance drivers.

Many customer applications, such as test applications, initialize all of the instruments in a system simultaneously, configure them, take measurements, and close them at the end of the test. Good driver design includes a logical division of operations.

The LabVIEW Plug & Play Instrument Driver model aids both instrument driver developers and end users. Refer to Developing a LabVIEW Instrument Driver for more information about the LabVIEW Plug & Play Instrument Driver model.

Instrument driver API VIs handle the configuration and measurement capabilities of the instrument. You can categorize API VIs as initialize, close, configuration, action/status, data, or utility VIs. The following section describes these categories in more detail. (Your instrument might require additional categories, depending on its functionality. )

• Initialize VI—You must include an Initialize VI in your instrument driver API. The initialize VI establishes communication with the instrument, so it is the first instrument driver VI called. The initialize VI ensures robust instrument control by setting up necessary bus and instrument communication configuration. Optionally, it can perform an instrument identification query and reset operations. Also, it can place the instrument either in its default power-on state or in some other state.
• Close VI—You must a Close VI in your instrument driver API. The Close VI terminates the software connection to the instrument.
• Configuration VIs—Include Configuration VIs that access functions that configure the instrument to perform operations. After these VIs are called, the instrument is ready to take measurements or stimulate a system.
• Action/Status VIs—Include Action VIs that initiate or terminate test and measurement operations. Action VIs differ from the configuration VIs in that action VIs do not change the instrument settings. Action VIs instruct the instrument to perform an action based on its current configuration. Status VIs obtain the current status of the instrument or the status of pending operations. Develop these VIs as you need them or as required by other functions. A software trigger is a good example of an Action/Status VI.
• Data VIs—Include functions that transfer data to or from the instrument. The specific routines these functions call depend on the instrument.
• Utility VIs—Utility VIs perform a variety of operations that are auxiliary to frequently used instrument driver VIs. These VIs include the reset, self-test, revision query, and error query functions.

Data flow determines the order in which LabVIEW programs execute. Design instrument drivers so users can take advantage of this paradigm. By using error in, error out, VISA resource name and VISA resource name out parameters in each of the instrument driver API VIs, you add data dependency to VIs that otherwise are not data dependent. This gives users a way to specify execution without using Sequence structures. After the error cluster passes data through all the instrument driver VIs, the end user application can use the General Error Handler VI or Simple Error Handler VI (which interprets error codes and displays messages to the operator) to handle errors. The VI in the figure below uses error clusters to provide data dependencies and report errors to the user.

Because the Close VI closes the session to the instrument, it does not include a VISA resource name out parameter. Typically example VIs are designed for interactive use so they do not include error in, error out, or VISA resource name out parameters.

Although utility VIs do not represent the core functionality of an instrument driver, implementing utility VIs consistently help end-users understand and learn new instrument drivers.

Revision Query VI —facilitates revision control of the instrument driver. Periodically, an instrument driver might be revised. Revision Query VIs let end users, developers, and support engineers track revisions. This utility VI also helps debug problems related to firmware revisions that cause behavioral differences in the instrument driver.

Self Test VI— verifies the functionality of the instrument. This VI instructs the instrument to perform a self-test and return the results of that self test.

Reset VI— initializes the instrument to a default state. If the instrument includes a reset operation, include this VI as subVI in the Initialize VI so the Initialize VI can make an optional call to the instrument. Because end users might want to reset the instrument in the middle of their application, the Reset VI needs to be accessible as a utility VI.

Error Query VI— returns the error status of the instrument. The Error Query VI detects and reports instrument errors by querying the instrument after other instrument driver commands are sent. For SCPI instruments, the :SYST:ERR? command returns the error status of the instrument. To facilitate error handling, each instrument driver API VI calls the Error Query VI. Because some users prefer to call the VI explicitly, the Error Query VI is also included in the menu palette. The Error Query VIs in the instrument driver template libraries can be used with SCPI instruments. For non-SCPI instruments, the Error Query VI will need to be modified or replaced with one of similar functionality.

Recommended

Design your instrument driver VIs to be consistent in appearance, structure, and style as the other instrument driver VIs for the same type of instrument. For example, all oscilloscope drivers should resemble each other, as should all multimeter, scanner, and source instrument drivers. Consider modifying a copy of an existing driver for a similar instrument to create a new driver, however be aware that some instrument drivers do not adhere to good design principals. Therefore, model your driver on one or more certified instrument drivers and ensure you review the new driver against the current guidelines before submitting the driver for certification.

Recommended

To communicate over the serial bus, the bus configuration settings of the instrument driver must match the settings on the instrument. The default configuration settings of the instrument driver should match the default settings the manufacturer set on the instrument unless an alternative setting is critical for driver communication. Users can use the instrument driver more quickly when they do not need to change configuration settings on the instrument driver or the instrument.

Operating system support, cable length, and other environment factors might influence the bus configuration settings a user might choose to use. Therefore the serial configuration settings should be configurable. For example, users might change handshaking settings when they want to optimize their baud rate or improve robustness. Include these configuration settings in a cluster control on the Initialize VI.

Instruments often allow users to configure the data encoding format when transferring data arrays. Although the ASCII data format is the easiest data format to parse in LabVIEW, transferring the data in binary format can significantly improve performance. The most common binary format used by IEEE 488.2 compliant instruments is the Definite Length Block Format.