Academic Company Events NI Developer Zone Support Solutions Products & Services Contact NI MyNI
NI IDNet Feedback

Instrument Driver Guidelines

August 2014 Revision

The following guidelines explain the National Instruments requirements and recommendations for creating a certified LabVIEW Plug & Play instrument driver. Use this guideline to review your driver for instrument driver certification. Because end users look for certification as an indicator of a high quality instrument driver, National Instruments reviews submitted instrument drivers against the following requirements and recommendations. This checklist should be used in conjunction with the "Developing LabVIEW Plug and Play Instrument Drivers" application note.

View Options

GuidelinesDetails
1)Before You Develop Your DriverView
1. Familiarize yourself with the instrument, its capabilities, and use. View

Being familiar with the instrument and its uses in actual applications helps you design a useful instrument driver application programming interface (API). Read the operating manual thoroughly. Learn how to use the instrument manually before you attempt developing interfaces to it. Use the instrument in an actual application to get practical experience. If the operating manual explains how to set up a simple test, do so.

2. Familiarize yourself with the instrument programming manual. View

Study the programming section of the instrument manual. Read the information on the instruction set to familiarize yourself with the available controls and functions and the organization of the features. Determine which instrument features you want to access for programmatic use. Test sending commands to the instrument to understand how the commands affect the operation of the instrument. Use one of the following tools to aid in interactive testing.

Communicate with Instrument Utility—(Windows Only) Select the Devices and Interfaces option in Measurement and Automation Explorer (MAX) to communicate with IEEE-488.2 instruments. Use this utility to read, write, and query an instrument in a graphical environment. Use this utility to test instrument commands as you develop instrument drivers.

VISA Interactive Control—NI-VISA includes the VISA Interactive Control (VISAIC) utility, which is called on all platforms that support the LabWindows/CVI Run-Time Engine. This utility provides access to all VISA functionality interactively in a graphical environment. Use this utility to test instrument commands as you develop instrument drivers.

Instrument I/O Assistant—The Instrument I/O Assistant Express VI, available in the Express»Input or Express»Output palette, lets you send commands to an instrument, then view and parse the responses in real-time using steps. When you place the assistant on the block diagram, the interactive window appears. Though the assistant provides simple instrument control when an instrument driver is unavailable, you can use it as an interactive tool as well.

3. Use the following settings for the options in the Tools»Options menu in LabVIEW when creating instrument driver VIs: View
3.1 Paths: Check Use default.
3.2 (Recommended) Front Panel: Select the Modern 3D style for use for new VIs.
3.3 Block Diagram: Check Use transparent name labels.
3.4 Block Diagram: Uncheck Place front panel terminals as icons.
3.5 Block Diagram: Uncheck Enable automatic error handling in new VIs.
3.6 Block Diagram: Uncheck Enable automatic error handling dialogs.
3.7 Environment: Check Use default colors.
3.8 Environment: Check Use default font.

Setting these user options before you create new VIs helps you create an instrument driver that is consistent with the look and feel of other certified instrument drivers. For example, use the default application font to ensure cross-platform compatibility. If you create a VI without these options, verify that the VI complies with the settings listed above.

2)Driver Architecture and API DesignView
1. Adhere to design guidelines and be consistent when developing the instrument driver API. Doing so ensures consistency within the API itself and with the API for drivers for similar instruments. View

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.

2. Design the instrument driver for use in simple and advanced applications. View

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.

3. Use the VISA I/O library to communicate over the GPIB, VXIbus, Serial, USB, PXI, and Ethernet bus interfaces. View
3.1 (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.

4. Design VIs that give users the appropriate amount of control of their instruments. Design VIs for reuse as subVIs. View

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.

5. Design an instrument driver that optimizes the programming capability of the instrument. View

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.

6. (Recommended) Design configuration VIs so they do not rely on the status or setting of another VI. View

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.

7. Design VIs to work well with other VIs in the instrument driver. View

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.

Example of consistent wiring within the instrument driver VIs

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

Example of bad terminal selections and bad text ring values.
8. Minimize redundant parameters. View

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.

9. Design the instrument driver for programmatic use. View

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.

10. Design the instrument driver to work with multiple instruments simultaneously in the same application. View

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.

11. Group the API VIs into categories by instrument capabilities. You can categorize most instrument driver VIs as Initialize, Close, Configure, Action/Status, Data, or Utility VIs. View

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 VIsUtility 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.

12. Use error in, error out, VISA resource name and VISA resource name out parameters in your VIs to help users control data flow and to force data dependency in their applications. View

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.

Example of using error clusters in an example program

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.

13. Include the following VIs in the instrument driver unless the instrument does not support the functionality: Revision Query, Self Test, Reset, and Error Query. View

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. The instrument driver templates web site includes template VIs for these utility VIs.

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.

14. (Recommended) Design the appearance and functional structure of the instrument driver so it is similar to drivers for instruments of the same type. View

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.

15. (Recommended) If the instrument driver supports the serial bus interface, ensure users can access configurable bus settings from the Initialize VI and the default values match the instrument default values. View

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.

16. Optimize driver performance by transferring data using binary transfers. View

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.

3)VIs: Names and PropertiesView
1. Name the LabVIEW library with a descriptive name, which will be used to namespace the instrument driver VIs contained within that library (.lvlib). View

The driver identifier uniquely identifies your instrument driver and the instruments supported by the driver. The driver identifier is used for naming of the project libraries, project library files, and other driver files. The driver identifier should be the manufacturer name followed by the instrument model or the manufacturer name followed by a name that represents a family of instruments as branded by the vendor. It should not contain the instrument revision such as A, B, E punctuation or special characters.

The following list includes examples of driver identifiers for instrument drivers.

Agilent ESG Series—The Agilent instrument driver for the ESG series signal generators.

Agilent 33XXX Series—The Agilent instrument driver for the 33120A, 33220A, and 33250A family of function generators.

Tektronix TDS 3000 Series—The Tektronix instrument driver for the TDS 3000 series oscilloscopes.

Yokogawa 2533—The Yokogawa instrument driver for the 2533 power meter.

2. Use a consistent naming convention for all instrument driver VIs. View
2.1 Use meaningful names that describe what operation the VI performs.
2.2 Use complete English words unless an abbreviation is known by users worldwide.
2.3 Name each VI with the base functionality first. Use a verb for the base name.(e.g., Configure, Query, and Read).
2.4 (Recommended) Use book title form (example: Fluke 45 Read Measurement).

Most users access VIs through the LabVIEW Functions palette. However, often users access the VI through a file dialog or explorer, so use a consistent naming methodology to help users identify VIs.

For example, in the Fluke 45 driver Configure Display and Configure Math would be correct, but Display Configure or Math Configure would not be correct.

Be sure to use consistent capitalization because that helps users organize the VIs in a file dialog, especially in file dialogs on operating systems that are case sensitive.

3. (Recommended) Use polymorphic VIs to enhance and condense the driver API. View

If you create polymorphic VIs, name each instance subVI the same as the top-level VI name and indicate the differences such as data types, trigger types, and so on in parenthesis. Do not use the word "Polymorphic" in the VI name. An example would be to have a polymorphic VI named Read.vi with the instance VIs named Read (Multiple) and Read (Single). Also use polymorphic VIs to implement similar functionality on data for a variety of data types.

