Control/Indicators: Naming and Data Representation

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.

Recommended

• Use book title form (examples: Input Impedance, Number of Averages) for control and indicator labels.
• 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.
• Include unit information if applicable in the labels using SI notation, such as Amplitude (10.0 V).
• Match the units of the default value in the label to the units of the control.

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

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

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.

Recommended

• Use the waveform data type when your VI acquires or generates analog waveforms.
• Use paths instead of strings for file path names.
• Use the time stamp data type for time and date information.
• 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.

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.

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.

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.

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.