Developer Center Resources

cancel
Showing results for 
Search instead for 
Did you mean: 

Add-on Development Guidelines

» LabVIEW Tools Network » Add-on Development Guidelines

 

Note: The guidelines outlined in this document are based upon the requirements for the LabVIEW Tools Network. 

Installation

  • Ensure installer defaults to the correct LabVIEW directory supported by the add-on or provides the user with a choice of which version(s) to install support for.

Activation/Purchase

  • Consider implementing a trial period for add-ons with licensing.

  • Be aware of the behavior of the add-on when the trial period expires. Does this behavior have a potential negative affect on customers?

    • For example, if a run-time licensing check is performed and a trial/license is expired/invalid does the code elegantly finish execution or is execution halted? Halting execution in this situation may leave hardware in an undesired or unknown state if other drivers/APIs are used in the application.

  • Document activation and purchase process for users.

    • When a trial expires, it should be obvious to a customer they need to purchase a license for the add-on. Documenting this process is important to prevent any confusion for the customer. Also , make the process of activation obvious to a customer and direct the customer to documentation instructing them “how to activate” following the purchase of an add-on.

  • Consider providing multiple options for a customer to purchase a license.

    • Some examples are to purchase over the phone, over the web, and purchase via email.

Support

  • Document the support process for customers.

    • If a customer needs help beyond what is found in the documentation provided with the product, where should they go? NI provides access to NI Community pages which can be used as a method for customers to communicate with the support group from your company. Aside from this, telephone, email and forum support are common methods for providing customer support, but do not expect NI to provide support for your product.

Updates/Upgrades

  • The upgrade and update process must be documented for customers.

    • How will your customers receive and install updates?

Design Practices

  • API Architecture and Design

    • Adhere to design guidelines and be consistent when developing the API; doing so ensures consistency within the API itself and with other similar APIs.

    • Design the API for use in simple and advanced applications.

      • When designing your API, make common functions obvious to users, but allow for advanced applications. Design your API so the most common 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.

    • Design VIs that give users the appropriate amount of control over desired functionality. Design VIs for reuse as subVIs.

      • An API with a few high-level VIs might not give the user enough control of a desired operation. An API with many low-level VIs might be too complicated for users unfamiliar with 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.

        It is acceptable to include low-level VIs that allow users more control over 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.

    • Design VIs to work well with other VIs in the API.

      • Design the data types and terminal patterns of each VI to work well together. For example, instrument drivers would use a consistent channel control throughout the driver VIs. Ensure the consistent 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.

    • Use error in and error out parameters, along with other parameters consistent in your VIs to help users control data flow and to force data dependency in their applications.

      • Data flow determines the order in which LabVIEW programs execute. Design APIs so users can take advantage of this paradigm. By using error in, error out, and other parameters consistent in each of the 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 of the API 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.

VI Names and Properties

  • Use a consistent naming convention for all instrument driver VIs.
    • Use meaningful names that describe what operation the VI performs.

    • Use complete English words unless an abbreviation is known by users worldwide.

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

  • Do not use the word "Example" in the name of API VIs. Use "Example" to identify example VIs that are not part of the API VIs. If you create Example Finder data (.bin3) files for examples in LabVIEW 8.0 and later, avoid including the word "Example" in the example VI name.

    • Examples are not considered part of the API, so each example can change with each revision of an API. API palette VIs should maintain consistency between releases to support upgrades for customers, if changes are made to API palette VIs this should be documented in the release notes or upgrade notes for the product.

Controls/Indicators

  • Give controls and indicators names that describe their function.

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

  • Give a Boolean control a name that clearly identifies the behavior associated with the Boolean states. When possible, assign a name that indicates the default state of the Boolean control.

  • Use text rings for controls that have a natural association to several discrete possibilities and the possibilities have no numeric content.

  • Use data types that minimize the amount of conversion, formatting, and parsing by the user.

  • Avoid strings as controls and indicators.

    • Avoid using strings as input parameters. If the set of strings the user can pass as an input 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.