4. Do not use the word "Example" in the name of API VIs.
5. Name VIs with characters all operating systems accept in file names. For example, do not use special characters, such as /, \\, :, ', ", ~, +, |, <, >, and &. View

Name VIs with alpha-numeric characters only. A special character, such as /, \\, or ~, might be an operator on other file systems, which can cause problems if the VI is saved outside of a VI library and opened on a different operating system.

6. Use LabVIEW default settings in the VI Properties dialog box. View
6.1 Do not select options to make the panel automatically show or run.

You use the VI Properties dialog box to customize the settings for a VI. In most cases, use the default settings for the options in this dialog box. Enter documentation for the VI in the Documentation page of the dialog box. The following list includes some key property options and their recommended settings.

Protection: Unlocked—Give users must access to the source code so they can add functionality or customize the instrument driver.

Window Appearance: Default—The default settings ensure that instrument driver VIs appear the same as all other VIs used in the LabVIEW development environment.

Execution: Check Allow Debugging—Allows users to access debugging capabilities so they can easily detect and resolve cable issues, instrument address complications, and configuration problems.

Execution: Disable Reentrant execution—Setting a VI to reentrant execution increases memory usage because each call to a re-entrant VI is a copy of that VI, including memory buffers. Also it is difficult to debug reentrant VIs. Setting a VI to reentrant benefits only those customers interested in making simultaneous access calls to identical instruments. Customers who require increased performance should change this property when they need to.

Execution: Same as Caller—Set the Preferred Execution System to Same as Caller. The task priority varies based on application needs. Therefore, the end user should adjust the priority based on his or her application needs.

Execution: Uncheck Enable automatic error handling—This should be the default setting for each VI you create if you set your environment to disable automatic error handling for new VIs. LabVIEW, by default, enables automatic error handling to help new users debug their VIs. Handling errors in your API VIs using the error in and error out cluster parameters ensures errors are properly reported to users.

Execution: Uncheck Run when Opened—When used interactively, users should control when the VI runs.

Execution: Uncheck Suspend when Called—Instrument Driver VIs never should be suspended when called.

7. (Recommended) If you use LabVIEW Revision History, reset the history when releasing version 1.0 of the driver. View

Before releasing version 1.0 of an instrument driver, clear the revision history of each VI. This facilitates version tracking each time someone updates the driver. To clear the revision history, choose VI Revision History from the Tools menu and click on the Reset button. Choose Yes to reset the revision number. Then close the revision history window and save the VI. Consider using the Invoke Node and the Clear History method to reset the revision history for a collection of VIs. Refer to Programmatically Controlling VIs in the LabVIEW Help for more information about configuring VIs programmatically.

4)Control/Indicators: Naming and Data RepresentationView
1. Give controls and indicators names that describe their function. View

For example, for a ring or labeled slide with options for volts, ohms, or amperes, use a name like Measurement Units rather than V/O/A or Mode.

2. Use a consistent format for control and indicator labels.
2.1 (Recommended) Use book title form (examples: Input Impedance, Number of Averages) for control and indicator labels.
2.2 (Recommended) Put the default value in parentheses and append the name to the control label. Do not include default values for indicators or VI terminal connections that are required.
2.3 (Recommended) Include unit information if applicable in the labels using SI notation, such as Amplitude (10.0 V).
2.4 (Recommended) Match the units of the default value in the label to the units of the control.
3. Choose a Boolean control to represent values with two easily understood opposite states, such as True/False or On/Off View
3.1 Give a Boolean control a name that clearly identifies the behavior associated with the Boolean states.

Once you selected a Boolean to represent a two-state control, assign a control name as well as the Boolean state labels. Below are good and bad choices for Boolean control names and associated selection labels:

Good choice—A control name of Enable Channel conveys that the control has a Enable/Disable selection and indicates the default state is disabled (false).

Bad choice—A control name of Value or Mode with a Value/Mode selection does not describe that you need to enable or disable the control.

Good choice—A control name of Reset (True) indicates the operation performed when the user selects True and indicates in the label that the default is True.

Bad choice—A control name of Wait Behavior with a Wait/Don't Wait selection is not clear.

The following front panel displays how these control names would appear to the user.

Good and bad choices for Boolean control names
4. Choose a Text Ring to represent values that do not have clear two state values, or if you anticipate more state values in the future. View
4.1 Use text rings for controls that have a natural association to several discrete possibilities and no numeric content. Text rings are also appropriate for numeric values when the set of valid values is small.
4.2 If you use text rings for numeric content, do not create an item with text that represents a different numeric value. For example, a selection of 2 assigned to the value 0 could confuse the user.
4.3 Avoid strict type definitions. Such a construct cannot be a constant, and it restricts end user UI choices unless they disconnect the control from the type.
4.4 Avoid the use of an enum type. Adding values to an enum in a future driver version may break existing customer applications.

Do not use Boolean controls if the two options are not opposites of each other. For example a DMM might only allow two-wire or four-wire resistance measurements. The instrument allows only two options, but in this case you would use a ring control because the options are not opposites. The two states are understood clearly from the front panel. A Boolean constant makes the block diagram difficult to understand. On the other hand, a Text Ring constant makes the block diagram easier to understand. The block diagram in the figure below uses a Text Ring to make the block diagram easier to understand.

Booleans without clear opposites make the block diagram difficult to read.

Text rings also make it easy to edit the driver if the instrument might add additional options in a future version. You can add options to a ring control without breaking end user applications. The front panel in the figure below shows good and bad choices for two-state controls.

Bad choices for Boolean data types

Use a Text Ring when you have a finite number of selections. The front panel in the figure below includes good examples of using Text Ring.

Good examples of Text Ring selections

Avoid using Text Rings for selections of numeric values. Instead, use an integer or double precision sparse ring for selections of numeric values. Sparse ring values associated with ring entries do not need to be sequential. For example, you can map "5.5" to the double precision value of "5.5" in a ring, which is helpful when you have only a few value numerics to choose from (such as 4.5, 5.5, and 6.5). By mapping to the same value, you can then directly pass that value to Format Into String to build up the command to send to the instrument. The front panel in the figure below includes good and bad techniques for creating rings for channels.

Use a numeric or numeric sparse ring instead of a Text Ring or Boolean to represent numerics

If possible, make the value names in the Text Ring obvious. However, sometimes the selections cannot be fully described in the selection. In this case, it is important to document the value options in the Context Help. The Context Help window below shows clear documentation of menu selections.

When ring values are not obvious, document them them in Context Help
5. Use data types that minimize the amount of conversion, formatting, and parsing by the user. View
5.1 (Recommended) Use the waveform data type when your VI acquires or generates analog waveforms.
5.2 (Recommended) Use paths instead of strings for file path names.
5.3 (Recommended) Use the time stamp data type for time and date information.
5.4 (Recommended) Use double precision (DBL) data type representation for timeout controls.

