2.4.2 - eStreamRead | LabJack
« Close

Datasheets and User Guides

App Notes

Software & Driver


2.4.2 - eStreamRead

Returns ScansPerRead * NumAddresses samples from an initialized and running LJM stream buffer. By default, eStreamRead waits for data to become available, if necessary.


                int Handle, 
                double * aData, 
                int * DeviceScanBacklog, 
                int * LJMScanBacklog)


Handle [in]
A device handle. The handle is a connection ID for an active device. Generate a handle with LJM_Open or LJM_OpenS.
aData [out]
An array that contains the samples being read. Returns all channels interleaved (see note below). Must be large enough to hold ScansPerRead * NumAddresses values, where ScansPerRead and NumAddresses are values passed to LJM_eStreamStart. The data returned is removed from the LJM stream buffer according to first in, first out (FIFO) order.
DeviceScanBacklog [out]
The number of scans left in the device buffer, as measured from when data was last collected from the device. DeviceScanBacklog should usually be near zero and not growing.
LJMScanBacklog [out]
The number of scans left in the LJM buffer, which does not include concurrent data sent in the aData array. LJMScanBacklog should usually be near zero and not growing.


LJM errorcodes or 0 for no error.

By default, eStreamRead should be considered a blocking call. To make eStreamRead always return immediately, configure LJM_STREAM_SCANS_RETURN to LJM_STREAM_SCANS_RETURN_ALL_OR_NONE.

If LJM_eStreamRead returns an error, LJM nearly always attempts to command the device to stop streaming. LJM does not do so for the case when LJME_NO_SCANS_RETURNED is returned (due to LJM_STREAM_SCANS_RETURN_ALL_OR_NONE).


Before calling this function, create a data buffer using LJM_eStreamStart. To stop stream, use LJM_eStreamStop.

If LJM_eStreamRead gives error 1301 (LJME_LJM_BUFFER_FULL) or many -9999 values in aData, here are some strategies to help.

LJM 1.2100 and later: If this function returns the error LJME_SYNCHRONIZATION_TIMEOUT, try setting a large send/receive timeout for the appropriate connection type.

Interleaved Channels

aData returns interleaved data. For example, when streaming two channels, AIN0 and AIN1, aData will look like this:

aData[0] contains the first AIN0 sample
aData[1] contains the first AIN1 sample
aData[2] contains the second AIN0 sample
aData[3] contains the second AIN1 sample


See the LJM_eStreamStart page for an example using LJM_eStreamRead.


Is it generally advised to periodically run this method to read the stream at a specified rate (dependent on your scan rate and buffer size), or is it better to use the LJM_SetStreamCallback and read the stream only from within the callback (BTW - I can't find the SetStreamCallback function in the documentation for the LJM lib)? Also I wish to understand the DeviceScanBacklog  parameter. Does this become non-zero when the output data size exceeds ScansPerRead * NumAddresses as dictated by  LJM_eStreamStart before the data gets a chance to unload?



Hi Ian,

LJM_eStreamRead is usually a sufficient way to read stream data. Using the default configurations, LJM_eStreamRead will block until a full read of data has been collected. In other words, if you don't need to worry about updating a GUI or anything, LJM_eStreamRead is probably the easiest way to read stream data.

The DeviceScanBacklog parameter is basically the device-reported number of scans on the device's buffer. For a contrived example, if the device has collected 2 scans, then sends 1 scan, 1 scan will be left in the device buffer, and DeviceScanBacklog will be 1. (DeviceScanBacklog will always be reported in the same way -- it will not be affected by ScansPerRead or NumAddresses.)

In a healthy stream, LJM should have ample processor time to read scans from the device, so DeviceScanBacklog should remain small. However, if LJM starts falling behind, this value will begin to increase. If this value increases enough, stream on the device will "pause" and enter auto-recovery mode. More information on the T7's stream characteristics, including auto-recovery mode, can be found on the stream-mode page of the T7 datasheet.

More information on LJM_SetStreamCallback to come.