# Software Trigger (Recorder) Module

In LabOne Releases prior to 17.12, the Recorder Module corresponds to the Software Trigger Tab of the LabOne User Interface. It allows the user to record bursts of instrument data based upon pre-defined trigger criteria similar to that of a laboratory oscilloscope, see Figure 1 for an example. The types of trigger available are listed in Table 1.

 Future Deprecation Warning In LabOne Release 17.12 and subsequent releases the Recorder Module has been superceded by the Data Acquisition Module. We strongly recommend using the Data Acquisition Module instead of the Recorder Module for time (and frequency) domain data acquisition. In particular, existing users of the Recorder module can use the guide Migrating a zoomFFT program to the DAQ Module.
Table 1. Overview of the trigger types available in the Software Trigger Module.
Trigger Type Description N/type

Manual

For simple recording.

0

Edge

Edge trigger with level hysteresis and noise rejection, see Figure 2.

1

Digital

2

Pulse

Pulse width trigger with level hysteresis and noise reduction, see Figure 3 and Figure 4.

3

Tracking (edge or pulse)

Level tracking trigger to compensate signal drift, see Figure 5.

4

Hardware Trigger

UHFLI and MFLI only. Trigger on one of the instrument’s hardware trigger channels.

6

Figure 1. The plot shows 10 bursts of data from a single demodulator; each burst was recorded when the demodulator’s R value exceeded a specified threshold using a positive edge trigger.

See Table 2 for the input parameters to configure the Software Trigger’s Module. Note that some parameters effect all triggers, e.g., endless, whereas some are configured on a per-trigger basis, e.g., N/duration, where N is the index of the trigger, starting at zero. The data output when using the Software Trigger’s read command has the same format as returned by ziCore’s poll command.

Figure 2. Explanation of the Software Trigger Module’s parameters for an Edge Trigger.
Figure 3. Explanation of the Software Trigger Module’s parameters for a positive Pulse Trigger.
Figure 4. Explanation of the Software Trigger parameters for a positive or negative Pulse Trigger.
Figure 5. Explanation of the Software Trigger Module’s parameters for a Tracking Trigger.

## Determining the Trigger Level automatically

The SW Trigger Module can calculate the 0/level and 0/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 5). In the LabOne User Interface this functionality corresponds to the "Find" button in the Settings sub-tab of the SW Trigger Tab.

This functionality is activated via API by setting the 0/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 SW Trigger 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 SW Trigger has finished its calculation of the level and hysteresis parameters it sets the value of the 0/findlevel parameter to 0 and writes the values to the 0/level and 0/hysteresis parameters. Note that the calculation is only performed if the SW Trigger Module is currently running, i.e., after execute() has been called. See Example 1 for Python code demonstrating how to use this behavior.