Use data types users can integrate easily in their applications. For example, if a user enters a voltage level using a numeric control, which likely has a double precision data type, the instrument driver VI should handle the formatting process that converts the double precision data to a string to send to the instrument. Similarly, the instrument driver VI should parse instrument responses and format them into a data type suitable for further analysis and presentation. For example, if the instrument returns a waveform, the instrument driver VI should parse the waveform string and create the waveform data type before it sends the data to a graph. The VIs in the figure below demonstrate building a waveform within an instrument driver VI.

Use the Waveform data type when returning waveform data
6. (Recommended) Use the long integer data type representation for controls where users enter a natural number, such as the number of items in a set. Use I32 controls for signed integers and U32 controls for unsigned integers. View
6.1 (Recommended) For arrays of natural numbers, use long integers (I32) as the representation for arrays except for arrays that might exceed one million elements. In cases of such exceptionally large arrays, you can use a word (I16) representation or bytes (I8) representation for the array.

Even if you can represent a number as a 16-bit or 8-bit integer, use a 32-bit integer value because you provide the user with a consistent API and minimize data conversions within the instrument driver and in the end-user's application.

7. Use the double precision (DBL) data type representation for controls where users enter a real number, such as the value for a level or setting. View
7.1 (Recommended) For arrays of real numbers, use double-precision values as the representation for arrays except for arrays that might exceed one million elements. In cases of such exceptionally large arrays, you can use a single-precision representation for the array.

If the value a user enters could be a non-integer value, ensure that the control uses the double-precision data type representation. For example, use double-precision representation value with physical units, such as voltage, power, frequency, length, and angle. Even if you can represent a number as a single-precision value, use a double precision value because you provide the user with a consistent API and minimize data conversions within the instrument driver and in the end-user's application.

8. Do not configure data limits for numeric controls
9. Avoid strings as controls and indicators, if the set of strings is finite; use a text ring instead. View

Avoid using strings as input parameters. If the set of strings the user can pass to an instrument is finite, use a text ring control so users can select the string to pass. Using a string control requires the user to enter the string with the proper spelling, case sensitivity, and word order, which is prone to error.

The front panel below demonstrates how requiring uses to enter units in a text string can confuse them.

Case sensitivity and exact matches are problematic with string controls

However, use a string indicator to display messages to the user.

10. Avoid using cluster controls and indicators, except for error in and error out. View

Passing cluster information between VIs makes the application more complex because doing so requires users to bundle and unbundle the information in the clusters. Re-evaluate the grouping of the inputs for the VI. Use clusters only when you can logically group a set of controls, such as a bank of digital control lines that you pass to several VIs.

5)VI Front PanelsView
1. Consistently place common controls and indicators in the same location on each front panel. View
1.1 Include the VISA resource name in the upper left corner, VISA resource name out in the upper right corner, error in in the lower left corner, and error out in the lower right corner.

In addition to establishing data flow between API VIs, the VISA resource name and the error clusters provide both interactive and programmatic use of the instrument driver. To use the VIs interactively, users select an open resource name from the VISA resource name ring control. The error out VI informs the user if an error occurred while running the API VI. Placing these controls and indicators in same location on each VI helps users focus on the controls that differ in each VI. Use the instrument driver templates when creating new API VIs. The standard controls in these templates contain complete descriptions that appear in the Context Help.

Besides the VISA resource name and the error clusters, place other standard controls in the same location on the front panel. For example, channel-based instruments often have multiple VIs that include a channel input, so place the channel control in the same location on each VI.

2. Set default values for each control. Do not set default values of indicators like graphs, arrays, and strings. View
2.1 Choose a default value whenever possible so the VI does not return an error when run.

To set default values for controls enter the default value in each control, select Operate»Make Current Values Default, and save the VI. Enter common user settings for the instrument driver as default values. This reduces unnecessary wiring for the end user. Do not set default values in indicators or large data controls (except in examples) such as graphs and arrays because doing so uses disk space when you save the VI.

3. Use the appropriate display format for the control. View
3.1 (Recommended) Use automatic formatting for numeric controls and indicators.
3.2 (Recommended) Use the same display format for common or similar values throughout the instrument driver VIs.

Right-click the control and select Format and Precision and select Automatic formatting in the Format and Precision tab unless the control requires a specific format. For most numeric controls and indicators, the Automatic Formatting option displays the numeric in the format that LabVIEW determines as most appropriate for the data. However, use a different format if appropriate. For example, users might expect numbers to appear in hexadecimal format. In this case, configure the numeric indicator to use the hexadecimal format, but right-click the control and select Show Radix from the shortcut menu to let users switch between formats easily.

4. Ensure font settings do not cause front panel objects to overlap. View

To create a professional panel, keep the front panel simple. Do not overlap controls on other controls, labels, digital displays, or other objects. Overlapped controls redraw slowly and make the front panel appear cluttered. Give each object a 33 percent cushion of space to account for font size changes. The figures below illustrate how overlapping text occurs when the system font size changes.

Although placement appears acceptable, the controls are too close together. When systen font size increases the controls text ovelaps
5. Ensure all front panel controls are visible on the front panel View

Do not hide controls and do not move controls outside the visible area of the front panel. Hidden controls confuse users and make debugging VIs difficult. For example, do not hide the error in control or place the control outside of the visible area to conserve front panel space. If you open the front panel of a subVI with a hidden error in control, you cannot determine from the front panel whether an error occurred before the subVI executed or when the subVI executed.

6. Align and distribute the controls for better front panel layout. View

Use the Align Objects tool and the Distribute Objects pull-down menus to create a uniform layout. The front panels in the figures below demonstrate how aligning controls can improve front panel appearance.

Bad alignment of front panel objectsAligned and distributed controls makes for a professional front panel
7. (Recommended) Use default colors and add color sparingly. View

Avoid bright colors because they might distract the user. Also, bright colors appear poorly on certain types of monitors or during printing. When possible use the LabVIEW default colors.

If you do use additional colors, ensure they appear as intended when printed on a black and white printer. Do not use color as the sole indicator of device status as some people with color-blindness can have problems detecting the change. Some of the colors on the front panel in the figure below do not appear as differentiated when printed with a black and white printer.

Shade better differentiator than color
8. Be consistent when using Modern 3D controls. View

Using a consistent style of control helps create a professional-looking user interface.

9. (Recommended) Save the VI so the front panel opens in the top left corner of the screen and fits within 1024x726 resolution. View

Front panels should fit within the standard monitor resolution of most of the users. Some displays, such as LCD displays and touch screens, have limited resolution, so design the window to be as small as possible without crowding controls or sacrificing a clear layout. Save the VI so that it opens in the upper-left corner of the screen to ensure most users can view the entire front panel without scrolling.

10. Use a consistent style for all Boolean and Numeric controls. View
10.1 Use the vertical slide switch for Boolean controls.
10.2 (Recommended) Use the control properties to set Show Boolean Text. Set appropriate labels for On Text and Off Text. Place Boolean text to the left or right of the control. Place Boolean text to the right of the control.
10.3 (Recommended) Use the Round LED for Boolean indicators.

Use the vertical slide switch Boolean control because it lets users easily identify the current state of the control. Avoid using buttons to represent Booleans.

You can label a Boolean by setting the properties of the switch. Right-click the control and choose Properties to display the Boolean Properties dialog box. On the Appearance tab, place a checkmark in the Show Boolean Text checkbox and the Multiple strings checkbox. Enter the label for your True value in the On text textbox and the label for your False value in the Off text textbox. Use the default ON/OFF values when appropriate. Click OK to save the changes. Move the Boolean text label to the right of the control.

