3.2.1 Stream Timing [T-Series Datasheet]
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 create timestamps relative to the host computer time, start by recording your system time immediately after calling eStreamStart
. This initial host time serves as a reference point. For each scan, you can calculate the elapsed time using:
ElapsedTime = ScanNumber / ActualScanRate
ScanNumber
represents the number of scans since the stream began, and ActualScanRate
is the scan rate value returned by eStreamStart
. To determine the absolute time for any given scan, simply add the elapsed time to the initial host time:
AbsoluteTime = InitialHostTime + ElapsedTime
It’s important to account for clock drift when correlating device time with host computer time. The T7 clock is highly accurate, with an average accuracy of 20 ppm at room temperature. This means the T7 clock could drift by approximately 72 milliseconds per hour:
(3600 sec / 1000000) * 20ppm = 0.072 sec
Host clocks could have an accuracy of around 100 ppm. When combined, the potential drift between the T7 clock and the host clock could reach up to 120 ppm, or about 10.4 seconds per day.
For applications that require precise long-term alignment between stream data and actual absolute time, it’s best to periodically re sample the initial host time. This adjustment helps compensate for any drift between the device’s clock and the host’s clock.
Additionally, keep in mind that host time may experience abrupt changes due to synchronization protocols like Network Time Protocol (NTP), which can occur once a week, resulting in the host time potentially jumping by as much as 60.5 seconds.
Additional details about device clock’s can be found at 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.