FlexLogger Plugin Development Kit Manual - National …FlexLogger Plugin Development Kit examples...

$: FlexLogger Plugin Development Kit Manual - National …FlexLogger Plugin Development Kit examples can be found in \ National Instruments\LabVIEW 2019\examples\FlexLogger.$
FlexLogger Plugin Development Kit ManualVersion 1.0

ContentsGetting Started.......................................................................................................................... 2

Installation ........................................................................................................................ 2Using the Wizard .............................................................................................................. 2Building a Plugin .............................................................................................................. 5Why Is There an XML File?............................................................................................. 5Importing into FlexLogger ............................................................................................... 5

Loading Plugins from Additional Locations ........................................................... 6Using Plugins in FlexLogger ............................................................................................ 6

Channels—Data Produced by the Plugin ................................................................. 8Channels—Data Sent to the Plugin .......................................................................... 9

Versioning ........................................................................................................................ 9Examples .......................................................................................................................... 10Getting Started with Plugin Development........................................................................ 11FlexLogger Palette in LabVIEW...................................................................................... 13

FlexLogger Plugin LabVIEW Classes (PluginSDK.lvlibp) ..................................................... 14Processing Element (Processing Element.lvclass) ........................................................... 14

Timing the Process State .......................................................................................... 16Plugin (Plugin.lvclass)...................................................................................................... 16Channel (Channel.lvclass) ................................................................................................ 16

Writing Channel Data from a Plugin to FlexLogger ................................................ 17Reading Setpoint Channels from FlexLogger .......................................................... 18Create Channel.vi ..................................................................................................... 19Channel-Specific Parameters.................................................................................... 20Dynamic Channels.................................................................................................... 20

System Interface (System Interface.lvclass)..................................................................... 20Additional Classes ............................................................................................................ 21

Plugin Debugging ..................................................................................................................... 21Loading Plugins into FlexLogger ..................................................................................... 21Viewing Errors in FlexLogger.......................................................................................... 22Interactively Testing Plugins ............................................................................................ 22

Interactive Debugging Session Example.................................................................. 25

2 | ni.com | FlexLogger Plugin Development Kit Manual

Getting Started

Installation1. Install LabVIEW 2019 64-bit.

2. (Optional) Install FlexLogger 2019 R3 or higher.

3. Open NI Package Manager and search for FlexLogger Plugin Development Kit.

4. Select FlexLogger Plugin Development Kit and click Install.

5. Follow the instructions on the following screens to complete installation.

Using the Wizard1. Launch LabVIEW.

2. In LabVIEW, select File»Create Project.

FlexLogger Plugin Development Kit Manual | © National Instruments | 3

3. From the Create Project window, select FlexLogger IO Plugin.

4. In the Create FlexLogger IO Plugin window, update the IO Plugin Name and select a Plugin Template from one the following options:

• Consume data from FlexLogger—This template is appropriate for instruments that need to be controlled while FlexLogger acquires data, such as a programmable power supply. The template plugin defines two channels that receive setpoint data from FlexLogger to control a third-party instrument.

• Produce data for FlexLogger—This template is appropriate for third-party instruments that continuously acquire data. To demonstrate data acquisition, the template plugin generates two channels of data with a constant value of zero.


5. Update the Description and Destination Directory (Source) for the plugin, if desired. By default, the wizard saves new plugins into the My Documents\LabVIEW Projects\FlexLogger IO Plugins\ directory.

The wizard creates a new LabVIEW project with the necessary dependencies, new LabVIEW class, corresponding XML file, and Packed Library build specification.


Building a PluginIn the LabVIEW project created by the wizard, the build specification is ready to build. Without any developer modification, plugins created using both the Produce data for FlexLogger template and the Consume data from FlexLogger template can be built and run in FlexLogger.

After building, the resulting build destination contains a folder with the plugin’s packed library and XML file. For example, the MyFirstPlugin build specification creates a MyFirstPlugin folder containing MyFirstPlugin.lvlibp and MyFirstPlugin.xml. By default, the build specification will build the plugin into the directory FlexLogger uses to load plugins. Refer to the Importing into FlexLogger section for more information.