Example 1. Python code demonstrating how to use the 0/findlevel parameter. Taken from the Python example example_swtrigger_grid.
# Start the Software Trigger's thread. Ready to record triggers.
trigger.execute()
# Tell the SW Trigger to determine the trigger level.
trigger.set('0/findlevel', 1)
time.sleep(0.1) # Ensure findlevel has been set before continuing.
trigger_params = trigger.get('*', True)
timeout = 10  # [s]
t0 = time.time()
# Wait until the levels have been found (when findlevel is set to 0).
while trigger_params['/0/findlevel'] = 1:
time.sleep(0.05)
trigger_params = trigger.get('*', True)
if time.time() - t0 > timeout:
trigger.finish()
trigger.clear()
raise RuntimeError("SW Trigger didn't find trigger level after %.3f seconds." % timeout)
print("Level: {}.".format(trigger_params['/0/level'][0])
print("Hysteresis: {}.".format(trigger_params['/0/hysteresis'][0]))

## Using the SW Trigger with a Digital Trigger

To use the SW Trigger with a digital trigger, it must be configured to use a digital trigger type (by setting 0/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 0/triggernode to the device node /devn/demods/m/sample.dio). It is important to be aware that the SW Trigger takes its value for the DIO output from the demodulator sample field bits, not from a node in the /devn/dios/ branch. As such, the specified demodulator must be enabled and and an appropriate transfer rate configured that meets the required trigger resolution (the SW Trigger can only resolve triggers at the resolution of 1/(/devn/demods/m/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 (0/bits) to be specified but also a bit mask (0/mask) 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 (0/edge set to value 1), the SW Trigger is triggered when the following equality holds for the DIO value:

(/devn/demods/m/sample.dio BITAND 0/mask) = (0/bits BITAND 0/mask)

and this equality has not been met for the previous value in time (the previous sample) of /devn/demods/m/sample.dio. For negative edge triggering (0/edge set to value 2), the SW Trigger is triggered when the following inequality holds for the current DIO value:

(/devn/demods/m/sample.dio BITAND 0/mask) != (0/bits BITAND 0/mask)

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

## The Software Trigger’s "retrigger" functionality

If the parameter 0/retrigger is enabled (set to 1), then the length of the current trigger’s data segment is extended if another trigger event occurs with the configured 0/duration. In other words, the returned data will have a length greater than 0/duration and contain multiple trigger events. The maximum size of the returned data corresponds to the value of buffersize; it is not possible to re-trigger beyond this time and a new trigger data segment will be started if required. Note, if a longer buffersize is desired it should be configured after setting the 0/duration parameter to avoid an automatic adjustment of buffersize by the Software Trigger.

Table 2. Software Trigger Input Parameters.
Setting/Path Type Unit Description

device

string

-

The device ID to execute the software trigger, e.g., dev123 (compulsory parameter).

buffersize

double

Seconds

Set the buffer size of the trigger object. The recommended buffer size is 2*N/duration.

flags

uint64

-

Define the SW Trigger’s behavior if sample loss is encountered: Fill holes (=0x01), align data that contains a timestamp (=0x02), throw EOFError if sample loss is detected.

endless

uint64

-

Enable endless triggering 1=enable; 0=disable.

forcetrigger

uint64

-

Force a trigger.

filename

string

-

This parameter is deprecated. If specified, i.e. not empty, it enables automatic saving of data in single triggering mode (endless = 0).

savepath

string

-

The directory where files are saved when saving data.

fileformat

string

-

The format of the file for saving data. 0=Matlab, 1=CSV, 3=SXM (Image Format), 4=HDF5.

historylength

uint64

-

Maximum number of entries stored in the measurement history.

clearhistory

uint64

-

Clear the measurement history

triggered

uint64

-

Has the software trigger triggered? 1=Yes, 0=No (read only).

N/bandwidth

double

Hz

Only for Tracking Triggers. The bandwidth used in the calculation of the exponential running average of the source signal.

N/bitmask

uint64

-

Only for Digital triggers. Specify the bitmask used with N/bits. The trigger value is bits AND bit mask (bitwise).

N/bits

uint64

-

Only for Digital triggers. Specify the bits used for the Digital trigger value. The trigger value is bits AND bit mask (bitwise)

N/count

uint64

-

The number of triggers to save.

N/delay

uint64

Seconds

The amount of time to record data before the trigger was activated, Delay: Time delay of trigger frame position (left side) relative to the trigger edge. For delays smaller than 0, trigger edge inside trigger frame (pre trigger). For delays greater than 0, trigger edge before trigger frame (post trigger), see Figure 2.

N/duration

double

Seconds

The length of time to record data for, see Figure 2.

N/edge

uint64

-

Define on which signal edge to trigger. Triggers when the trigger input signal crosses the trigger level from either low to high (edge=1), high to low (edge=2) or both (edge=3). Used for Trigger Type edge, pulse, tracking edge and tracking pulse. In the case of pulse trigger, the value specifies a positive (edge=1) or negative (edge=2) pulse relative to the trigger level (edge=3 specifies either positive or negative).

N/findlevel

uint64

-

Automatically find the value of N/level based on the current signal value.

N/level

uint64

Many

Specify the main trigger level value.

N/holdoff/count

uint64

-

The holdoff count, the number of skipped triggers until the next trigger is recorded again.

N/holdoff/time

double

Seconds

The holdoff time, the amount of time until the next trigger is recorded again. A hold off time smaller than @0/[email protected] will produce overlapping trigger frames.

N/hysteresis

double

Many

Specify the hysteresis value (the trigger is re-armed after the signal exceeds N/level and then falls below N/hysteresis, if using positive edge).

N/pulse/max

double

-

Only for Pulse triggers: The maximum pulse width to trigger on. See Figure 3.

N/pulse/min

double

-

Only for Pulse triggers: The minimum pulse width to trigger on. See Figure 3.

N/retrigger

uint64

-

1=enable, 0=disable. Enable to allow re-triggering within one trigger duration. If enabled continue recording data in on segment if another trigger comes within the previous trigger’s duration. If disabled the triggers will be recorded as separate events.

N/triggernode

string

-

Path and signal of the node that should be used for triggering, separated by a dot (.), e.g. /devN/demods/0/sample.x.

SAMPLE.X

Demodulator X value

SAMPLE.Y

Demodulator Y value

SAMPLE.R

Demodulator Magnitude

SAMPLE.THETA

Demodulator Phase

SAMPLE.AUXIN0

Auxiliary Input 1 value

SAMPLE.AUXIN1

Auxiliary Input 2 value

SAMPLE.DIO

Digital I/O value

Over HW Trigger paths may also be specified (device-class dependent). Overrides values from 0/path and 0/source.

N/type

uint64

-

The trigger type, see Table 1

0/grid/mode

int

-

Enable grid mode. In Grid Mode a matrix instead of a vector is returned by read(). Each trigger becomes a row in the matrix and each trigger’s data is interpolated onto a new grid defined by the number of columns: 0: Disable, 1: Enable grid mode with nearest neighbor interpolation, 2: Enable grid mode with linear interpolation.

0/grid/repetitions

int

-

The number of times to perform 0/grid/operation on the data in one grid.

0/grid/operation

int

-

If 0/grid/repetitions is greater than 1, either replace or average the data in the grid’s matrix.

0/grid/cols

int

-

Specify the number of columns in the grid’s matrix. The data from each row is interpolated onto a grid with the specified number of columns.

0/grid/rows

int

-

Specify the number of rows in the grid’s matrix. Each row is the data recorded from one trigger interpolated onto the columns.

0/grid/direction

int

-

The direction to organize data in the grid’s matrix: 0: Forward. 1: Reverse. 2: Bidirectional. 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. Reverse - the data in each row is ordered reverse chronologically, e.g., the first data point in each row corresponds to the last timestamp in the trigger data. Bidirectional - the ordering of the data alternates between Forward and Backward ordering from row-to-row, the first row is Forward ordered.

N/path

string

-

This parameter is deprecated, see the N/triggernode parameter.

N/source

uint64

-

This parameter is deprecated, see the N/triggernode parameter.

N/hwtrigsource

uint64

-

This parameter is deprecated, see the N/triggernode` parameter.

 Level and Hysteresis Settings with a Pulse Trigger For the pulse trigger type, there is a subtle difference between the way the trigger level and the hysteresis are used for positive/negative pulse triggering (N/edge= 1 or 2) and both (N/edge= 3). The difference can be seen in Figure 3 and Figure 4.