Front Panels

  • Consistently place common controls and indicators in the same location on each front panel.

    • Include a common reference input in the API in the upper left corner and the corresponding output in the upper right corner, 'error in' in the lower left corner, and 'error out' in the lower right corner.

  • Set default values for each control. Do not set default values of indicators like graphs, arrays, and strings.

    • Choose a default value 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 API 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.

  • Use the appropriate display format for the control.

    • In most cases, use automatic formatting for numeric controls and indicators.

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

  • Use a standard format for control and indicator labels.

    • Fonts vary by platform, user system preferences, and video driver settings. Therefore, text might appear larger or smaller on different systems. Right-click the label and ensure the Size to Text is selected in the shortcut menu to allow extra space for larger fonts. Use carriage returns to create multi-line text labels instead of resizing the text label.

    • Include default values in each control name so they appear in the Context Help window for the VI. End users use the Context Help window to determine whether they need to wire an input into the VI. The Context Help window in the figure below appears with default values. Units for the control appear in parentheses. Use plain text for the default values so users do not confuse them with the control names, which appear in bold, when viewing the front panel.

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

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

  • Ensure all front panel controls are visible on the front panel

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

  • Align and distribute the controls for better front panel layout.

    • Use the Align Objects tool and the Distribute Objects pull-down menus to create a uniform layout.

Icons and Connector Panes

  • Create an icon for each VI that identifies the instrument and conveys the functionality of the VI.

    • Consistently use a common theme for all VIs for a API or group of VIs within an API.

    • The banner at the top of the icon helps users identify the API.

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

  • Standardize the connector pane pattern.

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

    • Consistent use of the same terminal pattern makes the wiring of inputs and outputs consistent among an API and error clusters easy to align. Inconsistent connector pane assignments within an API results in poor wiring for the end users. If you need more terminals than the recommended patterns, reconsider the grouping of the controls and indicators on the VI.

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

  • Standardize the terminal assignments on the connector pane.

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

    • Assign the consistent input (reference wire) in an API to the upper left terminal and the consistent output in an API 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.

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

  • Use appropriate Required, Recommended, and Optional settings on the connector pane.

    • Make the input consistent among API VIs a required input.

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

Block Diagrams

  • Use consistent style and placement of terminal labels. Justify text appropriately.

    • Use plain text labels for controls/indicators.

    • Labels on the block diagram improve the readability of your VIs; which will not only make your code easier to maintain and debug moving forward, but will also provide your customers with an API that is easier to learn and customize.

  • Include error handling in all VIs that contain subVIs with error handling.

    • Do not change the error codes defined by National Instruments or other APIs

  • Leave enough space between nodes on the block diagram. Do not overlap or cover objects on the block diagram.

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

  • Use a Select function, not a Case Structure , to select between two wire options.

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

  • Position the diagram to open in the top left corner of the screen.

    • Save the block diagram so that it opens in the upper-left corner of the screen so most users can view the block diagram with minimal or no scrolling.

Palette Design

  • Organize all user-accessible VIs into a hierarchy of menu palettes.

    • Ensure the most commonly used VIs appear at the higher levels of your palettes and top rows within the palette.

    • Do not include subpalettes if the sub-menu does not contain any VIs.

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

      • Most users access the API VIs through the palettes. Therefore, ensure the API 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.

      • Consistency in organization between APIs helps users who are familiar with one API to quickly navigate a new API. This increases the ease of use of all APIs. Therefore, ensure that your API follows one of the menu structures shown in the figures above, depending on your LabVIEW version.

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

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

    • 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 API .mnu files in a file browser.

  • When choosing the palette location for an add-on, do what makes sense for the API.

    • Place API functions in a palette with other similar functions. For instance, if an add-on API is developed to provide advanced file I/O functionality, it would make sense to place this palette in the 'File I/O' palette. Similarly, a driver API for an instrument should be stored within 'Instrument I/O > Instrument Drivers'.

    • Palettes can be stored in their own category or as a subpalette in an existing palette category.

Menu Integration and Dialog Windows

  • Menu items are placed in LabVIEW\project, LabVIEW\wizard, and/or LabVIEW\Help.

  • Set the window title for dialog windows to not include ".vi".

  • Use system controls and indicators in dialog windows.

  • Set the background color for dialog windows to “Panel and Object”.

  • Set the Window Appearance for dialog windows to Dialog (File > VI Properties > Window Appearance).

  • Remove the abort button from dialog windows.

  • Set the run-time position of dialog windows to “centered”.

  • Dialog windows are to “run when opened”.

  • Follow the same style as NI dialog windows.

  • Include Help buttons in dialog windows linking to the LabVIEW Online Help.

