3.2.4 Low-Level Stream [T-Series Datasheet]
Stream mode is complicated but can easily be executed using the high-level LJM stream functions. LJM is recommend for all users, except users that need to integrate a T-series device into a system that cannot use LJM. The rest of this section is about manually executing stream protocol without LJM.
Executing stream mode involves the following:
Stream setup
Stream start
Stream-in data collection, if any stream includes stream-in channels
Stream-out buffer updates, if stream includes stream-out channels (See the Stream-Out section)
Stream stop
Spontaneous Stream vs. Command-Response Stream:
Data can be sent to the host in one of two data collection modes:
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.
Command-Response (CR): In CR mode, the stream data is stored in the device’s buffer and must be read out using a command. CR mode is useful for when the connection is unreliable.
T-series devices connected via either USB and Ethernet are capable of both spontaneous stream and command-response stream.
T7-Pro only: T7-Pro devices connected via WiFi are capable of only command-response stream.
Setup
Manual stream setup requires configuration of the registers that LJM_eStreamStart automatically configures:
Additional Configuration Notes
Additionally, address 4018 (STREAM_DATATYPE) must be written with the value 0. Note that address 4018 (STREAM_DATATYPE) is not in ljm_constants.json and is not compatible with LJM_NameToAddress.
STREAM_ENABLE must be written last.
Stream Burst
Writing a non-zero value to the register STREAM_NUM_SCANS will cause the device to automatically stop sending stream data after a certain number of scans. We commonly refer to this noncontinuous stream-mode acquisition as a stream burst.
After STREAM_NUM_SCANS scans have been acquired, the device will no longer scan new data and the status/error STREAM_BURST_COMPLETE will be returned from the LabJack. Upon receiving STREAM_BURST_COMPLETE, stream should be fully disabled by writing 0 to STREAM_ENABLE.
In most cases, STREAM_NUM_SCANS should not be configured when using LJM. LJM will set STREAM_NUM_SCANS when using StreamBurst.
Data Collection
Spontaneous Stream: Once stream has been initiated with STREAM_ENABLE, the device sends data to the target indicated by STREAM_AUTO_TARGET until STREAM_ENABLE is written with the value 0. Stream-out streams that do not contain stream-in channels do not send data.
Modbus Feedback Spontaneous Packet Protocol:
Bytes 0-1: Transaction ID
Bytes 2-3: Protocol ID
Bytes 4-5: Length, MSB-LSB
Bytes 6: 1 (Unit ID)
Byte 7: 76 (Function #)
Byte 8: 16
Byte 9: Reserved
Bytes 10-11: Backlog Bytes
Bytes 12-13: Status Code
Byte 14-15: Additional status information
Byte 16+: Stream Data (raw sample = 2 bytes MSB-LSB)
Command-Response Stream: When collecting data using command-response stream mode, data must be read from STREAM_DATA_CR (address 4500). Data is automatically discarded as it is read.
Modbus Feedback Command-Response Packet Protocol:
Bytes 0-1: Transaction ID
Bytes 2-3: Protocol ID
Bytes 4-5: Length, MSB-LSB
Bytes 6: 1 (Unit ID)
Byte 7: 76 (Function #)
Bytes 8-9: Number of samples in this read
Bytes 10-11: Backlog Bytes
Bytes 12-13: Status Code
Byte 14-15: Additional status information
Byte 16+: Stream Data (raw sample = 2 bytes MSB-LSB)
Backlog Bytes:
Backlog Bytes is the number bytes contained in the device stream buffer after reading. To convert BacklogBytes to the number of scans still on the device:
BacklogScans = BacklogBytes / (bytesPerSample * samplesPerScan)
Where bytesPerSample is 2 and samplesPerScan is the number of channels.
Status Codes:
2940: Auto-recovery Active.
2941: Auto-recovery End. Additional Status Information is the number of scans skipped. A scan consisting of all 0xFFFF values indicates the separation between old data and new data.
2942: Scan Overlap
2943: Auto-recovery End Overflow
2944: Stream Burst Complete
Stop
To stop stream, write 0 to STREAM_ENABLE. All stream modes expect to be stopped, except for burst stream (see STREAM_NUM_SCANS for more information on bust stream).
Code Example
A general low-level stream example written in C/C++ can be found here.