Skip to content

Data Acquisition Module

The Data Acquisition Module corresponds to the Data Acquisition tab of the LabOne User Interface. It enables the user to record and align time and frequency domain data from multiple instrument signal sources at a defined data rate. The data may be recorded either continuously or in bursts based upon trigger criteria analogous to the functionality provided by laboratory oscilloscopes.

example_data_acquisition_edge
Figure 1: example_data_acquisition_edge

DAQ Module Acquisition Modes and Trigger Types

This section lists the required parameters and special considerations for each trigger mode. For reference documentation of the module’s parameters, please see Data Acquisition Module Node Tree.

The following acquisition modes exists:

Mode / Trigger Type Description Value of type
Continuous Continuous recording of data. 0
Edge Edge trigger with noise rejection. 1
Pulse Pulse width trigger with noise rejection. 3
Tracking (Edge or Pulse) Level tracking trigger to compensate for signal drift. 4
Digital Digital trigger with bit masking. 2
Hardware Trigger on one of the instrument’s hardware trigger channels (not available on HF2). 6
Pulse Counter Trigger on the value of an instrument’s pulse counter (requires CNT Option). 8

Continuous Acquisition

This mode performs back-to-back recording of the subscribed signal paths. The data is returned by read() in bursts of a defined length (duration). This length is defined either:

  • Directly by the user via /duration for the case of nearest or linear sampling (specified by /grid/mode).
  • Set by the module in the case of exact grid mode based on the value of /grid/cols and the highest sampling rate of all subscribed signal paths.

Acquisition using Level Edge Triggering

Parameters specific to edge triggering are:

  • /level
  • /hysteresis

The user can request automatic calculation of the /level and /hysteresis parameters by setting the /findlevel parameter to 1. Please see Determining the Trigger Level automatically for more information.

The following image explains the Data Acquisition Module’s parameters for an Edge Trigger.

daq_analog_trigger
Figure 2: daq_analog_trigger

Acquisition using Pulse Triggering

Parameters specific to pulse triggering are:

  • /level
  • /hysteresis
  • /pulse/min
  • /pulse/max

The user can request automatic calculation of the /level and /hysteresis parameters by setting the /findlevel parameter to 1. Please see Determining the Trigger Level for more information.

The following image explains the Data Acquisition Module’s parameters for a positive Pulse Trigger.

daq_pulse_trigger
Figure 3: daq_pulse_trigger

Acquisition using Tracking Edge or Pulse Triggering

In addition to the parameters specific to edge and pulse triggers, the parameter that is of particular importance when using a tracking trigger type is:

  • /bandwidth

daq_tracking_trigger
Figure 4: daq_tracking_trigger

Acquisition using Digital Triggering

