Skip to main content
Skip table of contents

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.

T4 / T7

T4 Max Sample Rate: 50 ksamples/second

The T4 max sample rate is 50 ksamples/second. This is achievable for any single-address stream, but for a multi-address stream this is only true when resolution index = 0 or 1.

T7 Max Sample Rate: 100 ksamples/second

The T7 max sample rate is 100 ksamples/second. This is achievable for any single-address stream, but for a multi-address stream this is only true when resolution index = 0 or 1 and when range = ±10V for all analog inputs.

The max scan rate depends on how many addresses you are sampling per scan:

  • Address => The Modbus address of one channel. (See Streamable Registers below.)

  • Sample => A reading from one address.

  • Scan => One reading from all addresses in the scan list.

  • SampleRate = NumAddresses * ScanRate

Examples:

  • For a T4 streaming 4 channels at resolution index=0, the max scan rate is 10 kscans/second (calculated from 40 ksamples/second divided by 4).

  • For a T7 streaming 5 channels at resolution index=0 and all at range=+/-10V, the max scan rate is 20 kscans/second (calculated from 100 ksamples/second divided by 5).

Ethernet provides the best throughput: Ethernet is capable of the fastest stream rates. USB is typically a little slower than Ethernet, and WiFi is much slower. For more information on speeds, see the Data Rates Appendix.

T8

The maximum per-channel T8 sample rate is 40 ksamples/second/channel. This rate is achievable for any number of active stream channels, so it corresponds to an aggregate rate of 320 ksamples/second when sampling all 8 analog inputs. This rate is only guaranteed with a resolution index setting of 1. Higher resolution index settings may result in lower maximum rates.

Unlike the T4 and T7, the T8 analog inputs are sampled simultaneously. See the simultaneous sampling section for more information about operational differences.

When streaming at 40 kHz with 8 channels of data being read, the T8 will need to transfer 960+ kilobytes per second to avoid a stream buffer overflow. As such, high stream rates are only possible when certain communication requirements are met.

High stream rates cannot be used reliably under any of the following conditions:

  • When there is a WiFi hop in the Ethernet network.

  • When the connection crosses subnets.

  • If there are any other network conditions that can cause long round trip times.

High stream rates can be used reliably under either of the following conditions:

  • When using a fully wired Ethernet connection from T8 to a switch and/or a computer.

  • When using a USB 3.0 port connected through a powered hub.

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:

AIN#

See 14.0 Analog Inputs.

FIO_STATE

See 13.0 Digital I/O.

EIO_STATE

See 13.0 Digital I/O.

CIO_STATE

See 13.0 Digital I/O.

MIO_STATE

See 13.0 Digital I/O.

FIO_EIO_STATE

See 13.0 Digital I/O.

EIO_CIO_STATE

See 13.0 Digital I/O.

CIO_MIO_STATE

See 13.0 Digital I/O.

DIO#(0:22)

See 13.0 Digital I/O.

DIO#(0:22)_EF_READ_A

See 13.2 DIO Extended Features.

DIO#(0:22)_EF_READ_A_AND_RESET

See 13.2 DIO Extended Features.

DIO#(0:22)_EF_READ_B

See 13.2 DIO Extended Features.

CORE_TIMER

See 4.0 Hardware Overview.

SYSTEM_TIMER_20HZ

See 4.0 Hardware Overview.

STREAM_DATA_CAPTURE_16

See .

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.

T4/T7 - Supported

Digital only stream is supported. When digital only stream is active, the AIN can be read normally via command-response mode communications.

T8 - Unsupported

Digital only stream is not supported. One AIN channel must always be present in the stream scan list. Stream mode takes exclusive control over the analog input system and the AIN cannot be read via command-response mode communications while stream is active.

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.