Why Is There an XML File?FlexLogger uses the XML file to register and load the plugin for use at run-time. The project wizard scripts the XML file and adds it to the plugin’s LabVIEW project. It contains the plugin name and description. The XML file’s name must match the plugin’s packed library name. If there are no naming or version changes after the plugin is created, no manual changes to the XML file are necessary.

Importing into FlexLoggerWhen it launches, FlexLogger loads plugins from %public%\Documents\National Instruments\FlexLogger\Plugins\IOPlugins.

For example, a plugin named PowerSupply would have the following path: %public%\Documents\National Instruments\FlexLogger\Plugins\IOPlugins\PowerSupply. The PowerSupply folder contains the corresponding


PowerSupply.lvlibp and PowerSupply.xml files. The folder name must exactly match the contained plugin file names.

FlexLogger projects must be closed and re-opened to consume new or modified plugins.

Loading Plugins from Additional Locations To load a plugin from a different location, users can add a configuration file that specifies additional absolute paths to load plugins from. The file should end in a .config extension and be placed in the root directory of %public%\Documents\National Instruments\FlexLogger\Plugins\IOPlugins. The configuration file must use the following JSON format:

{"AdditionalPluginPaths":["C:\\Users\\<username>\\Documents\\FlexLoggerProjects\\ ","<another absolute path>"]}

Using Plugins in FlexLoggerTo add plugins in FlexLogger, click the Add plugin button in the Channel Specification document. If FlexLogger did not load any plugins on launch, the Add plugin button will not appear. For troubleshooting plugin appearance issues, refer to the Importing into FlexLogger and the Plugin Debugging sections.

All plugins imported into FlexLogger appear as selectable options:

If your plugin is not appearing in the drop-down menu, refer to the Plugin Debugging section for more information.


To configure plugin-level parameters, click the Configure gear icon that corresponds to the plugin:

FlexLogger automatically generates dialogs for parameters as defined by plugins:

Parameters cannot be modified while a FlexLogger test is running (the Start Test button has been clicked).

Use the Delete button to remove plugins from your project.


Channels—Data Produced by the PluginFor plugins like the Produce data for FlexLogger template, the plugin generates channel data and sends it to FlexLogger. For these channels, the channel configuration dialog allows users to rename channels and configure channel-specific parameters. The dialog also provides a live value graph to visualize the channel’s waveforms:

The channel name can also be renamed by double-clicking the channel name in the Channel Specification table. The Live value column displays the latest data point, so the data can be previewed with the channel dialog closed.


Channels—Data Sent to the PluginFor plugins using the Consume data from FlexLogger template, the FlexLogger application sends setpoint values to the plugin’s channel. Those channel values can then be used to control a third-party output device. The channel value can be changed using the Value field in the channel configuration dialog:

Alternatively, the channel value can be modified directly in the Live value column:

VersioningWhen a plugin is created it is given a version number as defined by the <Version> tag in the plugin’s XML file and an oldest compatible version number as defined by the <OldestCompatibleVersion> tag. Developers can change these numbers to reflect any updates that are made to the plugin behavior after the plugin has been used in a FlexLogger project.

FlexLogger does not support plugins with identical names. If a developer makes a breaking change to their plugin, they should update both the version and the oldest compatible version. Those updates tell FlexLogger to not load any plugins that have were saved with a lower version.


However, if a developer makes a non-breaking change, they may want to update the version to communicate that changes were made.

ExamplesFlexLogger Plugin Development Kit examples can be found in <Program Files>\National Instruments\LabVIEW 2019\examples\FlexLogger. Table 1 describes the available examples:

To load either of the IVI examples, the IVI Compliance Package must first be installed from NI Package Manger. Additionally, an IVI compliant instrument driver is necessary for the IVI Meter example in order to read voltage values from an instrument. Likewise, an IVI DC Power compliant instrument driver is needed for the IVI DC Power Supply example in order to control a power supply.

