« Close

Datasheets and User Guides

Software & Driver

 

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 3.2.2 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.

Stream can also output data.

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

T7 only:

 

The T7 supports some advanced stream features:

  • Stream sessions can be configured to delay scanning until after the T7 detects a trigger pulse.
  • Stream clock pulses can also be read externally at either a constant or a variable rate.

On This Page

Maximum Stream Speed

T4 Max Sample Rate: 40 ksamples/second

 

The T4 max sample rate is 40 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.

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 streams it out. (See 3.2.1 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:

  For more information
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.
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 below.
   

For stream-out registers, see 3.2.1 Stream-Out.

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 and LJM converts it to a float on the host using the calibration constants that LJM reads before starting the stream.

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 override the normal AIN configuration settling and resolution registers.

Name Start Address Type Access
STREAM_SETTLING_US 4008 FLOAT32 R/W    
STREAM_RESOLUTION_INDEX 4010 UINT32 R/W    

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.)

Stream Timing

When using LJM, there are three ways that stream can be too slow:

  1. Sample rate is too high
  2. Device buffer overflow
  3. LJM buffer overflow

Sample rate is too high: When the sample rate is too high, it causes a STREAM_SCAN_OVERLAP error and stream is terminated.

Scans are triggered by hardware interrupts. If a scan begins and the previous scan has not finished, the device stops streaming and returns a STREAM_SCAN_OVERLAP error (errorcode 2942), which LJM returns immediately upon the next call to LJM_eStreamRead.

Device buffer overflow: When the device buffer overflows, LJM inserts a dummy sample (with the value -9999.0) in place of each skipped sample, or it causes a STREAM_AUTO_RECOVER_END_OVERFLOW error and stream is terminated.

As samples are collected, they are placed in a FIFO buffer on the device until retrieved by the host. The size of the buffer is variable and can be set to a maximum of 32764 bytes. Write to STREAM_BUFFER_SIZE_BYTES to set the buffer size.

Name Start Address Type Access
STREAM_BUFFER_SIZE_BYTES 4012 UINT32 R/W    

If the device buffer overflows, the device will continue streaming but will discard data until the buffer is emptied, after which data will be stored in the buffer again. The device keeps track of how many scans are discarded and reports that value. Based on the number of scans discarded, the LJM library adds the proper number of dummy samples (with the value -9999.0) such that the correct timing is maintained. This will only work if the first channel in the scan is an analog channel.

If the device buffer overflows for too much time, a STREAM_AUTO_RECOVER_END_OVERFLOW error occurs and stream is terminated.

If the device buffer is overflowing, see the LJM stream help page for some mitigation strategies.

LJM buffer overflow: When the LJM buffer overflows, it causes a LJME_LJM_BUFFER_FULL error and stream is terminated.

LJM reads samples from the device buffer and buffers them internally. LJM reads these samples in an internal thread, regardless of what your code does. LJM's buffer can run out of space if it is not read often enough using LJM_eStreamRead, so make sure the LJMScanBacklog parameter does not continually increase.

LJM_eStreamRead blocks until enough data is read from the device, so your code does not need to perform waits.

If the LJM buffer is overflowing, see the LJM stream help page for some mitigation strategies.

Channel-to-Channel Timing

Channels in a scan list are input or output as quickly as possible after the start of a scan, in the order of the scan list.

Timing pulses are generated on SPC so that the channel-to-channel timing can be measured. Pulses on SPC are as follows:

  • Falling edge at the start of a scan.
  • Rising edge at the start of a sample.
  • Falling edge at the end of a sample.
  • Rising edge at the end of a scan.

Burst Stream

Burst stream is when stream collects a pre-determined number of scans, then stops. To set the stream burst size, write to STREAM_NUM_SCANS:

Name Start Address Type Access
STREAM_NUM_SCANS 4020 UINT32 R/W    

The LJM library collects burst stream data with the StreamBurst() function.

It may be beneficial to set STREAM_BUFFER_SIZE_BYTES to a large value for fast burst stream. See above for details about STREAM_BUFFER_SIZE_BYTES.

T7-Pro only: Burst stream is well-suited for WiFi connections, because WiFi has a lower throughput than other connection types.

Externally Clocked Stream - T7 Only

 

Externally-clocked stream allows T-series devices to stream from external pulses. It also allows for variable stream scan rates.

Clock Source: The scan rate is generated from the internal crystal oscillator. Alternatively, the scan rate can be a division of an external clock provided on CIO3.

Name Start Address Type Access
STREAM_CLOCK_SOURCE 4014 UINT32 R/W    

To subdivide the external clock pulses for a slower scan rate, use STREAM_EXTERNAL_CLOCK_DIVISOR.

Name Start Address Type Access
STREAM_EXTERNAL_CLOCK_DIVISOR 4022 UINT32 R/W    

To use externally clocked stream with LJM, see the externally clocked stream section of the LJM  User's Guide.

Triggered Stream - T7 Only

 

T7 minimum firmware 1.0186

Stream can be configured to start scanning when a trigger is detected. Trigger sources are DIO_EF modes:

Frequency In and Conditional Reset allow you to select rising or falling edges and Pulse Width In will trigger from either edge.

See Appendix A for hysteresis voltage information.

Configuring stream to use a trigger requires setting up a DIO_EF and adding the STREAM_TRIGGER_INDEX register to normal stream configuration.

Name Start Address Type Access
STREAM_TRIGGER_INDEX 4024 UINT32 R/W    

STREAM_TRIGGER_INDEX (address 4024):

  • 0 = No trigger. Stream will start when Enabled.
  • 2000 = DIO_EF0 will start stream.
  • 2001 = DIO_EF1 will start stream.
  • 2002 = DIO_EF2 will start stream.
  • 2003 = DIO_EF3 will start stream.
  • 2006 = DIO_EF6 will start stream.
  • 2007 = DIO_EF7 will start stream.

To use triggered stream with LJM, see the triggered stream section of the LJM  User's Guide.