Support Files: Location and Documentation

  • Add-ons must contain an 'Online Help' or a help document linked to from the context help windows and it must be accessible from the Help menu.

  • Write a VI Description for each VI in order to provide context help window documentation.

    • Include any information necessary to successfully use the VI.

    • Include any VI calling dependencies necessary for VI operation, such as calling Initiate before Fetch.

    • Document any restrictions for using the VI.

    • Include critical information on the front panel of the VI and in the VI Description.

    • Generally, users rely on the context help for information about the API. 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 APIs help minimize technical support issues.

      • The description should contain a general description of the API VI, including any control usage rules or VI interaction necessary to use the API. 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.

    • Add links to Help documents to the Context Help

  • Help documents should be linked to from the Help menu

    • Help documents can be created as HTML files, Microsoft Comiled HTML Help (.chm) files, Microsoft WinHelp (.hlp) files, or a VI can be called to launch a file of another format (such as a PDF).

    • Any .chm, .hlp, or .vi files placed in the LabVIEW\help\ directory will auto-populate in the LabVIEW Help menu. It is important to follow naming conventions outlined in the File and Folder Names for Integrating into LabVIEW document.

  • Write descriptions for each control and indicator.

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

Templates: Location and Documentation

  • Template VIs are stored in LabVIEW\templates\Company Name\Product Name or LabVIEW\templates\CompanyPrefix Product Name.

  • Template VIs contain free labels instructing the user for how to make use of the template.

Examples: Location and Documentation

  • Example VIs are located in LabVIEW\examples\Company Name\Product Name.

  • Create example VIs that show users how to build their applications.

    • Provide examples with source code. Call user-accessible VIs to teach users how to use the API. Examples help users understand the recommended calling sequence necessary to perform operations. If a simple example calls an excessive number of API VIs, the API might need a more appropriate level of granularity.

  • Use free labels to document examples.

    • Example VIs are often the method used by LabVIEW developers to learn how to use an API and if the example does not make sense or is not documented, your customers will have trouble learning how to use your product.

  • Create self-contained and runnable example VIs.

    • 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 and contains free labels describing execution step-by-step.

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

    • Example VIs are not part of the 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.

  • Create a separate example for each typical add-on use case.

    • Users expect most add-ons to include an example for each typical use case. Including multiple examples benefits a wider range of customers.

  • Give the example a meaningful name.

    • Use names in the example VIs that describe the operation the VI performs.

  • For add-ons which do not contain an API, useful examples include videos demonstrating use of the product and walk-through documents complete with screenshots.

Error Codes

  • Error codes are defined in the Online Help document for the add-on.

  • Error codes are stored in a .txt file in project\errors.

  • Error code files are to be named CompanyPrefix-ProductName-errors.txt.

  • Error codes for end-users fall in the range of 5000 to 9999 and -8999 to -8000.

    • For program applicants, a reserved set of error codes are available upon request from the Product Partner team.

Custom Probes

  • Custom probes are available for custom or complex data types, common to the add-on, to aid users in debugging applications.

  • Custom probes are stored in vi.lib\_probes\ and can be accessed through the right-click menu under 'Custom Probes'.

  • Custom probes are to be named based upon CompanyPrefix-ProductName-filename.vi

Real-Time Compatibility

  • Follow design practices outlined for Real-Time systems.

    • It is important to follow design guidelines to avoid unnecessary memory copies, repeated access to the memory manager, and other functions or operations which affect the determinism of the Real-Time system.

  • Add-ons intended for use on Real-Time systems are developed to have as little affect as possible on the determinism of a system.

  • Specific features of an add-on are documented to show compatibility for time critical or normal priority sections of code.

  • Please contact NI Partner Program team for further information regarding compatibility testing for add-ons meant to be compatible with LabVIEW Real-Time

Deployment

  • Add-on APIs must work when included as support files in an executable unless otherwise documented.

  • A deployment/licensing solution has been considered/implemented to support building API functions into deployed LabVIEW executables.

Testing

  • Test both API VIs and Example VIs

    • Invalid calling orders or dependencies should be handled robustly by the API. 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 API is complete.

  • Test a variety of API error reporting and recovery conditions.

    • If the API interfaces to hardware, test the API with hardware 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 errors. Abort an API example during execution and verify that the example can be run again without error.

  • It is important to test an add-on for endurance

    • This involves executing as many possible code paths continuously for an extended period of time without halts or failures

    • Endurance testing can be qualified as:

      • Level 1 – Months

      • Level 2 – Weeks

      • Level 3 – 24-48 hours

  • When testing, it is important to evaluate the memory and CPU use on the system to determine if there are any memory leaks or sections of code where unnecessary CPU resources are reserved.

Contributors