Asynchronous Custom Devices

NI VeriStand 2018 Help

Edition Date: May 2018

Part Number: 372846M-01

»View Product Info
Download Help (Windows Only)

Parent Topic: Custom Device Types

An asynchronous custom device executes in a parallel loop with the VeriStand Engine's Primary Control Loop (PCL) and uses RT FIFOs to exchange channel data with the rest of the NI VeriStand system. This topic describes a standard asynchronous custom device that you can create using the Custom Device Template Tool or by creating a new VI from the Asynchronous Custom Device Driver Template.vit in the Custom Device API library.

Note  This topic also applies to the Asynchronous Timing and Sync device type, which is an asynchronous device that you add to the system definition file as a timing and sync device.

Related Links

Understanding the NI VeriStand Engine

Creating a Custom Device with the Custom Device Template Tool

List of PCL Execution Steps

Using the Asynchronous Custom Device Driver Template

The asynchronous custom device driver template provides a template from which you can build the RT Driver VI for an asynchronous custom device. You can use most of the Custom Device API VIs when building an asynchronous RT Driver VI. The Asynchronous Device Properties VIs and Asynchronous Device Channels VIs configure functionality exclusive to asynchronous custom devices.

An asynchronous custom device uses a two-loop architecture, one loop for receiving commands and one for transferring data, with sections of code for initialization and cleanup before and after the loops, respectively. The template VI uses a While Loop for data transfer, but you also can use a Timed Loop. In general, you use a While Loop if timing is not important or if you want the loop to run as fast as it can. You use a Timed Loop if you need the loop to execute deterministically or run pseudo-synchronously with the Primary Control Loop. The following image shows the block diagram of the Asynchronous Custom Device Template.vit.

Controls

The input controls are specially named controls that the NI VeriStand Engine will use to provide the asynchronous custom device loops with data. To function, the name of each control must match the name below.

  • Device ClockDevice Clock specifies the name of a timing source that is ticked for every iteration of the Primary Control Loop after Custom Device FIFOs have been updated. If you change the data loop of your custom device to a Timed Loop, you can use Device Clock as the timing source of the Timed Loop to closely synchronize your asynchronous custom device with the Primary Control Loop.

    Device Clock is only populated if you set the Use Device Clock input of the Set Loop Type VI to TRUE in one of the VIs for configuring the custom device.
  • Initialization Status Notifier—You can use this optional input to send the NI VeriStand Engine the final status of the custom device initialization process. If this control exists on the custom device front panel, the VeriStand Engine will wait for a status update before starting up. If the custom device reports an error, that will abort the execution of the current configuration in the VeriStand Engine.
  • Device ReferenceDevice Reference is an auto-populated reference to the custom device. Use it to read configuration properties, get a list of channels, etc.
  • Device Outputs FIFO—The array of outputs sent to the system on the Device Outputs FIFO corresponds one-to-one to the Outputs array the Get Custom Device Channel List VI returns. By default, the NI VeriStand Engine reads the Device Outputs FIFO every iteration of the PCL.
  • Device Inputs FIFO—The array of inputs received from the system on the Device Inputs FIFO corresponds one-to-one to the Inputs array the Get Custom Device Channel List VI returns. The NI VeriStand engine pushes data to the Device Inputs FIFO every iteration of the PCL. If the FIFO is full, the new data packet will overwrite the oldest data packet.
  • Status Notifier—Notifies the engine of the last state of the custom device and indicates when the device completes execution. If you do not use this control, the device returns a default No Error value when it completes execution. By default, the NI VeriStand system does not check this error until shutdown, but you can use an output channel to send more immediate status values to the system.

Initialization Code

The template includes initialization code to do the following:

  1. Register custom engine events.
  2. Get the number of input and output channels and set up data buffers for the RT FIFOs.
  3. Read a final error status for the asynchronous custom device.

If you use a Timed Loop for your data loop, you can also add code here to configure the Timed Loop.

Command Loop

The command loop allows you to send commands to and receive data from your custom device that you can not easily do using a DBL channel value. By using the Send Custom Device Message VI in a LabVIEW VI or calling a corresponding .NET method, you can use, for example, a custom workspace object or NI TestStand automation script to send a command to your custom device, which can then execute a response to that command. Take, for example, a generic custom device for logging. If you need to change configuration data, such as the file path to which to save log files, at run time, you could create a custom workspace control to send this data to the command loop of the device, and then configure the command loop to update the configuration data when the data is received.

The command loop contains the following three events:

  1. Message (Byte Array)—Receives and sends data as a byte array of 8-bit unsigned integer values.
  2. Message (String)—Receives and sends data as a string.
  3. Shut Down—The VeriStand Engine sends this command to indicate that the custom device should shut down.

For an example custom device that uses Send Custom Device Message VI in a LabVIEW VI to communicate directly with the custom device, refer to the example located at labview\examples\NI Veristand\Custom Devices\Communication Example.

Data Loop

Use this loop to read input data from the Device Inputs FIFO, update the data, and send the updated data via the Device Outputs FIFO to the rest of the NI VeriStand system. The template data loop contains code that reads the input data, adds it to a random number, and writes it back to the output channels. The data loop also executes shutdown if it receives a shut down notification from the command loop.

Cleanup Code

Use the optional Status Notifier control to publish the final error state of your device regardless of errors. If a Status Notifier control is present in the RT driver VI, the NI VeriStand system uses this as an indication that the device has shut down. Otherwise the NI VeriStand system provides default status notification for the device.

Related Links

Asynchronous Device Properties VIs

Custom Device API VIs

Asynchronous Device Channels VIs

Synchronizing an Asynchronous Custom Device with the Primary Control Loop

Timing of an Asynchronous Custom Device

The rate at which an asynchronous custom device executes depends entirely on how you configure it. By default, the asynchronous custom device RT Driver VI template uses a While Loop, meaning your asynchronous custom device will execute as fast as possible. You can, however, change the default While Loop to a Timed Loop, and then configure the Timed Loop to use a specific timing source, such as the timing source for a hardware device.

You can also closely synchronize an asynchronous custom device with the Primary Control Loop by using the Device Clock control as the timing source of your Timed Loop. Device Clock is a timing sourced ticked for every iteration of the Primary Control Loop after custom device FIFOs have been updated. If you synchronize your device with the PCL, the dt of your Timed Loop will be in ticks of the PCL. So if you set the dt as 3, your Timed Loop will execute every 3 ticks of the PCL.

Decimation of an Asynchronous Custom Device

You can use Set Custom Device Decimation VI in the initialization code of your asynchronous custom device to change the decimation rate of your device. In an asynchronous custom device, the decimation affects when the Primary Control Loop reads and writes the FIFOs it uses to communicate with the custom device. For example, if you set the Decimation parameter of Set Custom Device Decimation VI to 4, the Primary Control Loop reads and writes the FIFOs on every fourth iteration.

Related Links

Syncing an Asynchronous Device with the PCL

Latency Due to FIFOs in Asynchronous Custom Devices

Because asynchronous devices run in parallel with the PCL and pass channel data via RT FIFOs, there is a minimum of one cycle delay from when data leaves the PCL and when it enters the custom device, and vice versa. Additionally, asynchronous devices might not always execute at the same time with respect to the other components of the NI VeriStand system. For example, the first iteration might execute before the PCL processes alarms, the second and third iterations after, and so on.

WAS THIS ARTICLE HELPFUL?

Not Helpful