6)Icon and Connector PanesView
1. Create an icon for each VI that identifies the instrument and conveys the functionality of the VI. View
1.1 Each icon must include a banner at the top. Place the driver prefix or abbreviated driver identifier in the icon banner.
1.2 Consistently use a common theme for all VIs for a driver or group of VIs within a driver.
1.3 (Recommended) Include a meaningful image that represents the functionality of the VI.
1.4 (Recommended) Avoid using text or signs that international users might not recognize.

The banner at the top of the icon helps users identify the instrument driver.

Use consistent background colors and the same prefix font to maintain a consistent theme for each VI. Combine glyphs that represent instrument functionality to build meaningful images. Copy glyphs and images from existing instrument drivers or select a glyph from the Icon Art Glossary. When possible, avoid using text in the image because the text might be difficult to read and international users might not understand the text.

Color icons appear within the development environment. When users print using black and white printers, the printer uses the black-and-white icons.

The icons in the following figures illustrate good and bad examples of icons.

Good: Examples of icons with meaningful icons and unifying themeBad: Examples of icons with icons that do not translate well to other languages and cultures

Use a white background for your icons to adhere to good design practices.

2. Standardize the connector pane pattern. View
2.1 Use the 4-2-2-4 or the 5-3-3-5 terminal pattern throughout the driver and consistently locate controls of the same type in the same place on the connector pane of each driver VI.
2.2 (Recommended) Include unused connector terminals in your connector pane pattern to allow for future development.

Consistent use of the same terminal pattern makes the wiring of VISA resource names and error clusters easy to align. The following figure highlights the recommended patterns for connector panes.

Recommended terminal patterns

Inconsistent connector pane assignments within an instrument driver results in poor wiring for the end users. The block diagram in the following figures include subVIs with consistent and inconsistent connector pane assignments.

Good: Example of VIs designed to work with other driver VIs.Bad: Example of VIs designed independently of others.

If you need more terminals than the recommended patterns, reconsider the grouping of the controls and indicators on the VI. Except for error in and error out, avoid using clusters to minimize the number of terminals. Clusters often require the user to unbundle and rebundle data from the cluster.

Use extra terminals for any controls or indicators you might add to the VI in future versions. Changing the terminal pattern to account for new inputs and outputs often requires the user to rewire the inputs and outputs everywhere the VI appears as a subVI on a block diagram. By contrast, if you add inputs and outputs but do not change the terminal pattern, it is less likely users must rewire their block diagrams.

If necessary, use the 6-4-4-6 terminal pattern, but do not make this the standard connector pane pattern. Use this pattern on individual VIs only.

3. Standardize the terminal assignments on the connector pane. View
3.1 Wire inputs on the left side and outputs on the right side of the connector pane to follow the standard left-to-right model of data flow.
3.2 (Recommended) When using the top and bottom connector terminals, assign inputs from the left and outputs from the right, without leaving open spaces.
3.3 Assign VISA resource name control to the upper left terminal and VISA resource name out indicator to the upper right terminal. Assign the error in input cluster to the lower left terminal and the error out output cluster the lower right terminal.
3.4 (Recommended) Assign the input and output terminals on the connector pane in a way that simplifies the wiring diagram. Consider how users would wire the instrument driver VIs together when you assign terminals. Be sure the output terminals align with the appropriate input terminals.
3.5 (Recommended) Use a consistent assignment for controls that are common to a group of subVIs, such as Channel.
3.6 Arrange the controls and indicators in a similar pattern to their locations on the front panel.

Ensure you assign terminals on the connector pane consistently. Conform to the LabVIEW programming standard of arranging terminal positions relative to the position of controls and indicators on the front panel.

4. Use appropriate Required, Recommended, and Optional settings on the connector pane. View
4.1 Make the VISA resource name a Required input.
4.2 (Recommended) Use the Required setting if you are unsure, because you can safely change this to a Recommended input in a future release without breaking existing user applications. The opposite is not true.

In the Context Help window, Required connections appear as bold, Recommended connections are in plain text, and Optional connections appear as grayed out text or appear as a wire stub. Users must wire all Required connections to subVIs with required inputs, otherwise the VI is broken.

Make a connector input Required if the associated control default value is not valid or is rarely valid for customer applications.

Leave most connections as Recommended inputs, the default option.

Use Optional connections for inputs that depend on another control setting, or not a critical setting for the VI.

Because each instrument's resource address differs for each customer and, possibly, each time the VI runs, users must wire a value to the VISA resource name parameter in their VIs. For this reason, always make the VISA resource name parameter a required input.

If you have a Configure Waveform VI that generates a waveform on a function generator, a parameter that controls the Duty Cycle applies only when the user selects a square waveform as the Waveform Shape. In the case of the Configure Waveform VI, configure the Duty Cycle control as an Optional connection.

7)Block DiagramsView
1. Use consistent style and placement of terminal labels. Justify text appropriately. View
1.1 (Recommended) Use plain text labels for controls/indicators.
1.2 (Recommended) Make all control and indicator terminal labels visible on the block diagram.
1.3 (Recommended) Use labels on block diagram constants to document the nature of the constants.

Labels on the block diagram improve the readability of your VIs, which allows users to customize the VIs more easily.

2. Include error handling in all VIs. View
2.1 Do not change the error codes defined in the instrument driver templates.
2.2 Include calls to the Error Query VI in all instrument driver API VIs. The only exceptions are low-level VIs used for end-user optimization.
2.3 If you define an instrument specific error code, use a code in the range of - 1073999873 to - 1074001920 (Hex: 0xBFFC0800 to 0xBFFC0FFF)
2.4 If you define an instrument specific warning, use a code in the range of 1073481728 to 1073483775 (Hex: 0x3FFC0800 to 0x3FFC0FFF)
2.5 If you define an instrument specific error or warning code, pre-pend the <ERR> tag to instrument error descriptions and wire to the Source of the error cluster.

Error codes defined within the instrument driver templates ensure consistent error codes in all instrument drivers.

Calling the Error Query VI within each API VI ensures the instrument driver checks the status of the instrument after each operation automatically. This helps users associate an instrument error with instrument commands within a particular instrument driver VI.

The block diagram in the figure below shows how an instrument driver VI calls the Error Query VI.

Instrument driver API VI with call to Error Query VI.

If you define additional error codes in your instrument driver, append the <ERR> tag to your error description. This <ERR> tag tells LabVIEW to use the information in the source text as the explanation for the associated error code. LabVIEW ignores any previously defined explanations in the LabVIEW error codes database. The Initialize Template VI uses this technique.

3. Use the appropriate format string modifiers to configure a period (.) as the decimal separator when formatting or parsing numbers sent to or received from an instrument. View
3.1 Include \"%.;\" as part of the format string to convert floating point numbers when using functions like Format Into String or Array to Spreadsheet String.
3.2 Wire a False Constant from the Boolean palette to the Use System Decimal Point terminal of the Number To Exponential String and Number To Fractional String functions.

