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
). The example runs the Scope Module in both time and frequency mode with scope record averaging enabled. See the Section Running the Examples in the Python Chapter for help getting started with the Python examples.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 Parameters
The following tables provide a comprehensive list of the module’s parameters, see:
Path | Type | Unit | Description |
---|---|---|---|
|
bool |
- |
Set to 1 to reset the averager. The module sets |
Path | Type | Unit | Description |
---|---|---|---|
|
int |
- |
Specify the averaging behavior:
|
|
int |
- |
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. The mode is either:
|
|
bool |
- |
Remove all records from the history list. |
|
double |
- |
Only relevant for HF2 Instruments. Specify the scaling to apply to the scope data based on the range of the instrument channel (/DEV…./SCOPES/0/CHANNEL) that is being recorded. For the following values of /DEV…/SCOPES/0/CHANNEL set
|
|
bool |
- |
Enable calculation of the power value. |
|
bool |
- |
Enable calculation of the spectral density value. |
|
int |
- |
FFT Window:
|
|
int |
- |
Maximum number of entries stored in the measurement history. |
|
int |
- |
Reserved for LabOne User Interface use. |
|
int |
- |
The Scope Module’s data processing mode:
|
|
- |
- |
Core module |
Path | Type | Unit | Description |
---|---|---|---|
|
int |
- |
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 |
|
int |
- |
The number of scope records that have been processed by the Scope Module since |