3.2.1 Stream Timing [T-Series Datasheet]
Subsections
Channel-to-Channel (Interchannel) 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.
For descriptions of typical interchannel delays, see Appendix A-1 Data Rates.
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.
Device Clock Scan Time
To calculate the time a scan was collected relative to the device clock, multiply the scan's offset from the first scan with the interval length. The interval length is the inverse of the scan rate:
TimeSinceFirstScan = Offset * (1 / ScanRate)
For example, with a 500 Hz scan rate, the 1000th scan collected is 2 seconds after the first scan, according to the device clock.
You can use STREAM_START_TIME_STAMP to relate the start of stream with other events:
Correlating Scan Times to Host Time
To get a timestamp relative to the host computer time, you can get your system time right after you call eStreamStart, then for each scan, add the time between each scan which you can calculate from the actual scan rate that is returned by eStreamStart like so 1 / ActualScanRate.
The LabJack’s scan frequency is extremely accurate relative to its clock time, but this clock does drift relative to your host’s clock.
The T7 clock has an average accuracy of 20ppm, which results in a 72ms drift over an hour:(3600 sec / 1000000) * 20ppm = 0.072 sec
Meaning that you should re sample your host time relative to the stream frequency at an appropriate time interval to address this drift.
You can get more accurate information about clock accuracy per device in this datasheet.
Stream Timing Complications
Most stream complications are due to the device acquisition outpacing the rate that data is consumed with your host device/computer/LJM. When using LJM, there are three common causes for this sort of issue:
Sample rate is too high
Device buffer overflow
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.
Stream Data Buffer
As samples are collected, they are placed in a FIFO ring buffer on the device until retrieved by the host. The size of the buffer is variable and can be set to a maximum of 32768 bytes for T4 and T7, and 262144 bytes for T8. The buffer size can be set by writing the desired number of Bytes to STREAM_BUFFER_SIZE_BYTES. The stream buffer will be allocated within shared memory. Values are stored in 16-bit words. A buffer of 8192 Bytes will be able to store 4096 results.
Once samples have been transferred to a host computer, they are stored in a second buffer until an application retrieves them.
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.
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 cannot return 0xFFFF.
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.