Reading and Writing Waveforms in the Custom Device Engine

Parent Topic: Customizing the Custom Device Driver

Waveforms, like channels, are mechanisms by which a custom device exchanges data with the rest of the NI VeriStand system. Using waveforms in custom devices allows you to publish waveform data or read waveform data from other sources in the VeriStand Engine. You can represent waveform values as double-precision floating-point numbers or complex double-precision floating-point numbers.

Writing Waveforms

After you add a waveform to a custom device and set its properties, use the VIs on the Waveform Data palette to open a write session to the waveform in the RT Driver VI of your custom device. You typically implement a work flow similar to the following process:

1. Get Waveform Data Reference VI—Generates a data reference to a specific waveform. If you want to write multiple waveforms, call this VI once per waveform and build an array of data references.
2. Open Waveform Session VI—Opens a write session for one or multiple waveforms. Specify the delta t (dt), or time interval in seconds between any two points in the signal. For example, the dt of a 10 kHz waveform is 0.0001 seconds.
3. Start Waveform(s) VI—Provides a start time (t0) that defines when the first sample is written. Readers of the waveform in the VeriStand Engine and on the host computer will receive this value. If you will read data from another waveform or from the DAQmx API, the t0 is provided. However, if you will read waveform data from an FPGA, you must calculate the t0 yourself.
4. Write Waveform(s) VI—Writes an array of waveform samples. Call this VI repeatedly as you generate data for the waveform. You can write as much or as little data at a time as you want.
   
   If you opened a write session for multiple waveforms, this VI writes to each waveform simultaneously.
5. Close Waveform Session VI—Closes the write session.

All data between calls to the Start Waveform(s) VI is considered continuous. However, if you stop writing data such that it is no longer continuous, call the Start Waveform(s) VI again before you start writing again to ensure the t0 is accurate.

Reading Waveforms

After you add a waveform and set its properties, use the VIs on the Waveform Data palette to implement a read session from the waveform in the RT Driver VI of your custom device. You typically implement a work flow similar to the following process:

1. Get Waveform Data Reference VI—Generates a data reference to a specific waveform. If you want to read multiple waveforms, call this VI once per waveform and build an array of data references.
2. Open Waveform Session VI—Opens a read streaming session for one or multiple waveforms.
3. Read Waveform(s) VI—Returns an array of values from the waveform whenever any waveform source publishes data. Call this VI repeatedly to read data as it is published.
4. Close Waveform Session VI—Closes the waveform streaming session.

Avoiding Data Loss When Reading and Writing Data

NI VeriStand uses queues to transfer data between custom devices and the Waveform Processing Loop (WPL), which transfers the waveform data through the system. By default, NI VeriStand automatically calculates the size of the queue used to hold waveform data. The calculations, described as follows, depend on whether you open a read or write session with the Open Waveform Session VI:

• Write sessions—The queue size is three elements, so the custom device can write three times without the WPL reading from the queue before data loss occurs.
• Read sessions—The queue size is three times the number of waveforms being read. For example, if you read from ten waveforms, the queue size is 30. In this example, the WPL can write 30 times without a reader consuming any data before data loss occurs.

If you notice data loss, you can specify a larger, custom queue size for the VeriStand Engine to use. When you open a read or write session with the Open Waveform Session VI, use the elements of the Communication Properties input cluster to define a custom queue size. Note that if the CPU cannot read or write as quickly as the custom device requires, changing the queue size will not resolve data loss, only delay it.

Tip  For read sessions, you can monitor the WPL Overflow Count system channel to determine if a queue overflows. For write sessions, use the timed out? output of the Write Waveform(s) VI to indicate when data loss occurs.

Identifying the Source of Values When You Read from Multiple Waveforms

If you open a read session for multiple waveforms, the Read Waveform(s) VI executes whenever any waveform returns data, and the VI returns data from only that waveform. You can identify which waveform the data came from during a particular execution using the Data reference element that the VI returns in a cluster output called Properties. Compare the Data reference to the data references you generated before you opened the waveform session.

Calculating the Start Time of a Read Operation

When you read from a waveform with the Read Waveform(s) VI, the VI returns a cluster that includes a t0 at start element. t0 at start is the start time of the first sample in the waveform, not the start time of the first sample in the current array of read values. You can calculate the start time of the first sample read during a particular read operation using the following equation:

current t0 = t0 at start + (dt * offset from start (samples))

where	t0 at start is the start time of the first sample in the waveform,
	dt is the time between samples, and
	offset from start (samples) is the number of samples by which the first sample in the array of read values is offset from the first sample in the waveform.

Note  The Read Waveform(s) VI returns dt, offset from start (samples), and t0 at start in a cluster output.

Example

On a computer with LabVIEW installed, refer to the example custom device in the labview\examples\NI Veristand\Custom Devices\Waveform Analysis and Generation\Waveform Analysis and Generation Custom Device Project.lvproj LabVIEW project for an example of a custom device that reads from a waveform, multiplies values by a channel value, and then generates its own waveform.