Scope Module
The Scope Module corresponds to the functionality available in the Scope tab in the LabOne User Interface and provides API users with an interface to acquire assembled and scaled scope data from the instrument programmatically.
example_scope.py
, an example distributed on our public GitHub repository. The example runs the Scope Module in both time and frequency mode with scope record averaging enabled.Introduction to Scope Data Transfer
In general, an instrument’s scope can generate a large amount of data which requires special treatment by the instrument’s firmware, the Data Server, LabOne API and API client in order to process it correctly and efficiently. The Scope Module was introduced in LabOne 16.12 to simplify scope data acquisition for the user. This section provides a top-level overview of how scope data can be acquired and define the terminology used in subsequent sections before looking at the special and more simplified case when the Scope Module is used.
There are three methods of obtaining scope data from the device:
-
By subscribing directly to the instrument node /DEV…./SCOPES/n/WAVE and using the
poll()
command. This refers to the lower-level interface provided by theziDAQServer
classsubscribe()
andpoll()
commands. -
By subscribing to the instrument node /DEV…./SCOPES/n/WAVE in the Scope Module and using using the Scope Module’s
read()
command. -
By subscribing to the instrument’s scope streaming node /DEV…./SCOPES/n/STREAM/SAMPLE which continuously streams scope data as a block stream. This is only available on MF and UHF instruments with the DIG Option enabled. The Scope Module does not support acquisition from the scope streaming node.
Segmented Mode
Additionally, MF and UHF instruments which have the DIG option enabled can optionally record data in "segmented" mode which allows back-to-back measurements with very small hold-off times between measurements. Segmented mode enables the user to make a fixed number of measurements (the segments), which are stored completely in the memory of the instrument, before they are transferred to the Data Server (this overcomes the data transfer rate limitation of the device’s connected physical interface, e.g., USB or 1GbE for a fixed number of measurements). The advantage to this mode is precisely that the hold-off time, i.e. the delay between two measurements, can be very low. Data recorded in segmented mode is still available from the instrument node /DEV…./SCOPES/n/WAVE as for non-segmented data, but requires an additional reshaping described in Segmented Recording. |
Scope Data Nomenclature
We’ll use the following terminology to describe the scope data streamed from the device:
|
Scope Data Structures
The device node /DEV…./SCOPES/n/WAVE (and /DEV…./SCOPES/n/STREAM/SAMPLE DIG Option enabled, API level > 4) return the following data structures based on the API level used by the session:
The Scope Module always returns scope data in the
ZIScopeWaveEx
format, regardless of which
supported API level (1, >4) was used in the session where the Scope
Module was instantiated. However, the data in the |
Advantages of the Scope Module
Although it is possible to acquire scope data using the lower-level subscribe/poll method, the Scope Module provides API users with several advantages. Specifically, the Scope Module:
-
Provides a uniform interface to acquire scope data from all instrument classes (HF2 scope usage differs from and MF and UHF devices, especially with regards to scaling).
-
Scales and offsets the scope wave data to get physically meaningful values. If data is polled from the device node using subscribe/poll the scaling and offset must be applied manually.
-
Assembles large multi-block transferred scope data into single complete records. When the scope is configured to record large scope lengths and data is directly polled from the device node /DEV…/SCOPES/n/WAVE the data is split into multiple blocks for efficient transfer of data from the Data Server to the API; these must then be programmatically reassembled. The Scope Module performs this assembly and returns complete scope records (unless used in pass-through mode,
mode=0
). -
Can be configured to return the FFT of the acquired scope records (with
mode=3
) as provided by the Scope Tab in the LabOne UI. FFT data is not available from the device nodes in the /DEV/…./SCOPES/ branch using subscribe/poll. -
Can be configured to average the acquired scope records the
averager/
parameters. -
Can be configured to return a specific number of scope records using the
historylength
parameter.
Working with Scope Module
It is important to note that the instrument’s scope is implemented in the firmware of the instrument itself and most of the parameters relevant to scope data recording are configured as device nodes under the /DEV…/SCOPES/ branch. Please refer to the instrument-specific User Manual for a description of the Scope functionality and a list of the available nodes.
The Scope Module does not modify the instrument’s scope configuration and, as such, processes the data arriving from the instrument in a somewhat passive manner. The Scope Module simply reassembles data transferred in multiple blocks into complete segments (so that they consist of the configured /DEV…./SCOPES/n/LENGTH) and applies the offset and scaling required to get physically meaningful values to the (integer) data sent by the instrument.
The following steps should be used as a guideline for a Scope Module work-flow:
-
Create an instance of the Scope Module. This instance may be re-used for recording data with different instrument settings or Scope Module configurations.
-
Subscribe in the Scope Module to the scope’s streaming block node (/DEV…./SCOPES/n/WAVE) to specify which device and scope to acquire data from. Data will only be acquired after enabling the scope and calling Scope Module
execute()
. -
Configure the instrument ready for the experiment. When acquiring data from the signal inputs it is important to specify an appropriate value the for input range (/DEV…./SIGINS/n/RANGE) to obtain the best bit resolution in the scope. The signal input range on MF and UHF instruments can be adjusted automatically, see the /DEV…./SIGINS/n/AUTORANGE node and API utility functions demonstrating its use (e.g.
zhinst.utils.sigin_autorange()
in the LabOne Python API). -
Configure the instrument’s scope as required for the measurement. If recording signals other than hardware channel signals (such as a PID’s error or a demodulator R output), be sure to configure the /DEV…./SCOPES/n/CHANNELS/n/LIMIT\{LOWER UPPER} accordingly to obtain the best bit resolution in the scope).
-
Configure the
*
parameters as required, in particular:-
Set
mode
in order to specify whether to return time or frequency domain data. See Scope Module Modes for more information on the Scope Module’s modes. -
Set the
historylength
parameter to tell the Scope Module to only return a certain number of records. Note, as the Scope Module is acquiring data therecords
output parameter may grow larger thanhistorylength
; the Scope Module will return the last number of records acquired. -
Set
averager/weight
to a value larger than 1 to enable averaging of scope records, see Averaging.
-
-
Enable the scope (if not previously enabled) and call Scope Module
execute()
to start acquiring data. -
Wait for the Scope Module to acquire the specified number of records. Note, if certain scope parameters are modified during recording, the history of the Scope Module will be cleared, Scope Parameters that reset the Scope Module for the list of parameters that trigger a Scope Module reset.
-
Call Scope Module
read()
to transfer data from the Module to the client. Data may be read out usingread()
before acquisition is complete (advanced use). Note, an intermediate read will create a copy in the client of the incomplete record which could be critical for memory consumption in the case of very long scope lengths or high segment counts. The data structure returned byread()
is of type ZIScopeWaveEx. -
Check the flags of each record indicating whether any problems occurred during acquisition.
-
Extract the data for each recorded scope channel and, if recording data in segmented mode, reshape the wave data to allow easier access to multi-segment records (see Segmented Recording) Note, the scope data structure only returns data for enabled scope channels.
Data Acquisition and Transfer Speed
It is important to note that the time to transfer long scope segments from the device to the Data Server can be much longer than the duration of the scope record itself. This is not due to the Scope Module but rather due to the limitation of the physical interface that the device is connected on (USB, 1GbE). Please ensure that the PC being used has adequate memory to hold the scope records. |
Scope Module Modes
The mode
is applied for all scope channels returned by the Scope
Module. Although it is not possible to return both time and frequency
domain data in one instance of the Scope Module, multiple instances may
be used to obtain both.
The Scope Module does not return an array consisting of the points in time (time mode) or frequencies (FFT mode) corresponding to the samples in ZIScopeWaveEx. These can be constructed as arrays of n points, where n is the configured scope length (/DEV…/SCOPES/n/LENGTH)) spanning the intervals:
- Time mode
-
[0,
dt*totalsamples
], wheredt
andtotalsamples
are fields in ZIScopeWaveEx.
In order to get a time array relative to the trigger position,(timestamp - triggertimestamp)/float(clockbase)
must be subtracted from the times in the interval, wheretimestamp
andtriggerstamp
are fields in ZIScopeWaveEx. - FFT mode
-
[0,
(clockbase/2^scope_time)/2
], wherescope_time
is the value of the device node /DEV…./SCOPES/n/TIME. andclockbase
is the value of /DEV…./CLOCKBASE.
Averaging
When averager/weight
is set to be greater than 1, then each new scope
record in the history element is an exponential moving average of all
the preceding records since either execute()
was called or
averager/restart
was set to 1. The average is calculated by the Scope
Module as following:
alpha = 2/(weight + 1)
newVal = alpha * lastRecord + (1 - alpha) * history
history = newVal
where newVal
becomes the last record in the Scope Module’s history. If
the scope is in Single mode, no averaging is performed. The weight
corresponds to the number of segments to achieve 63% settling, doubling
the value of weight achieves 86% settling.
It is important to note that the averaging functionality is performed by the Scope Module on the PC where the API client runs, not on the device. Enabling averaging does not mean that less data is sent from the instrument to the Data Server.
The average calculation can be restarted by setting averager/restart
to 1. It is currently not possible to tell how many scope segments have
been averaged (since the reset). In general, however, the way to track
the current scope record is via the sequenceNumber
field in
ZIScopeWaveEx.
Segmented Recording
When the instrument’s scope runs segmented mode the wave
structure
member in the
ZIScopeWaveEx
is an array
consisting of length*segment_count
where length
is the value of
/DEV…./SCOPES/0/LENGTH and num_segments
is
/DEV…./SCOPES/n/SEGMENTS/COUNT. This is equal to the value of the
totalsamples
structure member.
The Scope Module’s progress()
method can be used to check the progress
of the acquisition of a single segmented recording. It is possible to
read out intermediate data before the segmented recording has finished.
This will however, perform a copy of the data; the user should ensure
that adequate memory is available.
If the segment count in the instrument’s scope is changed, the Scope Module must be re-executed. It is not possible to read multiple records consisting of different numbers of segments within one Scope Module execution.
Scope Parameters that reset the Scope Module
The Scope Module parameter records
and progress are reset and all
records are cleared from the Scope Module’s history when the following
critical instrument scope settings are changed:
-
/DEV…/SCOPES/n/LENGTH
-
/DEV…/SCOPES/n/RATE
-
/DEV…/SCOPES/n/CHANNEL
-
/DEV…./SCOPES/n/SEGMENTS/COUNT
-
/DEV…./SCOPES/n/SEGMENTS/ENABLE
Device-specific considerations
Scope Module Use on HF2 Instruments
The HF2 scope is supported by the Scope Module, in which case the API
connects to the HF2 Data Server using LabOne API Levels 1
(the HF2 Data Server does not support higher levels). When using the
Scope Module with HF2 Instruments the parameter |
Scope Module Use on MF and UHF Instruments
For MF and UHF instruments no special considerations must be made except that LabOne API Levels 4 is not supported by the Scope Module; a higher API level must be used. Whilst not specific to the Scope Module, it should be noted that the instrument’s scope is not affected by loading device presets, in particular, default scope settings are not obtained by loading the instrument’s factory preset. |
Scope Module Node Tree
The following section contains reference documentation for the settings and measurement data available on the scope module.
Since these settings and data streams may be written and read using the LabOne APIs (Application Programming Interfaces) this section is of particular interest to users who would like to perform measurements programmatically via LabVIEW, Python, MATLAB, .NET or C.
AVERAGER
Read, Write Integer (enumerated) None Specifies the resampling mode. When averaging scope data recorded at a low sampling rate that is aligned by a high resolution trigger, scope data must be resampled to keep the corresponding samples between averaged recordings aligned correctly in time relative to the trigger time. 0 Linear interpolation 1 PCHIP interpolation
/AVERAGER/RESAMPLINGMODE
Properties:
Type:
Unit:
linear
pchip
Read, Write Integer (64 bit) None Set to 1 to reset the averager. The module sets averager/restart back to 0 automatically.
/AVERAGER/RESTART
Properties:
Type:
Unit:
Read, Write Integer (64 bit) None Specify the averaging behaviour. weight=0: Averaging disabled. weight>1: Moving average, updating last history entry.
/AVERAGER/WEIGHT
Properties:
Type:
Unit:
CLEARHISTORY
Read, Write Integer (64 bit) None Remove all records from the history list.
/CLEARHISTORY
Properties:
Type:
Unit:
ERROR
Read Integer (64 bit) None Indicates whether an error occurred whilst processing the current scope record; set to non-zero when a scope flag indicates an error. The value indicates the accumulated error for all the processed segments in the current record and is reset for every new incoming scope record. It corresponds to the status LED in the LabOne User Interface’s Scope tab - API users are recommended to use the flags structure member in ZIScopeWaveEx instead of this output parameter.
/ERROR
Properties:
Type:
Unit:
EXTERNALSCALING
Read, Write Double None Scaling to apply to the scope data transferred over API level 1 connection. Only relevant for HF2 Instruments.
/EXTERNALSCALING
Properties:
Type:
Unit:
FFT
Read, Write Integer (64 bit) None Enable calculation of the power value.
/FFT/POWER
Properties:
Type:
Unit:
Read, Write Integer (64 bit) None Enable calculation of the spectral density value.
/FFT/SPECTRALDENSITY
Properties:
Type:
Unit:
Read, Write Integer (enumerated) None FFT Window 0 Rectangular 1 Hann (default) 2 Hamming 3 Blackman Harris 16 Exponential (ring-down) 17 Cosine (ring-down) 18 Cosine squared (ring-down)
/FFT/WINDOW
Properties:
Type:
Unit:
rectangular
hann
hamming
blackman_harris
exponential
cos
cos_squared
HISTORYLENGTH
Read, Write Integer (64 bit) None Maximum number of entries stored in the measurement history.
/HISTORYLENGTH
Properties:
Type:
Unit:
LASTREPLACE
Read, Write Integer (64 bit) None Reserved for LabOne User Interface use.
/LASTREPLACE
Properties:
Type:
Unit:
MODE
Read, Write Integer (enumerated) None The Scope Module’s data processing mode. 0 Passthrough: scope segments assembled and returned unprocessed, non-interleaved. 1 Moving average: entire scope recording assembled, scaling applied, averager if enabled (see averager/weight), data returned in float non-interleaved format. 2 Reserved for future use (average n segments). 3 FFT, same as mode 1, except an FFT is applied to every segment of the scope recording before averaging. See the fft/* parameters for FFT parameters.
/MODE
Properties:
Type:
Unit:
passthrough
exp_moving_average
fft
RECORDS
Read Integer (64 bit) None The number of scope records that have been processed by the Scope Module since execute() was called or a critical scope setting has been modified (see manual for a list of scope settings that trigger a reset).
/RECORDS
Properties:
Type:
Unit:
SAVE
Read, Write String None The locale to use for the decimal point character and digit grouping character for numerical values in CSV files: "C": Dot for the decimal point and no digit grouping (default); "" (empty string): Use the symbols set in the language and region settings of the computer.
/SAVE/CSVLOCALE
Properties:
Type:
Unit:
Read, Write String None The character to use as CSV separator when saving files in this format.
/SAVE/CSVSEPARATOR
Properties:
Type:
Unit:
Read, Write String None The base directory where files are saved.
/SAVE/DIRECTORY
Properties:
Type:
Unit:
Read, Write Integer (enumerated) None The format of the file for saving data. 0 MATLAB 1 CSV 2 ZView (Impedance data only) 3 SXM (Image format) 4 HDF5
/SAVE/FILEFORMAT
Properties:
Type:
Unit:
mat
csv
zview
sxm
hdf5
Read, Write String None Defines the sub-directory where files are saved. The actual sub-directory has this name with a sequence count (per save) appended, e.g. daq_000.
/SAVE/FILENAME
Properties:
Type:
Unit:
Read, Write Integer (64 bit) None Initiate the saving of data to file. The saving is done in the background. When the save has finished, the module resets this parameter to 0.
/SAVE/SAVE
Properties:
Type:
Unit:
Read, Write Integer (64 bit) None Automatically save the data to file immediately before reading out the data from the module using the read() command. Set this parameter to 1 if you want to save data to file when running the module continuously and performing intermediate reads.
/SAVE/SAVEONREAD
Properties:
Type:
Unit: