3.2 Stream Mode [T-Series Datasheet]

Stream Mode Overview

Streaming is a fast data input mode. It is more complicated than command-response mode, so it requires more configuration. Using stream is simplified by the LJM stream functions; to stream without them, see Low-Level Streaming.

For a given stream session, a list of channels/addresses are sampled as input to the device. This list of channels (known as a scan list) is input, as quickly as possible, immediately after a clock pulse. Stream clock pulses are hardware-timed at a constant scan rate. By default, a stream session begins scanning immediately after being started and continuously scans until stopped.

A LabJack device cannot run more than one stream session at any given time.

Command-response can be done while a stream is active, but streaming needs exclusive control of the analog input system, so analog inputs (including the internal temperature sensor) cannot be read via command-response while a stream is active.

Stream can also output data.

Stream sessions can be configured to collect a limited number of scans. (See Burst Stream)

The T7 and T8 support some advanced stream features:

• Stream sessions can be configured to delay scanning until after the device detects a trigger pulse.

• Stream clock pulses can also be read externally at either a constant or a variable rate. *T7 Only

Subsections

Maximum Stream Speed

The maximum stream speed and requirements to achieve the maximum speed varies by device.

Stream-In and/or Stream-Out

There are three input/output combinations of stream mode:

Stream-in: The device collects data and streams it to the host.

Stream-out: The device does not collect data but does outputs data. See Stream Out.

Stream-in-out: The device collects data and streams it to the host. It also streams data out.

The stream channels determine which of these modes are used. Streamable channels may be either stream-in or stream-out.

Streamable Registers

The Modbus Map shows which registers can be streamed (by expanding the "details" area). Input registers that can be streamed include:

Stream Data Framing

Stream data is returned channel interleaved by scan. A scan consists of a sample from every channel in the scan list. For example, if you have a scan list of [AIN0, AIN1, AIN2]data will be returned like the following:

[AIN0Sample1, AIN1Sample1, AIN2Sample1, AIN0Sample2, AIN1Sample2, AIN2Sample2, ... AIN0SampleN, AIN1SampleN, AIN2SampleN]

Data from every AIN channel will be returned in each scan when using a device that samples its analog inputs simultaneously. See the Simultaneous Sampling section for more information.

Digital Only Stream

On some T-series devices it is possible to stream digital channels without any AIN channels in the scan list. This is referred to as a digital only stream.

16-bit or 32-bit Data

Stream data is transferred as 16-bit values, but 32-bit data can be captured by using STREAM_DATA_CAPTURE_16:

16-bit

In the normal case of an analog input such as AIN0, the 16-bit binary value is actually is what is transferred. LJM converts it to a float on the host using the calibration constants that LJM reads before starting the stream. To read binary AIN stream data, enable the LJM configuration LJM_STREAM_AIN_BINARY by setting it to 1.

32-bit

Some streamable registers (e.g. DIO4_EF_READ_A) have 32-bit data. When streaming a register that produces 32-bit data, the lower 16 bits (LSW) will be returned and the upper 16 bits (MSW) will be saved in STREAM_DATA_CAPTURE_16. To get the full 32-bit value, add STREAM_DATA_CAPTURE_16 to the stream scan list after any applicable 32-bit register, then combine the two values in software (LSW + 65536*MSW). Note that STREAM_DATA_CAPTURE_16 may be placed in multiple locations in the scan list.

Configuring AIN for Stream

STREAM_SETTLING_US and STREAM_RESOLUTION_INDEX control settling and resolution during stream.

The normal AIN configuration registers for range and negative channel still apply to stream.

T7 only: Stream mode is not supported on the hi-res converter. (Resolution indices 9-12 are not supported in stream.)

Simultaneous Sampling - T8 Only

The T8 is the only T-series device that samples its analog inputs simultaneously, all other T-series devices sample sequentially.

There are two ways to sample multiple analog inputs: sequentially or simultaneously. When sampling sequentially, each AIN is sampled one after another. The time between sequential samples creates a phase delay in the data. This phase difference can result in errors when comparing two signals such as voltage and current. When sampling simultaneously, the analog inputs will be sampled at the same time and rate, thereby eliminating the phase difference and any associated errors.

Simultaneous AIN Captures when Streaming

AIN#_CAPTURE registers are not streamable, however all simultaneously sampled AIN behave
similar to AIN#_CAPTURE registers when streaming; the stream scan timing determines when new simultaneous AIN readings are captured. New AIN samples always get captured precisely at the start of the stream scan.

Operational Differences Between Simultaneous and Sequential Sampling

Simultaneously sampled stream has a few important operational differences from sequentially sampled stream.

• The first time a request for a new analog input reading (AIN0-7) is encountered, the data for all 8 analog inputs will be loaded into the data-buffer.

• If there is any AIN in the stream scan list, stream data will contain samples from all of the AIN channels. As a result, more than one AIN in the low-level stream scan list will result in an error. However, our high-level LJM library will accept any number of AIN in the aScanList parameter for eStreamStart and process them internally such that the low-level scan list is trimmed to a single AIN. Calling eStreamRead will return trimmed data in the order that AIN registers are placed in the scan list for eStreamStart.

• Because the stream scan timing always determines when the AIN readings are captured, you can only acquire one sample from each AIN in a stream scan and the AIN are always sampled simultaneously. For example, if you have an LJM scan list of [AIN0, AIN1, AIN2] LJM will return simultaneously captured readings from AIN0, AIN1, and AIN2 in each scan.

• Reading fewer analog input channels does not result in faster scan rates. Each scan collects data from all analog inputs and places the samples in the data buffer. If some analog inputs do not appear in the scan list passed to LJM, they will be discarded. There is no benefit in terms of device loading or data throughput.

The LJM Library is currently required to stream from devices that perform simultaneous sampling.