# 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.

Figure 1. The plot was generated by example_data_acquisition_edge.py, an example distributed on our public GitHub repository. The plot shows 10 bursts of data acquired from a demodulator; each burst was recorded when the demodulator’s R value exceeded a specified threshold using a positive edge trigger.

## 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.

Table 1. Overview of the acquisition modes available in the Data Acquisition Module.
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

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 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.

Figure 2. Explanation of the Data Acquisition Module’s parameters for an Edge 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 automatically for more information.

Figure 3. Explanation of the Data Acquisition Module’s parameters for a positive 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

Figure 4. Explanation of the Data Acquisition Module’s parameters for a 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 (see Figure 4). 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.

Example 1. Python code demonstrating how to use the findlevel parameter. Taken from the Python example example_data_acquisition_grid.
# 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):

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]

### Signal Subscription Options

source signal

Node

Signal Name

Description (Path of the node containing the signal(s))

Comment

demod

x

Demodulator output in-phase component

y

r

Demodulator output amplitude

theta

Demodulator output phase

frequency

Oscillator frequency

auxin0

Auxilliary input channel 1

auxin1

Auxilliary input channel 2

xiy

Combined demodulator output in-phase and quadrature components

complex output (can only be used as FFT input))

df

Demodulator output phase derivative (can only be used for FFT(dθ/dt)/(2π)

impedance

realz

In-phase component of impedance sample

imagz

absz

Amplitude of impedance sample

phasez

Phase of impedance sample

frequency

Oscillator frequency

param0

Measurement parameter that depends on circuit configuration

param1

Measurement parameter that depends on circuit configuration

drive

Amplitude of the AC signal applied to the device under test

bias

DC Voltage applied to the device under test

z

Combined impedance in-phase and quadrature components

complex (can only be used as FFT input)

other

Nodes not listed here

Nodes containing only one signal do not have a source_signal field.

FFT (optional)

Name (node_path)

Description (Path of the node containing the signal(s))

Comment

FFT

complex output

complex_selector (mandatory with FFT)

Name (node_path)

Description (Path of the node containing the signal(s))

Comment

real

Real component of FFT

imag

Imaginary component of FFT

abs

Absolute component of FFT

phase

Phase component of FFT

filter (optional)

Name (node_path)

Description (Path of the node containing the signal(s))

Comment

filter

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)

Name (node_path)

Description (Path of the node containing the signal(s))

Comment

pwr

Power calculation

math_operation (optional)

Name (node_path)

Description (Path of the node containing the signal(s))

Comment

avg

Average of grid repetitions (parameter grid/repetitions)

std

Standard deviation

## Data Acquisition Module Node Tree

The following section contains reference documentation for the settings and measurement data available on the data acquisition 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.

### 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.

 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. dev123 (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.

 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).

 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/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.

 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.

 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.

 1 nearest Use the closest data point (nearest neighbour interpolation). 2 linear Use linear interpolation. 4 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.

 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.

 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.

 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).