Number formats depend on regional preferences. However, instrument number formats do not. In the United States, the decimal point (.) separates the whole number from the fractional part of a number. In western Europe a comma (,) often separates the whole number from the fractional part of the number. Most user applications display and operate on double-precision data using the number format commonly used in the region. LabVIEW uses the system default settings for number formats. The figures below show how the Windows operating system displays German and U.S. numbers.

System settings showing number formats used in GermanySystem settings showing number formats used in the United States

Instruments send and receive ASCII numbers using decimal points as separators, regardless of where you use the instrument and how you configure your computer. The user might configure LabVIEW to use the system default settings for number formats, so use the decimal point (.) as the separator for string parsing and formatting for instrument control strings.

For LabVIEW to use the decimal point separator of the operating system and communicate properly with instruments, all string operations that operate on floating point numbers must include the modifiers to use a period (.) as the decimal separator.

To force the decimal point, include the "%.;" in the format string input of Format Into String or Array to Spreadsheet String functions. To use the decimal specifier format string, attach %.; to the beginning of the standard format string input for floating point inputs (floats, exponential inputs), such as "%.; SHOR %e;". If you use the Number To Exponential String or Number To Fractional String functions, wire a False Constant from the Boolean palette to the Use System Decimal Point terminal. You do not need this decimal specifier for decimal numbers (those that use %d or %x format specifier).

4. Leave enough space between nodes on the block diagram. Do not overlap or cover objects on the block diagram. View
4.1 (Recommended) Use the Size to Text to ensure all the text in a label appears regardless of font or language settings.

Fonts vary by platform, user system preferences, and video driver settings. Therefore, text might appear larger or smaller on different systems. Right-click the labels on the block diagram and select the Size to Text option to allow extra space for larger fonts.

Make all labels visible to help users understand the block diagram. Covered VIs, functions, wires and terminals make the block diagram difficult to understand. To prevent labels from overlapping block diagram nodes when the font size changes, include extra space between the nodes.

5. (Recommended) Set the appropriate level of precision for format specifiers. Use the "%g" format specifier to format and parse floating point numbers. View

Many instruments accepts ASCII decimal numbers in a format referred to as Decimal Numeric Program Data or <NRf> for "flexible Numeric Representation". This format accepts values in both exponential and decimal format. For example, both of these numbers are valid: "+12.3e-10" or "0.000000000123". If you use "%f" when converting to a string, the value would be "0.00000".

Consider the range of values the instrument accepts for a given instrument setting and the number of digits of precision the instrument accepts. Use the "%g" format if the instrument accepts a value with a large range of values. This format allows the number of digits of precision to change based on the exponent and precision of the number. LabVIEW uses an "f" if the exponent is greater than -4 or less than the precision specified. LabVIEW uses an "e" if the exponent is less than -4 or greater than the precision specified.

The figure below shows how format specifiers affect a value you might send to an instrument.

Problems when formatting small numbers

For high precision settings, specify an appropriate value of precision in the format string. If the instrument accepts more than 5 digits of precision, include a precision specifier in the format string. The VI in the figure below uses precision settings in the format specifier to affect a value you might send an instrument.

Comparison of decimal formatting specifiers
6. Use a Select function, not a Case Structure, to select between two wire options. View

Users better understand diagrams that do not hide code within structures. When selecting between two wire options, use the Select function because it does not hide code, unlike the Case Structure structure. The VIs in the figures below show how the readability of the block diagram improves when you use a Select function. The two string constant choices are obvious and the users does not need to scroll through cases.

Use Select for two choice selectionsPoor use of a Case structure
7. (Recommended) Save diagrams with the first or most important frames and cases visible. View

Often a Case Structure includes a case with little or no functionality. However this case is not very informative to the user. Therefore, to minimize customer need to change the visible cases, save the VI so Case Structures display the most important cases first when the user opens the block diagram. If all cases are equally important, save the diagram with the first or True case visible.

The VIs in the figures below show how the readability of a block diagram improves when you display the most important cases.

Case saved with more important case visibleLess important case
8. (Recommended) Use the Concatenate Strings function sparingly and only if you cannot find a more appropriate string function. Use Scan From String and Format Into String as often as possible for string manipulation. Other string handling functions, such as Pick Line and Append True/False String, are good string manipulation functions to use. View

Use the Format into String function to format multiple values and multiple data types into a string. The VIs in the figure below formats data types into strings using the Format into String function.

Use Format into String instead of Concatenate

Use the Edit Format String dialog box to create the format string. Double-click the Format into String function to display the Edit Format String dialog box, as shown in the figure below.

Formatting string wizard for the Format into String function

Use the Scan from String function to parse instrument command strings an instrument returns. The VI in the figure below parses multiple values using a single Scan from String function.

Use Scan from String to parse query responses

Use the Append True/False String or Pick Line to select Boolean or Text Ring values. Use the Append True/False String function to select a string and concatenate it to the command string in a single step, as shown in the figure below.

Use Append True/False String instead of Select and Concatenate

Use the Pick Line function to select a string from a Text Ring. The function lets you select a string based on the label value and concatenates to the command string. The VI in the figure below demonstrates using the Pick Line function.

Use Pick Line instead of Case Structures of Index Array
9. (Recommended) Design the block diagram so it follows the left-to-right, top-to-bottom model of data flow. View

The positions of the program elements do not determine execution order. However, avoid wiring from right to left because this breaks the data flow model and makes the block diagram more difficult to understand.

10. (Recommended) Use dataflow and direct wire connections to specify the execution sequence. View
10.1 (Recommended) Link functions and VIs together using the VISA resource name and error clusters to ensure execution order.
10.2 (Recommended) Use Sequence structures only when you cannot make a wire connection or want to force data dependency and cannot do so any other way.

Use VISA resource names and error clusters to force data dependencies. Avoid using the Stacked Sequence Structure to enforce data flow because the structure hides parts of your diagram and makes it difficult to understand and modify. Also, the Stacked Sequence and Flat Sequence structures tend to be slower than chaining VIs together because sequence structures force all code within a given frame to wait until that frame executes. Chaining VIs together fixes the sequence of the I/O VIs and you still can execute parsing and formatting functions according to data availability.

LabVIEW instrument drivers use the National Instruments standard for error reporting based on the error cluster. Each error cluster includes an error status Boolean, an error code numeric, and an error source string. Each instrument driver VI includes an error in terminal in the lower left terminal and an error out terminal on the lower right terminal on the VI connector pane. The VI in the figure below includes standard error in and error out terminals.

Error I/O Clusters

Wiring the error out cluster of one subVI to the error in cluster of another subVI passes error information through your instrument driver and returns any errors to the top-level VI the user sees. The block diagram in the figure below use the VISA resource name and the error cluster inputs and outputs to enforce data flow.

Use VISA resource name and error cluster to force data flow within instrument driver VIs
11. (Recommended) Wire block diagram objects together as neatly and orderly as you can. View
11.1 (Recommended) Eliminate unnecessary bends in the wires.
11.2 (Recommended) Align and distribute terminals, constants, VIs, and functions.

To make the block diagram easy to understand and modify, reduce the number of bends in the wires by aligning the source and destination of the wires. Use consistent padding when you distribute nodes on the block diagram. The VIs in the figures below use properly aligned wires to improve block diagram readability.

