6.5. Data Streaming
The M81-SSM allows for fast and synchronized data transfer via the data stream. The instrument has a configurable data logger that places selected data into a buffer that is extracted via SCPI queries.
See lakeshore.com for system speeds.
MeasureSync™ tightly synchronizes the data captured by the data logger. It can then be extracted from the data buffer without any real-time considerations as with the Fetch or Read commands.
Figure 6.4 Data stream architecture
Note
This section details how to stream data via direct SCPI commands. If you are using a driver, please refer to that driver’s documentation for a higher level data streaming interface.
Configuring the Stream
What is streamed
What is streamed can be configured using the TRACe:FORMat:ELEMents command. Up to 10 can be specified. Max update rate is specified in kilosamples per second (kSa/s). If elements are specified that update at a lower maximum update rate than the requested stream rate, duplicate values are returned between unique updates. For example, streaming MRMS (5 kSa max) and MPPeak (1 kSa max) at 5 kSa would return five unique MRMS values but only one unique MPPeak value per five rows.
Mnemonic |
Description |
Bytes |
Type |
Max update rate |
|---|---|---|---|---|
RTIMe |
Relative Time: Time, in seconds, elapsed since first row in this stream. |
8 |
double (d) |
5 kSa |
SAMPlitude |
Source Amplitude: Present value of amplitude setting for this source module. |
8 |
double (d) |
5 kSa |
SOFFset |
Source Offset: Present value of offset setting for this source module. |
8 |
double (d) |
5 kSa |
SFRequency |
Source Frequency: Present value of the frequency setting for this source module. |
8 |
double (d) |
5 kSa |
SRANge |
Source Range: Largest value that can be sourced on the present range of this source module. |
4 |
float (f) |
5 kSa |
SVLimit |
Source Voltage Limit: State of V limit for this source module. True if limit is engaged. |
1 |
bool (?) |
5 kSa |
SILimit |
Source Current Limit: State of I limit for this source module. True if limit is engaged. |
1 |
bool (?) |
5 kSa |
SRDC |
Source Readback DC: DC source readback measurement for this source module. |
8 |
double (d) |
5 kSa |
SRRMs |
Source Readback RMS: RMS source readback measurement for this source module. |
8 |
double (d) |
5 kSa |
SRSettling |
Source Readback Settling: State of the source readback for this module. True if readback is settling. |
1 |
bool (b) |
5 kSa |
SReadbackFrequencyLimit |
Source Readback Frequency Limit: Status of whether this source module’s readback frequency limit is exceeded. True if frequency exceeds limit for the present range. |
1 |
bool (?) |
5 kSa |
SSWeeping |
Source Sweeping: State of the source sweeping for this module. True if the source is presently sweeping a parameter. |
1 |
bool (?) |
5 kSa |
MDC |
Measure DC: DC measurement for this measure module. The module must be in DC or AC mode. |
8 |
double (d) |
5 kSa |
MRMS |
Measure RMS: RMS measurement for this measure module. The module must be in DC or AC mode. |
8 |
double (d) |
5 kSa |
MPPeak |
Measure Positive Peak: Positive peak measurement for this measure module. |
8 |
double (d) |
1 kSa |
MNPeak |
Measure Negative Peak: Negative peak measurement for this measure module. |
8 |
double (d) |
1 kSa |
MPTPeak |
Measure Peak to Peak: Peak to peak measurement for this measure module. |
8 |
double (d) |
1 kSa |
MX |
Measure X: X measurement from the lock-in for this measure module. The module must be in lock-in mode. |
8 |
double (d) |
5 kSa |
MY |
Measure Y: Y measurement from the lock-in for this measure module. The module must be in lock-in mode. |
8 |
double (d) |
5 kSa |
MR |
Measure R: Magnitude measurement from the lock-in for this measure module. The module must be in lock-in mode. |
8 |
double (d) |
1 kSa |
MTHeta |
Measure Theta: Angle measurement from the lock-in for this measure module. The module must be in lock-in mode. |
8 |
double (d) |
1 kSa |
MRANge |
Measure Range: Largest value that can be measured on present range of this measure module |
4 |
float (f) |
5 kSa |
MOVerload |
Measure Overload: Overload status of this measure module. True if overloaded. |
1 |
bool (?) |
5 kSa |
MSETtling |
Measure Settling: Settling status of this measure module. True if settling. |
1 |
bool (?) |
5 kSa |
MUNLock |
Measure Unlock: Lock status of the PLL for this measure module. The module must be in lock-in mode. |
1 |
bool (?) |
5 kSa |
MRFRequency |
Measure Reference Frequency: Frequency measurement from the PLL for this measure module. True if unlocked. |
8 |
double (d) |
1 Sa |
GPIStates |
General Purpose Input States: Bit-stuffed value of general purpose input states. module index ignored. |
1 |
unsigned char (B) |
5 kSa |
GPOStates |
General Purpose Output States: Bit-stuffed value of general purpose output states. module index ignored. |
1 |
unsigned char (B) |
5 kSa |
Rate
The rate is specified using the TRACe:RATE command. The instrument accepts rates that are an integer division of the maximum element update rate and will choose the closest supported value to what is requested. The query TRACe:RATE? returns the actual streaming rate in effect.
For guidance on choosing a rate that fits your interface and application behavior, see Throughput Limits and Best Practices.
Encoding
Two encoding types are available:
CSV: Data is returned as comma-separated values. This is often easier to process, but will not achieve the highest throughput.
B64: Data is returned in a binary format that has been Base64 encoded (no padding, little endian). Use this for higher throughput.
The encoding type must be selected before starting the data stream. This is done via the TRACe:FORMat:ENCOding command.
Data Transfer
For any encoding, data can be extracted one row at a time or multiple rows at a time.
TRACe:DATA[:SINGle]? returns one row.
TRACe:DATA:ALL? returns all available rows.
Once data is read by either query, it is removed from the buffer. If no data is available, the response of either query is empty. Query the number of unread rows with TRACe:DATA:COUNt?.
Values appear in the order specified by TRACe:FORMat:ELEMents.
For the following examples, assume the instrument was configured with TRACe:FORMat:ELEMents:
TRACe:FORMat:ELEMents SAMPLITUDE,1,MX,2,MOVERLOAD,2
CSV Encoding
A single row is returned as comma-separated values:
"3.14159,2.71828,False"
TRACe:DATA:ALL? separates rows with a semicolon at the end of each row, for example:
"3.14159,2.71828,False;1.41421,1.61803,True;"
B64 Encoding
For the same example, the raw bytes for a single row are:
EA 2E 44 54 FB 21 09 40 03 57 14 8B 0A BF 05 40 00
Representation is little endian. No padding bytes are inserted. The format of the present configuration is available via TRACe:FORMat:ENCOding:B64:BFORmat?.
These bytes are then base 64 encoded for transfer:
"6i5EVPshCUADVxSLCr8FQAA="
If multiple rows are available, TRACe:DATA:ALL? concatenates the results with no separator. The length of a single row (in bytes) is available via TRACe:FORMat:ENCOding:B64:BCOunt? query.
Overflow
If the application, host PC, or selected interface does not read streamed data quickly enough relative to the selected rate and encoding, the buffer that holds unread rows will eventually overflow, resulting in data loss. Use TRACe:DATA:OVERflow? to check whether overflow occurred during the current stream. If this occurs, reduce the stream rate or elements, increase the read frequency, or use a higher throughput interface.
Throughput Limits and Best Practices
Long-term throughput limits
Keep your produced streaming data rate at or below the posted long-term interface throughput limits. Doing so helps avoid large TRACe:DATA:ALL? responses and minimizes the chance of a buffer overflow or long transfers that may exceed application timeouts, particularly on lower-throughput links like USB (Serial). These are the throughput limits published in the Product Specifications and apply to sustained operation. For higher sustained stream rates, consider using Ethernet (LAN); it provides significantly more throughput than USB and is better suited for large TRACe:DATA:ALL? responses.
Interface |
Maximum sustained throughput |
|---|---|
USB |
20 kB/s |
GPIB |
40 kB/s |
Ethernet |
80 kB/s |
If you must exceed the posted limits
You may exceed the posted limits only for brief periods. Set your interface timeout sufficiently high to accommodate large responses when streaming above the sustained throughput. A conservative timeout can be as high as 120 s.
Compute and size your stream throughput
Bytes per row = sum(bytes of each selected element)
Produced data (bytes/s) = (Bytes per row) × (TRACe:RATE?)
Example:
Elements: Source Amplitude (8 B) + Measure X (8 B) + Overload (1 B) = 17 B/row
If TRACe:RATE? = 200 Sa/s, produced data ≈ 17 × 200 = 3400 B/s ≈ 3.4 kB/s
Compare the result to the posted interface limit for your connection
Tips:
For higher stream rates or larger payloads, Ethernet is preferred over USB to maintain sustained throughput and reduce transfer time.
B64 encoding is preferred at higher rates.
TRACe:DATA:ALL? is preferred on a regular cadence. Using TRACe:DATA[:SINGle]? at fast rates is likely to cause buffer overflow.
Monitor TRACe:DATA:COUNt? during streaming. If the count rises over time, the application is not reading fast enough and data will eventually overflow.
Check TRACe:DATA:OVERflow? to detect whether an overflow occurred during a stream.
Data Stream Example
The following example illustrates one way to set up a data stream and query the data.
Reset the data stream.
TRACe:RESet
Set encoding format to CSV.
TRACe:FORMat:ENCOding CSV
Set the elements to include in the data stream. In this case the stream will include the amplitude of the first source module, the X measurement of the second measure module, and the overload status of the second measure module. These three elements total 17 bytes/row where the source amplitude and X measurement are 8 bytes each and the overload status is 1 byte.
TRACe:FORMat:ELEMents SAMP,1,MX,2,MOV,2
Set the data stream rate to 200 Sa/s. This totals to 3.4 KB/s.
TRACe:RATE 200
Start the data stream and set the number of rows to be streamed to 100. This will stream a total of 340 KB of data.
TRACe:STARt 100
Query all the available rows of data in the data stream.
TRACe:DATA:ALL?
Example row from the response.
1.5E-05,Infinity,True