« Close

Datasheets and User Guides

App Notes

Software & Driver

 

3.2 Stream Mode

Stream Mode Overview

The highest input data rates are obtained in stream mode. Stream is a continuous hardware timed input mode where a list of channels/addresses is scanned at a specified scan rate.  The scan rate specifies the interval between the beginning of each scan.  The samples within each scan are acquired as fast as possible.

The max sample rate of the T7 is 100 ksamples/second.  This is achievable for any single-address stream, but for a multi-address stream is only true if ResolutionIndex = 0 or 1 and Range = +/-10V for all analog inputs.  The max scan rate depends on how many addresses you are sampling per scan:

Address => You can usually also call this a "channel".  An address usually returns the value of 1 channel.
Sample => A reading from one address.
Scan => One reading from all addresses in the scan list.
SampleRate = NumAddresses * ScanRate

For example, if streaming 5 channels at ResolutionIndex=0 and all at Range=+/-10V, the max scan rate is 20 kscans/second (calculated from 100 ksamples/second divided by 5).

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 mode is not supported on the hi-res converter (resolutions 9-12 not supported in stream).

As samples are collected, they are placed in a FIFO buffer on the T7, until retrieved by the host.  The size of the buffer is variable and can be set to a maximum of 32764 bytes. Each data packet has various measures to ensure the integrity and completeness of the data received by the host.

Data can be sent to the host in two different ways. The first is “Spontaneous.” In spontaneous mode packets are automatically sent to the host as soon as there is enough data to fill a packet. The packet size is adjustable, see the register definitions below. The second is “Command-Response” (CR). In CR mode the stream data is stored in the T7’s buffer and must be read out using a command. CR mode is useful for when the connection is unreliable.

The T7 uses a feature called auto-recovery. If the buffer overflows, the T7 will continue streaming but discard data until the buffer is emptied, and then data will be stored in the buffer again.  The T7 keeps track of how many scans are discarded and reports that value.  Based on the number of scans discarded, the LJM driver adds the proper number of dummy samples (-9999.0) such that the correct timing is maintained. Auto-recover will only work if the first channel in the scan is an analog channel.

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.

The timing between items in the scan list is controlled by several factors. Timing pulses are generated on SPC so that the 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.

Registers that can be streamed are marked "streamable":true in ljm_constants.json and include:

  • AIN#
  • FIO_STATE
  • EIO_STATE
  • CIO_STATE
  • MIO_STATE
  • FIO_EIO_STATE
  • EIO_CIO_STATE
  • DIO#(0:22)_EF_READ_A
  • DIO#(0:22)_EF_READ_A_AND_RESET
  • DIO#(0:22)_EF_READ_B
  • CORE_TIMER
  • SYSTEM_TIMER_20HZ
  • STREAM_DATA_CAPTURE_16

Stream data is transferred as 16-bit values only.  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 in before starting the stream.  Some registers in the list above (e.g. DIO4_EF_READ_A) have 32-bits 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 register, then combine the two values in software (LSW + 65536*MSW).  Note that it would not be unusual to put STREAM_DATA_CAPTURE_16 in multiple locations in the scan list.

The following describes the Modbus registers related to stream mode.  Note that the LJM library provides special functions for stream, so most users will not use the following registers.

Register Listing