Aligned wires makes the diagram readableBad wiring makes the diagram hard to read
12. (Recommended) Use block diagram labels to document your code. View
12.1 (Recommended) Document each case in a case structure.
12.2 (Recommended) Document complicated algorithms.
12.3 (Recommended) Document non-standard instrument control code.
12.4 (Recommended) Use descriptive labels on block diagram constants.

Try to make the block diagram as easy as possible to understand and modify. Use the free labels found on the Functions»Decorations palette to document any obscure part of the block diagram. Use multiple lines of text if necessary.

Use labels for constants where their functionality is not obvious.

The block diagram in the figure uses text in Case Structures and labels in constants to improve readability.

Documenting constants and adding free label explanations makes the diagram more readable
13. (Recommended) Select the following options in the User Options dialog. Ensure all VIs in your API have these settings. View
13.1 (Recommended) Make terminal and VI labels transparent.
13.2 (Recommended) Disable View as Icon for front panel terminals.
13.3 Select Disable automatic error handling from the VI Properties»Execution window.
13.4 (Recommended) Use default colors for the block diagram background and structures.

Set User Options so each new VI you create or edit uses the recommended settings. However, if you encounter an instrument driver VI saved without the appropriate User Options selected, then you must manually set these options in the VI. Use transparent labels to make the block diagram easier to read. Use data type terminals instead of icon terminals to conserve space on the block diagram. Use default colors to provide consistency with other VI block diagrams. The block diagram in the figure below does not use standard settings and is difficult to understand.

Non-default settings make the diagram more difficult to understand.

Do not enable Automatic error handling. Individual users should enable or disable this feature, depending on their preference. Instrument drivers handle errors internally, so users who enable Automatic error handling in their applications receive error message dialog boxes if an error occurs within the instrument driver.

14. (Recommended) Save the VI so the block diagram opens in the top left corner of the screen when opened. The block diagram must fit within 1024x726 resolution. View

The size of the block diagram window affects how readable it is. Make the block diagram window no larger than the screen size. In addition to the size of the block diagram window, ensure that the block diagram requires the user to scroll a minimal amount. If users must scroll, make sure they have to scroll in one direction, horizontal or vertical.

Consider recreating the block diagram if it is too large by using subVIs to modularize the code.

15. Do not use save options that remove or password-protect the block diagram. View

Most users do not modify the instrument driver VIs. However, allow them to access the block diagram in case they need to optimize or modify the code. Some customers modify the code to optimize performance. Some customers use the instrument driver as a basis for other instrument drivers that control a similar instrument. Some customers need to debug the driver when instrument firmware changes.

8)TestingView
1. Exercise each parameter value to ensure that the instrument settings are updated appropriately. Test both API VIs and Example VIs. View

Each parameter results in a different command string sent to the instrument. Therefore, verify each command string. Test different VI combinations, calling orders, and dependencies. Invalid calling orders or dependencies should be handled robustly by the driver. Test parameters as part of a test framework or test them interactively. Test VIs can be saved and executed on future driver versions. If you test VIs interactively, combine the testing with a final front panel review. This type of testing should be executed throughout development and after the driver is complete.

2. Test a variety of instrument error reporting and recovery conditions. View
2.1 Verify that Error Query VI returns appropriate error information.
2.2 Test that the driver can be run with an instrument that is in an error state.

Test both valid and invalid test conditions. Testing failing conditions validates the error handling mechanisms. Send out of range parameter values, call dependent VIs in the incorrect order, or use other methods to produce instrument errors. Refer to the instrument documentation for a complete list of command, execution, device, and system error messages to test. Test the following conditions to ensure the Error Query VI executes appropriately based on instrument or VISA errors:

Single Instrument error: Error Query should return the instrument's error

Multiple Instrument errors: Error Query should return a queue of instrument errors

VISA timeout due to command error: Error Query should return the instrument's error information

VISA timeout due to data not ready: Error Query should return the VISA timeout error

Non-timeout VISA error: Error Query should return the VISA error

The Initialize VI should clear all instrument errors and place the instrument in a known good state so that the driver can execute properly. Abort an instrument driver example during execution and verify that the example can be run again without error.

3. (Recommended) If the instrument driver supports multiple bus interfaces, test the driver thoroughly with each interface. View

There are many possibilities for different behavior when supporting multiple buses. First, the instrument itself might have different behavior for each bus type. Then the actual bus protocol might introduce differences, including time delays. Third, VISA defines different behavior for some functions and properties. Take these differences into account as you develop your instrument driver VIs. Thoroughly test the driver with each interface. The majority of testing can be executed on one interface bus. The most common use cases, like the instrument driver examples, should be tested with various parameter selections on all supported buses. Test driver VIs that transfer large amounts of data to or from the instrument. Verify the timeout is appropriate for typical transfers on slow buses. All interface specific code should also be tested.

4. (Recommended) Document known issues and functionality not included in the driver. View

The instrument driver Readme should include detailed information about any known issues found in the driver. Include information about test coverage for testing performed on the driver. Instrument functionality not supported by the driver should also be documented in the Readme. All of this information can be useful to users of the driver, particularly if problems are encountered.

5. (Recommended) Thoroughly test and document any timing-related issues. View

Timing issues can often be difficult to identify and troubleshoot. A majority of timing issues occur with the serial interface or with poorly designed instruments. Developers should use Wait VIs only as required to work around timing issues. This workaround should be documented in the driver code and also in the Readme. This type of documentation can be denoted with a keyword so that a user can search for and identify all instances of this workaround in the driver.

6. (Recommended) Stress test the driver under various conditions.
6.1 (Recommended) Run examples with large channel counts, if applicable. For instance, if the instrument supports more than one channel, test all channels for different types of operations. Test reading from or writing to channels in non-sequential order.
6.2 (Recommended) Run examples for an extended period of time. Verify that there is no degradation in performance and that the driver continues to function as expected. Verify that there is no significant increase in memory usage.
6.3 (Recommended) Test different use cases of looping sections of code in a typical series of instrument driver VI calls including entire series of VI calls, the measurement section of code, and multiple configure and measurement sequences.
7. Mass compile all the VIs in the instrument driver library to ensure they execute. View

Before submitting the driver for certification, mass compile the driver to ensure that the instrument driver VI Library contains only runnable VIs. In addition to mass compiling the library, review all the VIs in the VI Library. Sometimes temporary or testing VIs appear in the VI Library unintentionally. Mass compile the VIs on a separate computer running LabVIEW to ensure that there are no dependencies to other VIs not installed on the end-user computers. Do so especially if you create a new instrument driver from an existing instrument driver.

8. (Recommended) Test example VIs for the "out-of-the-box" experience. View

Validate that default values in each VI are appropriate for the most common use cases. Instruments often require stimulus to perform measurements. Set examples to use instrument on-board test signals, such as the probe compensation signal available on most oscilloscopes. This provides users with a good out-of-the-box experience when using both the instrument and instrument driver. If no on-board test signals are available, clearly document the required system setup and stimulus needed to perform the operation. Include these instructions on the front panel of the instrument VI.