The examples include a LabVIEW-only VI that demonstrates how to map functionality from a standalone VI to a FlexLogger plugin class. For example, the Mouse Input LabVIEW project contains Mouse Input - LabVIEW Only Example.vi that describes how different parts of the block diagram correspond to the VIs in Mouse Input.lvclass:

Table 1. Plugin Examples

Name Type Description

Mouse Input Produce data for FlexLogger Reads mouse data from the mouse connected to the computer

IVI DC Power Supply

Consume data from FlexLogger

Uses the IVI DC Power class driver to control a power supply instrument

IVI Meter – DC Voltage

Produce data for FlexLogger Read DC voltage values from an IVI DMM class driver compliant instrument


Getting Started with Plugin DevelopmentAs described in the Using the Wizard section, new FlexLogger plugins are created through LabVIEW’s Create Project menu. If a developer names their plugin MyFirstPlugin, the wizard creates the following file hierarchy:

The VIs inside MyFirstPlugin.lvclass are the starting point for code changes. These VIs perform different roles, such as defining parameters and reading data from/writing data to FlexLogger. This functionality is described in detail in the Processing Element (Processing Element.lvclass) section. State information—like a hardware reference—can be passed between the MyFirstPlugin VIs using the class private data defined in MyFirstPlugin.ctl.

Table 2. LabVIEW Project Files

File Name File Type

MyFirstPlugin.lvproj LabVIEW Project

MyFirstPlugin.lvlib LabVIEW Library

MyFirstPlugin.lvclass LabVIEW Class


When planning a FlexLogger plugin, it is helpful to have an existing LabVIEW VI that communicates with the third-party instrument. This LabVIEW-only functionality allows for hardware and driver testing before beginning plugin development. As mentioned in the Examples section, the example plugin projects include a LabVIEW-only VI that demonstrates how to map functionality from a standalone VI to a FlexLogger plugin class.

After reviewing the examples, use the following questions to guide the design of a plugin:

• How many channels are needed?

• Refer to the Channel (Channel.lvclass) section for details on how plugin channels communicate with FlexLogger.

• How many plugin-level parameters are needed?

• These are parameter values that affect the entire plugin—for example, a hardware resource name.

• Refer to the Plugin (Plugin.lvclass) section.

• How many channel-specific parameters are needed?

• These parameter values are unique to every channel and are defined when creating new plugin channels.

• Refer to the Channel (Channel.lvclass) section.

• What data needs to be passed between plugin VIs?

• For example, if an instrument session is initialized in Configure Session.vi, it needs to be passed to Process.vi for use and then to Cleanup Session.vi for disposal.

• Important plugin information can be stored in the plugin’s private class data (for example, MyFirstPlugin.ctl).

When developing a plugin, there are two approaches to evaluate a plugin’s functionality. Both options execute the plugin’s logic and allow developers to investigate the effect of code changes.

• Loading the plugin into FlexLogger. Refer to the Importing into FlexLogger section for more information.

• Running the plugin with the Plugin Environment Simulator. Refer to the Interactively Testing Plugins section for more information.


FlexLogger Palette in LabVIEWTo facilitate plugin creation, installing the Plugin Development Kit adds the FlexLogger palette to the LabVIEW Functions palette.

The palette provides the plugin and channel methods needed to interact with the FlexLogger application. For more information on the methods contained in the palette, refer to the FlexLogger Plugin LabVIEW Classes (PluginSDK.lvlibp) section.

Figure 1. FlexLogger Palette in LabVIEW


FlexLogger Plugin LabVIEW Classes (PluginSDK.lvlibp)In the FlexLogger Plugin Development Kit, PluginSDK.lvlibp contains the classes and VIs used for plugin development. Plugin developers will mostly interact with the Plugin and Channel classes.

If you are unfamiliar with LabVIEW object-oriented programming, refer to the LabVIEW Object-Oriented Programming topic in the LabVIEW Help for conceptual and how-to documentation. To access this topic, visit ni.com/r/lvobjectprog.

