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.
- Icon Art Glossary
- Developing LabVIEW Plug and Play Instrument Drivers
- Development Tools
- Submit a Driver
|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|
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.
|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|
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.
|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.
The following block diagram consists of subVIs designed with inconsistent terminal patterns, which leads to inconsistent controls and wiring.
|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 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.
|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.
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.
|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.
|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|
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.
|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|
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.
|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.|
|3.||Choose a Boolean control to represent values with two easily understood opposite states, such as True/False or On/Off||View|
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.
|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|
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.
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.
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.
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.
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.
|5.||Use data types that minimize the amount of conversion, formatting, and parsing by the user.||View|
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.
|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|
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.
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.
|1.||Consistently place common controls and indicators in the same location on each front panel.||View|
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|
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|
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.
|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.
|8.||Be consistent when using Modern 3D controls.||View|
Using a consistent style of control helps create a professional-looking user interface.
|10.||Use a consistent style for all Boolean and Numeric controls.||View|
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.
|1.||Create an icon for each VI that identifies the instrument and conveys the functionality of the VI.||View|
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.
Use a white background for your icons to adhere to good design practices.
|2.||Standardize the connector pane pattern.||View|
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.
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.
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|
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|
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.
|1.||Use consistent style and placement of terminal labels. Justify text appropriately.||View|
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|
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.
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|
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.
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|
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.
|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.
|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.
|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|
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.
|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.
|1.||Write a VI Description for each VI.||View|
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.
|3.||Write descriptions for each control and indicator.||View|
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.
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.
|5.||Include the following items in the Readme file included with your driver:||View|
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.
|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.
|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".
|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
|1.||Organize all user-accessible VIs into a hierarchy of menu palettes.||View|
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.
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.|
|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|
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|
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.
|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|
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.|