Stream Configuration
Name Start Address Type Access
STREAM_SCANRATE_HZ 4002 FLOAT32 R/W
STREAM_NUM_ADDRESSES 4004 UINT32 R/W
STREAM_SAMPLES_PER_PACKET 4006 UINT32 R/W
STREAM_SETTLING_US 4008 FLOAT32 R/W
STREAM_RESOLUTION_INDEX 4010 UINT32 R/W
STREAM_BUFFER_SIZE_BYTES 4012 UINT32 R/W
STREAM_CLOCK_SOURCE 4014 UINT32 R/W
STREAM_AUTO_TARGET 4016 UINT32 R/W
STREAM_NUM_SCANS 4020 UINT32 R/W
STREAM_EXTERNAL_CLOCK_DIVISOR 4022 UINT32 R/W
STREAM_ENABLE 4990 UINT32 R/W
STREAM_SCANLIST_ADDRESS#(0:127) 4100 UINT32 R/W
STREAM_TRIGGER_INDEX 4024 UINT32 R/W
STREAM_SCANRATE_HZ
- Address: 4002
Write a value to specify the number of times per second that all channels in the stream scanlist will be read. Max stream speeds are based on Sample Rate which is NumChannels*ScanRate. Has no effect when using and external clock. A read of this register returns the actual scan rate, which can be slightly different due to rounding. For scan rates >152.588, the actual scan interval is multiples of 100 ns. Assuming a core clock of 80 MHz the internal roll value is (80M/(8*DesiredScanRate))-1 and the actual scan rate is then 80M/(8*(RollValue+1). For slower scan rates the scan interval resolution is changed to 1 us, 10 us, 100 us, or 1 ms as needed to achieve the longer intervals.
  • Data type: FLOAT32  (type index = 3)
  • Readable and writable
  • Default value: 0
STREAM_NUM_ADDRESSES
- Address: 4004
The number of entries in the scanlist
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
STREAM_SAMPLES_PER_PACKET
- Address: 4006
Specifies the number of data points to be sent in the data packet. Only applies to spontaneous mode.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
STREAM_SETTLING_US
- Address: 4008
Time in microseconds to allow signals to settle after switching the mux. Default=0. When set to less than 1, automatic settling will be used. The automatic settling behavior varies by device.
  • Data type: FLOAT32  (type index = 3)
  • Readable and writable
  • Default value: 0
  • T7-specific details: The T7 will select the settling time based on resolution and gain settings. When the sample rate is above 60 kHz, settling time will be set to ~5 us. Max is 4400.
  • T4-specific details: The T4 will default to 10 us. When the scan rate is above 20 kHz, settling time will be set to 5 us.
STREAM_RESOLUTION_INDEX
- Address: 4010
The resolution index for stream readings. A larger resolution index generally results in lower noise and longer sample times.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
  • T7-specific details: Valid values: 0-8. Default value of 0 corresponds to an index of 1.
  • T4-specific details: Valid values: 0-5. Default value of 0 corresponds to an index of 1.
STREAM_BUFFER_SIZE_BYTES
- Address: 4012
Size of the stream data buffer in bytes. A value of 0 equates to the default value. Must be a power of 2, as it takes 2 bytes to hold 1 sample. Size in samples is STREAM_BUFFER_SIZE_BYTES/2. Size in scans is (STREAM_BUFFER_SIZE_BYTES/2)/STREAM_NUM_ADDRESSES. Changes while stream is running do not affect the currently running stream.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
  • T4-specific details: Max size is 32768. Default size is 8192.
  • T7-specific details: Max size is 32768. Default size is 4096.
STREAM_CLOCK_SOURCE
- Address: 4014
Controls which clock source will be used to run the main stream clock. 0 = Internal crystal, 2 = External clock source on CIO3. Rising edges will increment a counter and trigger a stream scan after the number of edges specified in STREAM_EXTERNAL_CLOCK_DIVISOR. T7 will expect external stream clock on CIO3. All other values reserved.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
STREAM_AUTO_TARGET
- Address: 4016
Controls where data will be sent. Value is a bitmask. bit 0: 1 = Send to Ethernet 702 sockets, bit 1: 1 = Send to USB, bit 4: 1 = Command-Response mode. All other bits are reserved.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
STREAM_NUM_SCANS
- Address: 4020
The number of scans to run before automatically stopping (stream-burst). 0 = run continuously. Limit for STREAM_NUM_SCANS is 2^32-1, but if the host is not reading data as fast as it is acquired you also need to consider STREAM_BUFFER_SIZE_BYTES.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
STREAM_EXTERNAL_CLOCK_DIVISOR
- Address: 4022
The number of pulses per stream scan when using an external clock.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
STREAM_ENABLE
- Address: 4990
Write 1 to start stream. Write 0 to stop stream.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
STREAM_SCANLIST_ADDRESS#(0:127)
- Starting Address: 4100
A list of addresses to read each scan. In the case of Stream-Out enabled, the list may also include something to write each scan.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
Expanded Names Addresses
STREAM_SCANLIST_ADDRESS0, STREAM_SCANLIST_ADDRESS1, STREAM_SCANLIST_ADDRESS2, STREAM_SCANLIST_ADDRESS3, STREAM_SCANLIST_ADDRESS4, STREAM_SCANLIST_ADDRESS5, STREAM_SCANLIST_ADDRESS6, STREAM_SCANLIST_ADDRESS7, STREAM_SCANLIST_ADDRESS8, STREAM_SCANLIST_ADDRESS9, STREAM_SCANLIST_ADDRESS10, STREAM_SCANLIST_ADDRESS11, STREAM_SCANLIST_ADDRESS12, STREAM_SCANLIST_ADDRESS13, STREAM_SCANLIST_ADDRESS14, STREAM_SCANLIST_ADDRESS15, STREAM_SCANLIST_ADDRESS16, STREAM_SCANLIST_ADDRESS17, STREAM_SCANLIST_ADDRESS18, STREAM_SCANLIST_ADDRESS19, STREAM_SCANLIST_ADDRESS20, STREAM_SCANLIST_ADDRESS21, STREAM_SCANLIST_ADDRESS22, STREAM_SCANLIST_ADDRESS23, STREAM_SCANLIST_ADDRESS24, STREAM_SCANLIST_ADDRESS25, STREAM_SCANLIST_ADDRESS26, STREAM_SCANLIST_ADDRESS27, STREAM_SCANLIST_ADDRESS28, STREAM_SCANLIST_ADDRESS29, STREAM_SCANLIST_ADDRESS30, STREAM_SCANLIST_ADDRESS31, STREAM_SCANLIST_ADDRESS32, STREAM_SCANLIST_ADDRESS33, STREAM_SCANLIST_ADDRESS34, STREAM_SCANLIST_ADDRESS35, STREAM_SCANLIST_ADDRESS36, STREAM_SCANLIST_ADDRESS37, STREAM_SCANLIST_ADDRESS38, STREAM_SCANLIST_ADDRESS39, STREAM_SCANLIST_ADDRESS40, STREAM_SCANLIST_ADDRESS41, STREAM_SCANLIST_ADDRESS42, STREAM_SCANLIST_ADDRESS43, STREAM_SCANLIST_ADDRESS44, STREAM_SCANLIST_ADDRESS45, STREAM_SCANLIST_ADDRESS46, STREAM_SCANLIST_ADDRESS47, STREAM_SCANLIST_ADDRESS48, STREAM_SCANLIST_ADDRESS49, STREAM_SCANLIST_ADDRESS50, STREAM_SCANLIST_ADDRESS51, STREAM_SCANLIST_ADDRESS52, STREAM_SCANLIST_ADDRESS53, STREAM_SCANLIST_ADDRESS54, STREAM_SCANLIST_ADDRESS55, STREAM_SCANLIST_ADDRESS56, STREAM_SCANLIST_ADDRESS57, STREAM_SCANLIST_ADDRESS58, STREAM_SCANLIST_ADDRESS59, STREAM_SCANLIST_ADDRESS60, STREAM_SCANLIST_ADDRESS61, STREAM_SCANLIST_ADDRESS62, STREAM_SCANLIST_ADDRESS63, STREAM_SCANLIST_ADDRESS64, STREAM_SCANLIST_ADDRESS65, STREAM_SCANLIST_ADDRESS66, STREAM_SCANLIST_ADDRESS67, STREAM_SCANLIST_ADDRESS68, STREAM_SCANLIST_ADDRESS69, STREAM_SCANLIST_ADDRESS70, STREAM_SCANLIST_ADDRESS71, STREAM_SCANLIST_ADDRESS72, STREAM_SCANLIST_ADDRESS73, STREAM_SCANLIST_ADDRESS74, STREAM_SCANLIST_ADDRESS75, STREAM_SCANLIST_ADDRESS76, STREAM_SCANLIST_ADDRESS77, STREAM_SCANLIST_ADDRESS78, STREAM_SCANLIST_ADDRESS79, STREAM_SCANLIST_ADDRESS80, STREAM_SCANLIST_ADDRESS81, STREAM_SCANLIST_ADDRESS82, STREAM_SCANLIST_ADDRESS83, STREAM_SCANLIST_ADDRESS84, STREAM_SCANLIST_ADDRESS85, STREAM_SCANLIST_ADDRESS86, STREAM_SCANLIST_ADDRESS87, STREAM_SCANLIST_ADDRESS88, STREAM_SCANLIST_ADDRESS89, STREAM_SCANLIST_ADDRESS90, STREAM_SCANLIST_ADDRESS91, STREAM_SCANLIST_ADDRESS92, STREAM_SCANLIST_ADDRESS93, STREAM_SCANLIST_ADDRESS94, STREAM_SCANLIST_ADDRESS95, STREAM_SCANLIST_ADDRESS96, STREAM_SCANLIST_ADDRESS97, STREAM_SCANLIST_ADDRESS98, STREAM_SCANLIST_ADDRESS99, STREAM_SCANLIST_ADDRESS100, STREAM_SCANLIST_ADDRESS101, STREAM_SCANLIST_ADDRESS102, STREAM_SCANLIST_ADDRESS103, STREAM_SCANLIST_ADDRESS104, STREAM_SCANLIST_ADDRESS105, STREAM_SCANLIST_ADDRESS106, STREAM_SCANLIST_ADDRESS107, STREAM_SCANLIST_ADDRESS108, STREAM_SCANLIST_ADDRESS109, STREAM_SCANLIST_ADDRESS110, STREAM_SCANLIST_ADDRESS111, STREAM_SCANLIST_ADDRESS112, STREAM_SCANLIST_ADDRESS113, STREAM_SCANLIST_ADDRESS114, STREAM_SCANLIST_ADDRESS115, STREAM_SCANLIST_ADDRESS116, STREAM_SCANLIST_ADDRESS117, STREAM_SCANLIST_ADDRESS118, STREAM_SCANLIST_ADDRESS119, STREAM_SCANLIST_ADDRESS120, STREAM_SCANLIST_ADDRESS121, STREAM_SCANLIST_ADDRESS122, STREAM_SCANLIST_ADDRESS123, STREAM_SCANLIST_ADDRESS124, STREAM_SCANLIST_ADDRESS125, STREAM_SCANLIST_ADDRESS126, STREAM_SCANLIST_ADDRESS127 Show All 4100, 4102, 4104, 4106, 4108, 4110, 4112, 4114, 4116, 4118, 4120, 4122, 4124, 4126, 4128, 4130, 4132, 4134, 4136, 4138, 4140, 4142, 4144, 4146, 4148, 4150, 4152, 4154, 4156, 4158, 4160, 4162, 4164, 4166, 4168, 4170, 4172, 4174, 4176, 4178, 4180, 4182, 4184, 4186, 4188, 4190, 4192, 4194, 4196, 4198, 4200, 4202, 4204, 4206, 4208, 4210, 4212, 4214, 4216, 4218, 4220, 4222, 4224, 4226, 4228, 4230, 4232, 4234, 4236, 4238, 4240, 4242, 4244, 4246, 4248, 4250, 4252, 4254, 4256, 4258, 4260, 4262, 4264, 4266, 4268, 4270, 4272, 4274, 4276, 4278, 4280, 4282, 4284, 4286, 4288, 4290, 4292, 4294, 4296, 4298, 4300, 4302, 4304, 4306, 4308, 4310, 4312, 4314, 4316, 4318, 4320, 4322, 4324, 4326, 4328, 4330, 4332, 4334, 4336, 4338, 4340, 4342, 4344, 4346, 4348, 4350, 4352, 4354 Show All
STREAM_TRIGGER_INDEX
- Address: 4024
Controls when stream scanning will start. 0 = Start when stream is enabled, 2000 = Start when DIO_EF0 detects an edge, 2001 = Start when DIO_EF1 detects an edge. See the stream documentation for all supported values.
  • Data type: UINT32  (type index = 1)
  • Readable and writable
  • Default value: 0
  • Minimum firmware version: 1.0186

(New beta feature) Triggered Stream:

Requires firmware 1.0186

Stream can be configured to start scanning when a trigger is detected. Trigger sources are DIO_EF modes Frequency In, Pulse Width In, and Conditional Reset.  Frequency In and Conditional Reset allow you to select rising or falling edges and Pulse Width In will trigger from either edge. 

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

STREAM_TRIGGER_INDEX (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.

 

17 comments

What effect would repeated calls to discreet read/write functions have while streaming? IE - if my program happened to call LJM_eReadAddress 100,000 times within 1 second would my stream experience some interference for that second and perhaps slow down? I ask because I plan to have 1 T7 device that I stream data out on at the maximum allowable rate, but I also want to read/write to/from certain registers on that device from time to time (which I don't want to put into the stream).

Stream acquisition is high priority in firmware, and it will either collect every scan at exactly the specified scan rate, or return an error or auto-recovery data.  It might slow down the transfer of data from the T7 to the host, but will not slow down the acquisition of the data on the T7.  It will not skip scans, except for auto-recovery described above.

I suggest you watch the scan backlog returned by eStreamRead to make sure it is not growing.

Because stream is high priority, the most likely behavior in your situation is that the command-response calls (eReadAddress) will take longer than usual, but stream will operate normally.

I watched the backlogs between OS X (which works) and Linux (which doesn't) and they behave more or less identically.

They climb to ~300, but then always come back down again.

Sampling an AIN at scan rate 44100 doesn't work on 64-bit Linux. The stream starts ok (when connected via Ethernet), but stream reads only work very, very rarely. Most of the time they return a LJME_INCORRECT_NUM_RESPONSE_BYTES_RECEIVED error.

What does this error mean? How can I resolve it?

The LJME_INCORRECT_NUM_RESPONSE_BYTES_RECEIVED error is "An incorrect/unexpected number of Modbus response bytes were received from the device." and is most likely related to the stream response bytes from the T7.

Download and install the latest Linux driver (currently v1.0707) from here and see if it helps the issue:

http://labjack.com/support/ljm

The main 32-bit/64-bit Linux installs are built from CentOS but are meant for all Linux distributions.

I still see the same behaviour with the latest driver and also get the occasional segfault when trying to open the device.

What version/distribution of Linux are you running?

Ubuntu Server 14.04.

Please try running LJM stream examples, specifically stream_example, which is available for multiple languages here:

http://labjack.com/support/ljm/examples

If you cannot get stream_example to work, please email LabJack support at [email protected]. Please send information including:

  • output of stream_example (and/or any core dumps)
  • which programming language you're using
Thanks

 

martin beck mechatronic's picture

Hi,

is it possible to start streaming based on a trigger-event? Most simply, such an event should be an edge on a digital input, but, even better, an event could be a counter overflow or even an analog input exceeding a certain threshold.

With triggering I do not mean executing a single sample, I mean starting the execution of a scan-list with a predefined scan- and sample-rate. Of course such a behaviour would require a configurable time-out in case that the trigger-event never occurs.

Reason for asking is that I am acquiring periodic signals and I have a sensor for zero-crossing, that I could utilize to trigger sampling. Without triggering the sampling, the phase-relationship is lost. Moreover, treating the acquired signals in an FFT requires windowing when the acquisition s not triggered.

Any comment is appreciated!

Greetings from Germany,

Martin

LabJack Support's picture

Yes, actually. We are actively working on this, so contact [email protected] for further help and details, but we are working on a couple options for a triggered stream start: 1. From your host application you tell it you are doing a triggered stream start and what DI to watch for what state. 2. From your host application you tell it you are doing a triggered stream start, and then use a Lua script to whatever logic you want and tell the stream to start when you want.
martin beck mechatronic's picture

Cool, Thanks for this info!
I will contact you shortly on this.

Best,

Martin

Miles's picture

Hello.  I am using eStreamRead on FIO_EIO_STATE to monitor pulses coming from electronic eyes at 3k.  I use eReadNames to monitor two speed encoders through DIO_EF Frequency In.  I am also using eWriteNames to control DIO_EF PWM Out to control a hydraulic valve.  Randomly, (median about 25 seconds) I will get a Stream_Scan_Overflow.

I updated to the latest beta firmware (1.0186) and moved my Frequency Ins to One Shot, Read Reset (as I saw an article with similar problems) and continued getting the error.

I was using eReadNames for convenience so I put these back into the stream.  Now the error occurs much more frequently (median about 4 seconds), so it seems to be caused by my PWM Out.  I am guessing that it occurs more frequently as the odds of it colliding go up with significantly longer stream.

Is there something that I can do to fix this? 

If it isn't a bug or something that I'm overlooking, is there some flag that I can set to ask it to skip stream overlaps rather than bomb out?

Thank you for your always excellent support.

LabJack Support's picture

Hello,

There's a few distinct errors that sound like what you are receiving. Which of the following errors are you receiving?

  • STREAM_USB_PKT_OVERFLOW
  • STREAM_AUTO_RECOVER_END_OVERFLOW
  • STREAM_SCAN_OVERLAP

If it's STREAM_SCAN_OVERLAP, a new scan started before the previous scan finished. Generally occurs because ScanRate > MaxSampleRate/NumChannels.  Note that MaxSampleRate is impacted by Range, ResolutionIndex, and Settling. Try adding commands right before StreamStart to set AIN_ALL_RANGE=10, STREAM_RESOLUTION_INDEX=0, and STREAM_SETTLING_US=0.

Let us know if you need more help.

Miles's picture

Yes it is actually STREAM_SCAN_OVERLAP.

It is uneffected by my sampling rate.  Further it seems alot like the problems occuring in this article: http://forums.labjack.com/index.php?showtopic=7156

LabJack Support's picture

So far I've been unable to reproduce your issue with the latest beta firmware. The scan overlaps issue in the forum happened when streaming pulse width inputs. Your issue seems to be occuring while streaming digital inputs, and using PWM and frequency inputs with command/response.

Please send an email to [email protected] with your code or code snippets that show how you are configuring your DIO#_EFs (PWM and frequency in), stream mode and other code that performs the stream reads, sets your PWMs and reads your frequency inputs. With this we will try to reproduce the issue further.

Miles's picture

I should add that you will need to be updating your DIO_EF PWM Out to see the problem.  It lasted as long as it did in my code because my debug stand was only asking or a steady PWM.