Processing Element (Processing Element.lvclass)The Processing Element class defines the plugin execution states. FlexLogger’s data engine manages the transitions between these states. Refer to Figure 2 and Table 3 for more information on how FlexLogger plugins manage state.

Figure 2. FlexLogger Plugin Execution State Management Flow

http://www.ni.com/r/lvobjectprog


Table 3. FlexLogger Plugin Methods

Method Description

Initialize Runs only once—When plugin added in the FlexLogger Channel Specification.

Defines the timing method used by the Process state.

Declare the plugin-level parameters users interact with in FlexLogger.

Declare the channels (and corresponding channel parameters) the plugin will read data from or send data with.

Configure Session Initialize and configure hardware/instrument sessions.

Runs after Initialize

Runs when a configuration change is detected and FlexLogger is not running a test.

Read the latest channel parameters set in FlexLogger.

Read the latest plugin-level parameters set in FlexLogger.

Set the timing information (dt, T0) for data written to FlexLogger in the Process state.

Read what channels FlexLogger reports as valid (channels defined by the plugin may be modified in FlexLogger).

Process Read from and write to third-party hardware.

Read channel data from FlexLogger.

Write channel data to FlexLogger.

Cleanup Session Clean up the hardware sessions and resources initialized by the Configure Session state.

Runs when a configuration change is detected.

Finalize Runs when the plugin is being shut down, during either FlexLogger project close or when the plugin is removed

Clean up any resources initialized during the Initialize state.

Commonly empty.


Timing the Process StateIn the Initialize state, Plugins set the Timing Parameters that control how the Process state executes.

Plugin (Plugin.lvclass)The Plugin class is the parent class for plugins created with the FlexLogger Plugin Development Kit. It provides the plugin’s state management functionality by inheriting from Processing Element.lvclass. The Plugin class also provides methods to define and interact with plugin channels and parameters. After the channels are initialized, the Plugin class maintains channel information that correctly reflects the state of the plugin channels in the FlexLogger application.

The Plugin class supports double-precision floating point numbers, strings, enums, booleans, and integers as plugin-level parameters. Plugin-level parameters can be created by using the Plugin class’s Write Parameter.vi, as shown in the following example:

Channel (Channel.lvclass)The Channel class allows plugins to send data to the FlexLogger application and read setpoint data from the FlexLogger application. The Plugin class uses the Channel class to organize channels and ensure the plugin and the FlexLogger application agree on what channels should exist.

Table 4. FlexLogger Plugin Process State Timing Parameters

Timing MethodTiming Period (ms)

required? Description

Periodic Yes With a timing period of n, periodic timing ensures at least n milliseconds between runs of the Process state.

Immediate No Run Process without delay. This method is typically used when a blocking call inside the Process state controls timing.

On Data Ready No For use by plugins that read channel data from FlexLogger—such as the Consume data from FlexLogger template. On Data Ready blocks execution of Process until FlexLogger sends new channel data to the plugin.

Triggered No Not applicable for IO Plugin development


Writing Channel Data from a Plugin to FlexLoggerAs demonstrated by plugins created from the Produce data for FlexLogger template, plugins can publish data from their data source to FlexLogger:

Figure 3. IO Plugin Data Flow for Production of Data for FlexLogger

To create a channel that can send data to FlexLogger, use the Produced by Plugin option in Create Channel.vi:

When sending data to FlexLogger, writing waveforms that overlap in time can disrupt FlexLogger’s visualization and logging capabilities. Using the Plugin class’s Set Stream Timing.vi and Write Data.vi to send data to FlexLogger protects plugin developers from waveform overlap errors. For example, Set Stream Timing.vi defines the waveform dt and Start Time timing parameters in the Configure Session state:


Since Configure Session always executes before the Process state, the output channels timing information updates after every configuration change. Write Data.vi allows the Process state to write channel data to FlexLogger in either a one or two-dimensional array of doubles:

Reading Setpoint Channels from FlexLoggerPlugins created from the Consume data from FlexLogger template read channel values from FlexLogger and use those values to control third-party output devices:

Figure 4. IO Plugin Data Flow for Consumption of Data from FlexLogger

To create a channel that can consume setpoint channel information from the FlexLogger application, use the Setpoint consumed by Plugin option in Create Channel.vi:

As demonstrated in the Consume data from FlexLogger template’s Process.vi, the Plugin class’s Read Latest Setpoints.vi extracts the most recent scalar value and provides a one-dimensional array of setpoints (one per channel):


In the IVI DC Power Supply example, the setpoint value read from FlexLogger is used as the level input to set the Power Supply’s DC voltage level:

Create Channel.viAs described in the previous sections, Create Channel.vi allows users to create two types of channels, Produced by Plugin and Setpoint consumed by Plugin. Creating channels involves the following information:

FlexLogger allows users to change a channel’s Default Channel Name from both the channel configuration dialog and directly in the Channel Specification table. Additionally, FlexLogger requires all channels in the Channel Specification to have unique names—and will automatically

Table 5. Plugin Channel Components

NameLabVIEW Data Type Description

Unique Channel Identifier

string Channel identifier that is unique in the plugin context. Displayed in the far-left Channel Specification column (for example, ai0 for a DAQ channel).

Default Channel Name string Channel name in FlexLogger.

Display Group string Name used in Channel Specification header and channel selector.

Unit string Channel units (for example, Hz).

Can Disable? Boolean Should users be able to disable this channel? False by default.

Default Value Double Setpoint consumed by Plugin channels allow plugin developers to set the default value that appears in FlexLogger when the plugin is added.

dt(sec) Double If Produced by Plugin channels use the 1D Wfm (DBL) option provided by Write.vi, this parameter tells the FlexLogger application what dt to expect.


change a plugin channel name if that rule is violated (for example, myChannel becomes myChannel_1). Regardless of the change to Default Channel Name, the Unique Channel Identifier parameter remains unchanged.

Channel-Specific ParametersThe Channel class supports double-precision floating point numbers, strings, enums, booleans, and integers as channel-level parameters. Channel-specific parameters can be created by using the Channel class’s Write Parameter.vi, as shown in the following example:

Dynamic ChannelsTo help developers work with dynamic channels—such as when names change or channels are disabled—plugins maintain an array of valid channels. Wiring a property node to a plugin class wire provides direct access to the ValidProducerChannels, and ValidConsumerChannels arrays:

Knowing what channels are valid allows developers to configure their plugins correctly and produce the right data for the available channels.

System Interface (System Interface.lvclass)The System Interface class defines the execution environment interacting with a FlexLogger plugin. When FlexLogger loads and runs a built plugin, the plugin will communicate with FlexLogger’s underlying data engine. When debugging a plugin in the Plugin Environment Simulator, the plugin will communicate with a simplified, test-specific environment.


Additional ClassesThe following classes belong to PluginSDK.lvlibp and are outside the scope of FlexLogger plugin development. These classes should not be used in your plugins.

Plugin Debugging

Loading Plugins into FlexLoggerIf FlexLogger fails to parse a plugin’s XML file, the plugin will not be available for users to add in the Channel Specification. In case of parsing failure, an Error.txt file will be created in the plugin’s folder with details about the problem.

Table 6. Additional Classes Not Used in Plugin Development

Class Name Summary

Addon Interface.lvclass Defines the communication between plugins and FlexLogger

Message Completion Handler.lvclass

Messaging functionality for classes that do not inherit from Plugin.lvclass

Parameters.lvclass Provides the parameter functionality for the Channel and Plugin classes.


Viewing Errors in FlexLoggerBecause the Plugin class provides built-in error handling, it is important that developers wire their error wires to the provided error out terminals. For example, IVI class driver VIs publish errors on their error wires when they are initialized incorrectly. Wiring the error terminals from those driver VIs to the error out terminal ensures errors appear to users in FlexLogger:

Users receive three distinct error notifications:

• Detailed errors in the Errors and Warnings pane

• An error icon on the plugin’s header