To use the DAQ Module with a digital trigger, it must be configured to use a digital trigger type (by setting type to 2) and to use the output value of the instrument's DIO port as it's trigger source. This is achieved by setting /triggernode to the device node /DEV..../DEMODS/N/SAMPLE.bits. It is important to be aware that the Data Acquisition Module takes its value for the DIO output from the demodulator sample field bits, not from a node in the /DEV..../DIOS branch. As such, the specified demodulator must be enabled and and an appropriate transfer rate configured that meets the required trigger resolution (the Data Acquisition Module can only resolve triggers at the resolution of 1//DEV..../DEMODS/N/RATE it is not possible to interpolate a digital signal to improve trigger resolution and if the incoming trigger pulse on the DIO port is shorter than this resolution, it may be missed).

The Digital Trigger allows not only the trigger bits (/bits) to be specified but also a bit mask (/bitmask) in order to allow an arbitrary selection of DIO pins to supply the trigger signal. When a positive, respectively, negative edge trigger is used, all of these selected pins must become high, respectively low. The bit mask is applied as following. For positive edge triggering (/edge set to value 1), the Data Acquisition Module recording is triggered when the following equality holds for the DIO value:

(/DEV..../DEMODS/N/SAMPLE.bits BITAND bitmask) == (bits BITAND bitmask)

and this equality has not been met for the previous value in time (the previous sample) of /DEV..../DEMODS/N/SAMPLE.bits. For negative edge triggering (/edge set to value 2), the Data Acquisition Module recording is triggered when the following inequality holds for the current DIO value:

(/DEV..../DEMODS/N/SAMPLE.bits BITAND bitmask) != (bits BITAND bitmask)

and this inequality was not met (there was equality) for the previous value of the DIO value.

Acquisition using Hardware Triggering

There are no parameters specific only to hardware triggering since the hardware trigger defines the trigger criterion itself; only the trigger edge must be specified. For a hardware trigger the triggernode must be one of:

  • /DEV.../CNTS/N/SAMPLE.TrigAWGTrigN + (requires CNT Option)
  • /DEV.../DEMODS/N/SAMPLE.TrigAWGTrigN
  • /DEV.../DEMODS/N/SAMPLE.TrigDemod4Phase
  • /DEV.../DEMODS/N/SAMPLE.TrigDemod8Phase
  • /DEV.../CNTS/N/SAMPLE.TrigInN (requires CNT Option)
  • /DEV.../DEMODS/N/SAMPLE.TrigInN
  • /DEV.../DEMODS/N/SAMPLE.TrigOutN

The hardware trigger type is not supported on HF2 instruments.

Acquisition using Pulse Counter Triggering

Pulse Counter triggering requires the CNT Option. Parameters specific to the pulse counter trigger type:

  • /eventcount/mode

The /triggernode must be configured to be a pulse counter sample /DEV…​./CNTS/N/SAMPLE.value.

Determining the Trigger Level automatically

The Data Acquisition Module can calculate the /level and /hysteresis parameters based on the current input signal for edge, pulse, tracking edge and tracking pulse trigger types. This is particularly useful when using a tracking trigger, where the trigger level is relative to the output of the low-pass filter tracking the input signal's average. In the LabOne User Interface this functionality corresponds to the "Find" button in the Settings sub-tab of the Data Acquisition Tab.

This functionality is activated via API by setting the /findlevel parameter to 1. This is a single-shot calculation of the level and hysteresis parameters, meaning that it is performed only once, not continually. The Data Acquisition Module monitors the input signal for a duration of 0.1 seconds and sets the level parameter to the average of the largest and the smallest values detected in the signal and the hysteresis to 10% of the difference between largest and smallest values. When the Data Acquisition Module has finished its calculation of the level and hysteresis parameters it sets the value of the /findlevel parameter to 0 and writes the values to the /level and /hysteresis parameters. Note that the calculation is only performed if the Data Acquisition Module is currently running, i.e., after execute() has been called.

The following python code demonstrates how to use the /findlevel parameter.

# Arm the Data Acquisition Module: ready for trigger acquisition.
trigger.execute()
# Tell the Data Acquisition Module to determine the trigger level.
trigger.set('findlevel', 1)
findlevel = 1
timeout = 10  # [s]
t0 = time.time()
while findlevel == 1:
    time.sleep(0.05)
    findlevel = trigger.getInt('findlevel')
    if time.time() - t0 > timeout:
        trigger.finish()
        trigger.clear()
        raise RuntimeError("Data Acquisition Module didn't find trigger level after %.3f seconds." % timeout)
level = trigger.getDouble('level')
hysteresis = trigger.getDouble('hysteresis')

Signal Subscription

The Data Acquisition Module uses dot notation for subscribing to the signals. Whereas with the Software Trigger (Recorder Module) you subscribe to an entire streaming node, e.g. /DEV..../DEMODS/N/SAMPLE and get all the signal components of this node back, with the Data Acquisition Module you specify the exact signal you are interested in capturing, e.g. /DEV..../DEMODS/N/SAMPLE.r /DEV..../DEMOD/0/SAMPLE.phase. In addition, by appending suffixes to the signal path, various operations can be applied to the source signal and cascaded to obtain the desired result. Some examples are given below (the /DEV.../DEMODS/n/SAMPLE prefix has been omitted):

Signal Description
x Demodulator sample x component.
r.avg Average of demodulator sample abs(x + iy).
x.std Standard deviation of demodulator sample x component.
xiy.fft.abs.std Standard deviation of complex FFT of x + iy.
phase.fft.abs.avg Average of real FFT of linear corrected phase.
freq.fft.abs.pwr Power of real FFT of frequency.
r.fft.abs Real FFT of abs(x + iy).
df.fft.abs Real FFT of demodulator phase derivative (dθ/dt)/(2π).
xiy.fft.abs.pwr Power of complex FFT of x + iy.
xiy.fft.abs.filter Demodulator low-pass filter transfer function. Divide xiy.fft.abs by this to obtain a compensated FFT.

The specification for signal subscription is given below, together with the possible options. Angle brackets <> indicate mandatory fields. Square brackets [] indicate optional fields.

<node_path><.source_signal>[.fft<.complex_selector>[.filter]][.pwr][.math_operation]

source_signal

Note

Nodes not listed here probably only contain one signal and do not have a source_signal field.

Signal Name Description (Path of the node containing the signal(s)) Comment
<demod>.x Demodulator output in-phase component
<demod>.y Demodulator output quadrature component
<demod>.r Demodulator output amplitude
<demod>.theta Demodulator output phase
<demod>.frequency Oscillator frequency
<demod>.auxin0 Auxiliary input channel 1
<demod>.auxin1 Auxiliary input channel 2
<demod>.xiy Combined demodulator output in-phase and quadrature components complex output (can only be used as FFT input))
<demod>.df Demodulator output phase derivative (can only be used for FFT(dθ/dt)/(2π)
<impedance>.realz In-phase component of impedance sample
<impedance>.imagz Quadrature component of impedance sample
<impedance>.absz Amplitude of impedance sample
<impedance>.phasez Phase of impedance sample
<impedance>.frequency Oscillator frequency
<impedance>.param0 Measurement parameter that depends on circuit configuration
<impedance>.param1 Measurement parameter that depends on circuit configuration
<impedance>.drive Amplitude of the AC signal applied to the device under test
<impedance>.bias DC Voltage applied to the device under test
<impedance>.z Combined impedance in-phase and quadrature components complex (can only be used as FFT input)

complex_selector (mandatory with .fft)

Signal Name Description
real Real component of FFT
imag Imaginary component of FFT
abs Absolute component of FFT
phase Phase component of FFT

filter (optional)

Helper signal representing demodulator low-pass filter transfer function. It can only be applied to 'abs' FFT output of complex demodulator source signal, i.e. 'xiy.fft.abs.filter'. No additional operations are permitted. Can be used to compensate the FFT result for the demodulator low-pass filter.

pwr (optional)

Power calculation

math_operation (optional)

Signal Name Description
avg Average of grid repetitions (parameter grid/repetitions)
std Standard deviation

Node Documentation

This section describes all the nodes in the Data Acquisition Module node tree organized by branch.

awgcontrol

/awgcontrol

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Enable interaction with the AWG. If enabled, the row number is identified based on the digital row ID number set by the AWG. If disabled, every new trigger event is attributed to a new row sequentially.

bandwidth

/bandwidth

Properties: Read, Write
Type: Double
Unit: Hz

Set to a value other than 0 in order to apply a low-pass filter with the specified bandwidth to the triggernode signal before applying the trigger criteria. For edge and pulse trigger use a bandwidth larger than the trigger signal's sampling rate divided by 20 to keep the phase delay. For tracking filter use a bandwidth smaller than the trigger signal's sampling rate divided by 100 to track slow signal components like drifts. The value of the filtered signal is returned by read() under the path /DEV..../TRIGGER/LOWPASS.

bitmask

/bitmask

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Specify a bit mask for the DIO trigger value. The trigger value is bits AND bit mask (bitwise). Only used when the trigger type is digital.

bits

/bits

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Specify the value of the DIO to trigger on. All specified bits have to be set in order to trigger. Only used when the trigger type is digital.

buffercount

/buffercount

Properties: Read
Type: Integer (64 bit)
Unit: None

The number of buffers used internally by the module for data recording.

buffersize

/buffersize

Properties: Read
Type: Double
Unit: Seconds

The buffersize of the module's internal data buffers.

clearhistory

/clearhistory

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Set to 1 to clear all the acquired data from the module. The module immediately resets clearhistory to 0 after it has been set to 1.

count

/count

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

The number of trigger events to acquire in single-shot mode (when endless is set to 0).

delay

/delay

Properties: Read, Write
Type: Double
Unit: Seconds

Time delay of trigger frame position (left side) relative to the trigger edge. delay=0: Trigger edge at left border; delay<0: trigger edge inside trigger frame (pretrigger); delay>0: trigger edge before trigger frame (posttrigger)

device

/device

Properties: Read, Write
Type: String
Unit: None

The device serial to be used with the Data Acquisition Module, e.g. dev1000 (compulsory parameter).

duration

/duration

Properties: Read, Write
Type: Double
Unit: Seconds

The recording length of each trigger event. This is an input parameter when the sampling mode (grid/mode) is either nearest or linear interpolation. In exact sampling mode duration is an output parameter; it is calculated and set by the module based on the value of grid/cols and the highest rate of all the subscribed signal paths.

edge

/edge

Properties: Read, Write
Type: Integer (enumerated)
Unit: None

The trigger edge to trigger upon when running a triggered acquisition mode.

Value Description
1 "rising": Rising edge
2 "falling": Falling edge
3 "both": Both rising and falling

enable

/enable

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Set to 1 to enable the module and start data acquisition (is equivalent to calling execute()).

endless

/endless

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Set to 1 to enable endless triggering. Set to 0 and use count if the module should only acquire a certain number of trigger events.

eventcount

/eventcount/mode

Properties: Read, Write
Type: Integer (enumerated)
Unit: None

Specifies the trigger mode when the triggernode is configured as a pulse counter sample value (/DEV..../CNTS/0/SAMPLE.value).

Value Description
0 "every_sample": Trigger on every sample from the pulse counter, regardless of the counter value.
1 "incrementing_counter": Trigger on incrementing counter values.

fft

/fft/absolute

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Set to 1 to shift the frequencies in the FFT result so that the center frequency becomes the demodulation frequency rather than 0 Hz (when disabled).

/fft/powercompensation

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Apply power correction to the spectrum to compensate for the shift that the window function causes.

/fft/window

Properties: Read, Write
Type: Integer (enumerated)
Unit: None

The FFT window function to use (default 1 = Hann). Depending on the application, it makes a huge difference which of the provided window functions is used. Please check the literature to find out the best trade off for your needs.

Value Description
0 "rectangular": Rectangular
1 "hann": Hann
2 "hamming": Hamming
3 "blackman_harris": Blackman Harris 4 term
16 "exponential": Exponential (ring-down)
17 "cos": Cosine (ring-down)
18 "cos_squared": Cosine squared (ring-down)

findlevel

/findlevel

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Set to 1 to automatically find appropriate values of the trigger level and hysteresis based on the current triggernode signal value. The module sets findlevel to 0 once the values have been found and set.

flags

/flags

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Record flags. FILL = 0x1: always enabled; ALIGN = 0x2: always enabled; THROW = 0x4: Throw if sample loss is detected; DETECT = 0x8: always enabled.

forcetrigger

/forcetrigger

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Set to 1 to force acquisition of a single trigger for all subscribed signal paths (when running in a triggered acquisition mode). The module immediately resets forcetrigger to 0 after it has been set to 1.

grid

/grid/cols

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Specify the number of columns in the returned data grid (matrix). The data along the horizontal axis is resampled to the number of samples defined by grid/cols. The grid/mode parameter specifies how the data is sample onto the time, respectively frequency, grid.

/grid/direction

Properties: Read, Write
Type: Integer (enumerated)
Unit: None

The direction to organize data in the grid's matrix.

Value Description
0 "forward": Forward. The data in each row is ordered chronologically, e.g., the first data point in each row corresponds to the first timestamp in the trigger data.
1 "reverse": Reverse. The data in each row is in reverse chronological order, e.g., the first data point in each row corresponds to the last timestamp in the trigger data.
2 "bidirectional": Bidirectional. The ordering of the data alternates between Forward and Backward ordering from row-to-row. The first row is Forward ordered.
/grid/mode

Properties: Read, Write
Type: Integer (enumerated)
Unit: None

Specify how the acquired data is sampled onto the matrix's horizontal axis (time or frequency). Each trigger event becomes a row in the matrix and each trigger event's subscribed data is sampled onto the grid defined by the number of columns (grid/cols) and resampled as specified with this parameter.

Value Description
1 "nearest": Use the closest data point (nearest neighbour interpolation).
2 "linear": Use linear interpolation.
4 "exact": Do not resample the data from the subscribed signal path(s) with the highest sampling rate; the horizontal axis data points are determined from the sampling rate and the value of grid/cols. Subscribed signals with a lower sampling rate are upsampled onto this grid using linear interpolation.
/grid/overwrite

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

If enabled, the module will return only one data chunk (grid) when it is running, which will then be overwritten by subsequent trigger events.

/grid/repetitions

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Number of statistical operations performed per grid. Only applied when the subscribed signal path is, for example, an average or a standard deviation.

/grid/rowrepetition

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Enable row-wise repetition. With row-wise repetition, each row is calculated from successive repetitions before starting the next row. With grid-wise repetition, the entire grid is calculated with each repetition.

/grid/rows

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Specify the number of rows in the grid's matrix. Each row is the data recorded from one trigger event.

/grid/waterfall

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Set to 1 to enable waterfall mode: Move the data upwards upon each trigger event; the data from newest trigger event is placed in row 0.

historylength

/historylength

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Sets an upper limit for the number of data captures stored in the module.

holdoff

/holdoff/count

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

The number of skipped trigger events until the next trigger event is acquired.

/holdoff/time

Properties: Read, Write
Type: Double
Unit: Seconds

The hold-off time before trigger acquisition is re-armed again. A hold-off time smaller than the duration will produce overlapped trigger frames.

hysteresis

/hysteresis

Properties: Read, Write
Type: Double
Unit: Many

If non-zero, hysteresis specifies an additional trigger criteria to level in the trigger condition. The trigger signal must first go higher, respectively lower, than the hysteresis value and then the trigger level for positive, respectively negative edge triggers. The hysteresis value is applied below the trigger level for positive trigger edge selection. It is applied above for negative trigger edge selection, and on both sides for triggering on both edges. A non-zero hysteresis value is helpful to trigger on the correct edge in the presence of noise to avoid false positives.

level

/level

Properties: Read, Write
Type: Double
Unit: Many

The trigger level value.

preview

/preview

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

If set to 1, enable the data of an incomplete trigger to be read. Useful for long trigger durations (or FFTs) by providing access to the intermediate data.

pulse

/pulse/max

Properties: Read, Write
Type: Double
Unit: Seconds

The maximum pulse width to trigger on when using a pulse trigger.

/pulse/min

Properties: Read, Write
Type: Double
Unit: Seconds

The minimum pulse width to trigger on when using a pulse trigger.

refreshrate

/refreshrate

Properties: Read, Write
Type: Double
Unit: Hz

Set the maximum refresh rate of updated data in the returned grid. The actual refresh rate depends on other factors such as the hold-off time and duration.

save

/save/csvlocale

Properties: Read, Write
Type: String
Unit: 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/csvseparator

Properties: Read, Write
Type: String
Unit: None

The character to use as CSV separator when saving files in this format.

/save/directory

Properties: Read, Write
Type: String
Unit: None

The base directory where files are saved.

/save/fileformat

Properties: Read, Write
Type: Integer (enumerated)
Unit: None

The format of the file for saving data.

Value Description
0 "mat": MATLAB
1 "csv": CSV
2 "zview": ZView (Impedance data only)
3 "sxm": SXM (Image format)
4 "hdf5": HDF5
/save/filename

Properties: Read, Write
Type: String
Unit: 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/save

Properties: Read, Write
Type: Integer (64 bit)
Unit: 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/saveonread

Properties: Read, Write
Type: Integer (64 bit)
Unit: 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.

spectrum

/spectrum/autobandwidth

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Set to 1 to initiate automatic adjustment of the subscribed demodulator bandwidths to obtain optimal alias rejection for the selected frequency span which is equivalent to the sampling rate. The FFT mode has to be enabled (spectrum/enable) and the module has to be running for this function to take effect. The module resets spectrum/autobandwidth to 0 when the adjustment has finished.

/spectrum/enable

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Enables the FFT mode of the data Acquisition module, in addition to time domain data acquisition. Note that when the FFT mode is enabled, the grid/cols parameter value is rounded down to the nearest binary power.

/spectrum/frequencyspan

Properties: Read, Write
Type: Double
Unit: None

Sets the desired frequency span of the FFT.

/spectrum/overlapped

Properties: Read, Write
Type: Integer (64 bit)
Unit: None

Enables overlapping FFTs. If disabled (0), FFTs are performed on distinct abutting data sets. If enabled, the data sets of successive FFTs overlap based on the defined refresh rate.

triggered

/triggered

Properties: Read
Type: Integer (64 bit)
Unit: None

Indicates whether the module has recently triggered: 1=Yes, 0=No.

triggernode

/triggernode

Properties: Read, Write
Type: String
Unit: None

The node path and signal that should be used for triggering, the node path and signal should be separated by a dot (.), e.g. /DEV.../DEMODS/0/SAMPLE.X.

type

/type

Properties: Read, Write
Type: Integer (enumerated)
Unit: None

Specifies how the module acquires data.

Value Description
0 "continuous": Continuous acquisition (trigger off).
1 "analog_edge_trigger": Analog edge trigger.
2 "digital_trigger": Digital trigger mode (on DIO source).
3 "analog_pulse_trigger": Analog pulse trigger.
4 "analog_tracking_trigger": Analog tracking trigger.
5 "change_trigger": Change trigger.
6 "hardware_trigger": Hardware trigger (on trigger line source).
7 "pulse_tracking_trigger": Pulse tracking trigger, see also bandwidth.
8 "event_count_trigger": Event count trigger (on pulse counter source).
9 "burst_trigger": Burst trigger (device triggered acquisition).