9. (Recommended) Test the driver with the latest instrument firmware and on different machines. Report the instrument firmware version tested in the Readme.
10. (Recommended) Run the Instrument Driver VI Analyzer Plug-in. View

The LabVIEW Instrument Driver VI Analyzer Plug-in contains additional tests and configuration based on the Instrument Driver Guidelines. This plug-in prioritizes instrument driver tests for driver architecture and API design, VI names and properties, controls and indicator properties, front panels, block diagrams, icons and connector panes, documentation, palette menus, and examples.

11. (Recommended) If you created online help linked from instrument driver VIs, test access to the help by selecting Click here for more information from the Context Help window. View

Ensure no hard coded paths exist anywhere in the VIs. Test links to the online help on a computer with a different file structure than your development machine.

12. (Recommended) View front panels and block diagrams in larger system fonts to check for font issues and overlapping objects. View

Change the system font for your computer, then check the front panel and block diagram for overlapping objects.

9)DocumentationView
1. Write a VI Description for each VI. View
1.1 Include any information necessary to successfully use the VI.
1.2 Include any VI calling dependencies necessary for VI operation, such as calling Initiate before Fetch.
1.3 Document any restrictions for using the VI, such as whether a certain mode prohibits using the VI or if the VI cannot be used with a particular instrument model.
1.4 (Recommended) Use consistent writing style in the VI and throughout the instrument driver.

Generally, users rely on the context help for information about the instrument driver. A VI description appears when the user opens the Context Help window and moves a cursor over a VI icon. The description for the VI that appears in this window should describe how to use the VI and should include any dependencies necessary for using the VI successfully. Well documented instrument drivers help minimize technical support calls.

The description should contain a general description of the instrument driver VI, including any control usage rules or VI interaction necessary to use the instrument. Select File»VI Properties, then select Documentation from the pull-down menu to display the Documentation Page of the dialog box. Select Help»Show Context Help to display the Context Help window. The Context Help window in the figure below shows the description for an instrument driver configuration VI.

Context help for the Tektronix SA2500 Configure IF Output VI
2. (Recommended) Include critical information on the front panel of the VI and in the VI Description. View

Include any critical information on the front panel of the VI and in the context help for the VI and/or control if applicable. The front panel figure below and the context help figure above include critical information.

Document critical information on the front panel of the VI
3. Write descriptions for each control and indicator. View
3.1 (Recommended) Include a brief description for each control and include its purpose, valid ranges, default values and items within a ring control. Include information that shows index numbers and their corresponding settings for all ring and slide controls, and settings corresponding to True/False positions on Boolean controls.
3.2 (Recommended) Use a consistent style throughout the instrument driver.

A control description help appears when the user opens the Context Help window and moves a cursor over the control. Include descriptions for the individual controls and indicators by right-clicking the object and selecting Description and Tip from the shortcut menu. The figure below shows context help for a Boolean, Text Ring and Numeric controls.

Context help for controls

The help description includes the name and description of the parameter, its valid range, and default value. Include information that shows index numbers and their corresponding settings for all ring and slide controls, settings corresponding to True/False positions on Boolean controls, and range information for numeric controls. Note any pertinent information concerning control interaction in the description boxes of each affected control. You might also include important instructions to the user in free labels on the front panel and in the block diagram.

4. (Recommended) If you provide online help, create help files for each VI and link to those files from the Context Help window. View

The online help document should contain information from the VI and control and indicator descriptions. Refer to the LabVIEW Help for more information about saving VI and control descriptions, creating compiled help files, and linking VIs to compiled help files. Select Help»VI, Function and How To Help to access the LabVIEW Help.

5. Include the following items in the Readme file included with your driver: View
5.1 The instrument driver revision number
5.2 The firmware revision of the instrument used when creating the instrument
5.3 The instrument manufacturer name
5.4 The supported instrument model(s) (Be specific and include letter revisions, for example, TDS 3054B)
5.5 The instrument type (digital multimeter, oscilloscope, function generator, etc.)
5.6 Unsupported features and options, (Be specific, for example, TDS 3FFT option not supported)
5.7 Versions of LabVIEW and VISA used during development
5.8 Instrument bus types supported by the driver
5.9 Modification history, if you are updating the driver

Revision number—Start the instrument driver revision number with 1.0 for the first release. The driver revision should be in the following format: Major.Minor.Fix. Set the instrument driver revision number in the Project Library Properties dialog box.

Firmware revision—Include the firmware of the instrument(s) you used during development. If using a SCPI instrument, query the firmware using the "*IDN?" command.

VISA version—If developing on the Windows platform, use the Measurement and Automation Explorer (MAX) to determine the version of VISA installed on your computer.

Bus support—Many instruments support multiple buses. However, the instrument driver you develop might not support all the bus interfaces. Document the supported buses clearly.

Modification history—Include the name or initials of the developer, the modification date, and a short description of the changes made to the driver in each entry.

6. (Recommended) Include the instrument manufacturer name, instrument description, supported instrument models, and supported bus interfaces in the context help documentation for the VI Tree VIs and example VIs. View

Often, users open the VI Tree VI, example VIs, and the Initialize VI first, so ensure these VIs include the most critical information about the manufacturer and instrument(s) the instrument driver supports in their context help descriptions.

7. (Recommended) Use boldface <b> and </b> tags to emphasize keywords or phrases. Context Help. View

By tagging items with <b> and </b> you can add emphasis to context help text. The True and False strings in the help window shown below were tagged for emphasis.

Context help for Enable Statistics Boolean control
10)Example VIsView
1. Create example VIs that show users how to use the API. View

Provide examples with source code. Call user-accessible VIs to teach users how to control the instrument. Examples help users understand the recommended calling sequence necessary to perform instrument operations. If a simple example calls an excessive number of API VIs, the instrument driver might need a more appropriate level of granularity. The figures below show the front panel and block diagram of an instrument driver example VI.

A sample example front panel and block diagram
2. Create runnable example VIs with reasonable default values. View

Examples are self-contained and runnable VIs that perform complete operations. For example, a good example VI for a DMM configures, starts, and reads from the DMM. Include calls to the Initialize, Close and Simple Error Handler in your examples. Also, example VIs help users establish communication with the instrument and learn how to programmatically control the instrument.

3. Do not wire terminals to the connector pane of an example VI. Do not design example VIs to be used as subVIs. View

Example VIs are not part of the instrument driver API and, therefore, users should not use them as subVIs. Examples might change from one driver release to the next. If you wire the terminals to the connector pane, end users might use the example VI in their applications. A change to the example in a future release would break their application.

4. Create a separate example for each typical instrument use case. View

Users expect most instrument drivers to include an example for each typical use case for an instrument. Including multiple examples benefits a wider range of customers.

5. Give the example a meaningful name Do not use the word "Example" in the VI name. View

Use names in the example VIs that describe the operation the VI performs, such as "Agilent 33XXX Series Generate Arbitrary Waveform" or "Tektronix PA1000 Acquire Harmonic Measurement".

6. (Recommended) Include description and tip help for all controls and indicators. View

To aid users in getting started with an example VI, include tip strips for the controls. Tip strips are brief descriptions that appear when users move cursors over a front panel object.

7. (Recommended) Include general instructions for using the example VI and other important information at the top of the front panel of the example VI. View

