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 data into a real-time capture buffer. The data is then transferred at the maximum throughput to a SCPI buffer, from which it can be extracted via SCPI commands.
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.
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 kSamples/second. If elements are specified that update at a lower max update rate than the requested stream rate, duplicate sample values are provided. 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 elapsed since first row in this stream in seconds. |
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 |
SRSettling |
Source Readback Settling: State of the source readback for this module. True if readback is settling. |
1 |
bool (b) |
5 kSa |
SSWeeping |
Source Sweeping: Sate of the source sweeping for this module. True is 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 rate must be the maximum rate divided by an integer value. The command will select the closest available rate to the requested rate. The query TRACe:RATE? will return the actual, rounded streaming rate.
There are two constraints on the rate at which data can be streamed. The first is the capture buffer size. Data may be streamed at any rate (up to the maximum for that source) for streams that are short enough to fit within the capture buffer size of 16 kB. For streams larger than the capture buffer, the rate must be slower than the maximum throughput of 50 kB/s.
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 maximum throughput.
B64: Data is returned in a binary format that has been B64 encoded (no padding, little endian).
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 from the SCPI buffer one row at a time or multiple rows at a time. TRACe:DATA[:SINGle]? provides a single row. TRACe:DATA:ALL? provides all available rows. Once data is read by either query, it is no longer in the buffer.
If no data is available, the response of either query will be empty. Number of unread rows in the SCPI buffer can be queried with TRACe:DATA:COUNt?.
In either encoding, values appear in the order they are specified by TRACe:FORMat:ELEMents.
For the following examples, assume the following was sent for TRACe:FORMat:ELEMents:
TRACe:FORMat:ELEMents SAMPLITUDE,1,MX,2,MOVERLOAD,2
CSV Encoding
In the CSV encoding, a single row looks like this with values in a single row separated by commas:
"3.14159,2.71828,False"
TRACe:DATA:ALL? separates rows with a semicolon at the end of each row like this:
"3.14159,2.71828,False;1.41421,1.61803,True;"
B64 Encoding
In the B64 encoding, a single row consists of each value in that row. The above example would consist of the following raw bytes:
EA 2E 44 54 FB 21 09 40 03 57 14 8B 0A BF 05 40 00
The representation is little endian. No padding bytes are inserted. The format of the present configuration is available via the TRACe:FORMat:ENCOding:B64:BFORmat? query.
This would then be base 64 encoded for transfer over SCPI as:
"6i5EVPshCUADVxSLCr8FQAA="
If multiple rows are available TRACe:DATA:ALL? will concatenate the results with no separator. The length of a single row is available via the TRACe:FORMat:ENCOding:B64:BCOunt? query.
Overflow
If data is not read from the SCPI buffer quickly enough and the SCPI buffer is full, overflow will occur. TRACe:DATA:OVERflow? can be used to check if any overflow has occurred during this data stream.