• The Error indicator by the Stop Test buttons.

Interactively Testing PluginsWhen plugins load and run in FlexLogger, the application’s compiled data engine and the compiled plugins prevent interactive debugging with LabVIEW. The Plugin Environment Simulator provides a simplified, test-specific environment that allows developers to run and debug plugins from the source G code.

The Plugin Environment Simulator installs to %ProgramFiles%\National Instruments\LabVIEW 2019\resource\FlexLogger\SDK\Plugin Environment Simulator.


To enable interactive debugging of Plugin source code, the Simulator is provided as a VI:

To debug a plugin, open and run Plugin Environment Simulator.vi. When the Simulator starts running, it prompts the user for the Plugin class to debug. The following is the Simulator running an unmodified Produce data for FlexLogger plugin:


The Configure Plugin Parameters button allows users to update plugin-level parameters:

Similarly, the Configure Channel Parameters allows developer to update channel-specific parameters:


Plugins following the Consume data from FlexLogger template do not write any data to FlexLogger, so the Channel Data chart shows the current setpoint values. The Update Setpoint Channels button provides the input information needed to write the correct values to an external system. The following figure shows setting the setpoint for the IVI DC Power Supply example:

Interactive Debugging Session ExampleThe following scenario illustrates how the Plugin Environment Simulator could be used to investigate an issue with a plugin under development.

1. After loading and configuring the DMM plugin, the plugin channel does not produce any data. In the FlexLogger Error and Warning pane, the error message references a problem in the Configure Session VI.

2. To investigate further, open and run Plugin Environment Simulator VI, and then select the DMM plugin LabVIEW class.

3. After updating the plugin-level parameter that defines the IVI Logical Name to test channel, the simulator stops running and the Runtime Information error terminal displays an error:


4. To investigate further, run the Plugin Environment Simulator again and select the DMM plugin class. This loads the plugin source into memory, so you can open the plugin VIs and add probes and breakpoints. In the Plugin Environment Simulator Configure Device Parameters case, open Reconfigure Plugin.vi and inspect the block diagram:

5. Notice that this VI calls the Configure Session VI. Double-click on Processing Element.lvclass:Configure Session.vi to open the DMM plugin’s Configure Session VI:

6. With Configure Session VI open, add a breakpoint and several probes to see what part of the logic is generating the error:

© 2019 National Instruments. All rights reserved.

378089A-01 Jul19

Information is subject to change without notice. Refer to the NI Trademarks and Logo Guidelines at ni.com/trademarks for more information on NI trademarks. Other product and company names mentioned herein are trademarks or trade names of their respective companies. For patents covering NI products/technology, refer to the appropriate location: Help»Patents in your software, the patents.txt file on your media, or the National Instruments Patents Notice at ni.com/patents. You can find information about end-user license agreements (EULAs) and third-party legal notices in the readme file for your NI product. Refer to the Export Compliance Information at ni.com/legal/export-compliance for the NI global trade compliance policy and how to obtain relevant HTS codes, ECCNs, and other import/export data. NI MAKES NO EXPRESS OR IMPLIED WARRANTIES AS TO THE ACCURACY OF THE INFORMATION CONTAINED HEREIN AND SHALL NOT BE LIABLE FOR ANY ERRORS. U.S. Government Customers: The data contained in this manual was developed at private expense and is subject to the applicable limited rights and restricted data rights as set forth in FAR 52.227-14, DFAR 252.227-7014, and DFAR 252.227-7015.

7. With the breakpoint in place, go to the front panel of the simulator and configure the plugin-level parameter again. That action will hit the newly placed breakpoint. Using LabVIEW’s debugging tools, step through the block diagram to see exactly which VI is having problems:

8. After this debugging session, you should see that the plugin has been using the wrong the IVI Logical Name. The plugin runs as expected when started using the correct name.

FlexLogger Plugin Development Kit Manual - National …FlexLogger Plugin Development Kit examples...

Documents

Transcript of FlexLogger Plugin Development Kit Manual - National …FlexLogger Plugin Development Kit examples...