Often, users start with an example when they first start using an instrument driver. Include important information about using the driver and the example on the front panel and in the Context Help of the example VI. Include information on supported instrument model(s), required bus configuration settings, and required instrument cabling and hardware setup. Include a sentence on the front panel that instructs users to refer to the Context Help for more information on using the instrument driver.

8. Include the Examples folder in the project (.lvproj), but not in the project library (.lvlib). View

The figure below shows how the Examples Folder (.lvproj) and other folders are organized in the Project Explorer

Power Meter Template Project Explorer View
9. (Recommended) Prepare the example VIs you create to appear in the NI Example Finder. View

Select Tools»Prepare Example VIs for NI Example Finder to prepare example VIs you create to appear in the NI Example Finder. Select Hardware Input and Output»Instrument Drivers»LabVIEW Plug and Play for the browse path. Select keywords to be associated with the driver. Keywords should include the following: the words "instrument" and "driver" the manufacturer's name, such as "Agilent" or "Mettler" and "Toledo" the supported instrument model and/or series name some type of product reference, such as "DMM," "analyzer," or "scope"Use the Build Data File tab to build the data (.bin3) file that stores the task-based browse paths, keywords, and other information about the example VIs you document. Include this newly created data (.bin3) file with your driver. Refer to the LabVIEW Help for more information about running this tool.

11)Palette Menu FilesView
1. Organize all user-accessible VIs into a hierarchy of menu palettes. View
1.1 Ensure the most commonly used VIs appear at the higher levels of your palettes and top rows within the palette.
1.2 If the instrument driver follows the organization used in the templates, use the palette menus provided in the LabVIEW instrument driver templates. Link to the palette menu file through the project library (.lvlib).
1.3 Do not include subpalettes if the sub-menu does not contain any VIs.
1.4 (Recommended) If a palette contains enough VIs to have more subpalettes, create new menu (.mnu) files for each subpalette.

To help customers access and use instrument drivers, create well-organized menu files. Menus benefit the end user when instrument drivers appear in the Function palette automatically and in an organized manner after they load the instrument driver. The menu palettes also help users learn about the instrument driver API.

Most users access the instrument driver VIs through the palettes. Therefore, ensure the instrument driver VIs users access appear in the menu palette. Do not include support VIs and any other VIs the user does not access directly in the menu palette. The palettes in the figures below show the top level palette of a sample instrument driver.

Tektronix 200 1000 2000 Series Scope top level menu palette Agilent 3352X Series Configure menu palette

Consistency in organization between instrument drivers helps users who are familiar with one instrument driver to quickly navigate a new instrument driver. This increases the ease of use of all instrument drivers. Therefore, ensure that your instrument driver follows one of the menu structures shown in the figures above, depending on your LabVIEW version. The LabVIEW instrument driver templates include sample menus for your reference.

When creating a hierarchy, highlight the most common VIs at the higher levels of your menus, and place advanced VIs deeper in the hierarchy. Within each palette, place the most commonly used VIs on the top rows.

Ensure related VIs appear together in the order the user would typically call them. Do not include many one- and two-icon palettes because users find them difficult to navigate. For more details on Palette Structure please review the How to Build a Palette Structure for a LabVIEW Plug and Play Instrument Driver article.

2. Save .mnu files with meaningful names that describe the category of VIs they contain. View

Although end users typically do not need to associate menu files with their palettes, provide meaningful file names to help users associate files with palettes when they view the instrument driver .mnu files in a file browser.

3. Name the top-level menu file (dir.mnu). View

In LabVIEW, the dir.mnu provides directory information for all its subpalettes, and so be sure it is the top-level menu file.

4. Write documentation for each palette and subpalette.
5. (Recommended) Include Short Names for each VI in the palette.
12)Files and Documents to be SubmittedView
1. Save all the instrument driver VIs in a directory structure matching the instrument driver palette layout. Driver VIs should be saved as part of the instrument driver library (Instrument Driver Identifier.lvlib). View
1.1 (Recommended) Separate driver API VIs from the support VIs. Support VIs should be saved in Private folder, the end user should not access Private folder directly.

Private VIs should not appear in the Instrument Drivers palette and therefore are not intended to be used by the end user. Private VIs never appear on the block diagram of an Example VI or VI Tree. An example of a support VI is the Default Instrument Setup VI, which sends a default command string to the instrument whenever a new VISA session opens, or the instrument is reset.

Do not confuse Private support VIs with user-accessible Utility VIs. Refer to the LabVIEW instrument driver templates for more information about example support VIs.

2. Create VI Tree.vi and include in Public folder. View
2.1 (Recommended) Include a message on the front panel instructing the users to "See the diagram for the VI Tree".
2.2 (Recommended) Arrange the instrument driver VIs on the block diagram that helps the user understand the instrument driver API. Include only the instrument driver VIs you intend end users to access.

The VI Tree VI is a non-executable VI that helps end users visually see the hierarchy of the instrument driver VIs. Arrange the VIs in the VI Tree VI by functional grouping, such as Initialize, Configuration, Action/Status, Data, Utility, and Close. The functional grouping should be similar to grouping of the instrument driver palette.

A VI Tree VI should not contain front panel controls, so include instructions on the front panel to view the block diagram. The figures below show the front panel and block diagram of a sample VI Tree VI.

VI Tree VI front panelVI Tree VI block diagram
3. Examples should be included in a separate Examples folder on disk and in the project (.lvproj). View

This helps end users select the VIs needed to begin communication with their instrument.

4. Do not mark VI library (.lvlib), project (.lvproj), or menu files (.mnu) as read-only. View

End users need write access to the instrument driver VIs and menu palettes. Users might want to optimize the code in the instrument driver and often need to mass compile VIs in other versions of LabVIEW. Although users are less likely to modify .mnu files, give them write access to these files because read-only files frustrate end-users when they need to modify them.

5. Package all instrument driver files in driver_indentifier.zip (no spaces and in lower case letters). View
5.1 lvproj/lvlib, the main instrument driver library
5.2 Folders: Examples, Public (Configure, Action-Status, Data, Utility), and Private (if applicable)
5.3 Palette menu files: dir.mnu (top level), Action-Status.mnu, Data.mnu, Utility.mnu. Configure.mnu (Public folder)
5.4 Readme (e.g., Agilent 34401 Readme.htmlb, Fluke 45 Readme.html).
5.5 (Recommended) For a detailed review, copy of programming manual of the instrument

The <labview>/instr.lib subdirectory contains subdirectories for all installed LabVIEW Plug & Play instrument drivers. The name of each instrument driver subdirectory is the driver prefix. This subdirectory all instrument driver files. For example, the Agilent 34401 DMM instrument driver files reside in the <labview>/instr.lib/Agilent 34401 subdirectory.

For distribution, each instrument driver is compressed as a .zip file. The name of the zip file is driver_identifier.zip, such as agilent_34401.zip. Creating a .zip file provides a convenient way to keep track of all your instrument driver files. Files can be archived using common utilities such as 7Zip. Create the zip file so that it automatically creates a subdirectory with the prefix name. This prevents users from overwriting files in the root <labview>/instr.lib directory accidentally.

6. Submit the completed instrument driver to the Instrument Driver Network.