Configure Analog Input Triggers

Analog Input Trigger Properties

An analog input trigger is defined as an event that initiates data logging. You can log data to the engine (memory) and to a disk file. As shown in the figure below, when a trigger occurs, the Logging property is automatically set On and data is stored in the specified target.

When defining a trigger, you must specify the trigger type. Additionally, you might need to specify one or more of these parameters:

  • A trigger condition and trigger condition value

  • The number of times to repeat the trigger

  • A trigger delay

  • A callback function to execute when the trigger event occurs

Properties associated with analog input triggers are as follows:

Property Name

Description

InitialTriggerTime

Indicate the absolute time of the first trigger.

ManualTriggerHwOn

Specify that the hardware device starts when a manual trigger is issued.

TriggerFcn

Specify the callback function to execute when a trigger occurs.

TriggerChannel

Specify the channel serving as the trigger source.

TriggerCondition

Specify the condition that must be satisfied before a trigger executes.

TriggerConditionValue

Specify one or more voltage values that must be satisfied before a trigger executes.

TriggerDelay

Specify the delay value for data logging.

TriggerDelayUnits

Specify the units in which trigger delay data is measured.

TriggerRepeat

Specify the number of additional times the trigger executes.

TriggersExecuted

Indicate the number of triggers that execute.

TriggerType

Specify the type of trigger to execute.

Except for TriggerFcn, these trigger-related properties are discussed in the following sections. TriggerFcn is discussed in Events and Callbacks.

Define Trigger Types and Conditions

This section contains the following topics:

Defining a trigger for an analog input object involves specifying the trigger type with the TriggerType property. You can think of the trigger type as the source of the trigger. For some trigger types, you might need to specify a trigger condition and a trigger condition value. Trigger conditions are specified with the TriggerCondition property, while trigger condition values are specified with the TriggerConditionValue property.

The analog input TriggerType and TriggerCondition values are given below.

Table 7-3. Analog Input TriggerType and TriggerCondition Values

TriggerType Value

TriggerCondition Value

Description

{Immediate}

None

The trigger occurs just after you issue the start function.

Manual

None

The trigger occurs just after you manually issue the trigger function.

Software

{Rising}

The trigger occurs when the signal has a positive slope when passing through the specified value.

Falling

The trigger occurs when the signal has a negative slope when passing through the specified value.

Leaving

The trigger occurs when the signal leaves the specified range of values.

Entering

The trigger occurs when the signal enters the specified range of values.

For some devices, additional trigger types and trigger conditions are available. Refer to the TriggerType and TriggerCondition property reference page for these device-specific values.

Trigger types are grouped into two main categories:

  • Device-independent triggers

  • Device-specific hardware triggers

The trigger types shown above are device-independent triggers because they are available for all supported hardware. For these trigger types, the callback that initiates the trigger event involves satisfying a trigger condition in the engine (software trigger type), or issuing a toolbox function (start or trigger). Conversely, device-specific hardware triggers depend on the specific hardware device you are using. For these trigger types, the callback that initiates the trigger event involves an external analog or digital signal.

Device-specific hardware triggers for National Instruments® and Measurement Computing™ devices are discussed in Device-Specific Hardware Triggers. Device-independent triggers are discussed below.

Immediate Trigger

If TriggerType is Immediate (the default value), the trigger occurs immediately after you issue the start function. You can configure an analog input object for continuous acquisition by using an immediate trigger and setting SamplesPerTrigger or TriggerRepeat to inf. If you use the TriggerRepeat set to inf, you must set your TriggerType to Immediate. You can use SamplesPerTrigger with any TriggerType setting. For more information on trigger repeats see Repeat Triggers.

To see how to set up continuous analog input acquisitions, refer to the Continuous Acquisitions Using Analog InputContinuous Acquisitions Using Analog Input example.

Manual Trigger

If TriggerType is Manual, the trigger occurs just after you issue the trigger function. A manual trigger might provide you with more control over the data that is logged. For example, if the acquired data is noisy, you can preview the data using peekdata, and then manually execute the trigger after you observe that the signal is well-behaved.

Software Trigger

If TriggerType is Software, the trigger occurs when a signal satisfying the specified condition is detected on the hardware channel specified by the TriggerChannel property. The trigger condition is specified as either a voltage value and slope, or a range of voltage values using the TriggerCondition and TriggerConditionValue properties.

Some acquisition speeds on some devices may not be available when the TriggerType is Software, due to hardware limitations. When you set TriggerType to Software, the device is put into a continuous acquisition mode, and acquisition begins when you call start. The data collected is analyzed as it comes in to detect the trigger condition you have specified. If the data does not contain your trigger condition, it is discarded. When the trigger condition is met, the engine begins storing data. This data can be retrieved using getdata. With some devices, the maximum speed of the device changes when it is running in continuous acquisition mode, making some speeds unavailable when setting TriggerType to Software.

Voice Activation Using a Software Trigger

This example shows you how to configure an acquisition with a sound card based on voice activation. The sample rate is set to 44.1 kHz and data is logged when an acquired sample has a value greater than or equal to 0.2 volt and a rising slope. A portion of the data is then extracted from the engine and plotted.

You can run this example by typing daqdoc5_3 at the MATLAB Command Window.

  1. Create a device object — Create the analog input object AIVoice for a sound card. The installed adaptors and hardware IDs are found with daqhwinfo.

    AIVoice = analoginput('winsound');
    %AIVoice = analoginput('nidaq','Dev1');
    %AIVoice = analoginput('mcc',1);
  2. Add channels — Add one hardware channel to AIVoice.

    chan = addchannel(AIVoice,1);
    %chan = addchannel(AIVoice,0); % For NI and MCC
  3. Configure property values — Define a 2-second acquisition and configure a software trigger. The source of the trigger is chan, and the trigger executes when a rising voltage level has a value of at least 0.2 volt.

    duration = 2; 
    AIVoice.SampleRate = 44100
    ActualRate = AIVoice.SampleRate;
    AIVoice.SamplesPerTrigger = (ActualRate*duration)
    AIVoice.TriggerChannel = chan
    AIVoice.TriggerType = Software
    AIVoice.TriggerCondition = Rising
    AIVoice.TriggerConditionValue = 0.2
  4. Acquire data — Start AIVoice, acquire the specified number of samples, and extract the first 1000 samples from the engine as sample-time pairs. Display the number of samples remaining in the engine.

    start(AIVoice)
    wait(AIVoice, duration+1)  
    [data,time] = getdata(AIVoice,1000);
    remsamp = num2str(AIVoice.SamplesAvailable);
    disp(['Number of samples remaining in engine: ', remsamp])

    Plot all extracted data.

    plot(time,data)
    drawnow
    xlabel('Time (sec.)')
    ylabel('Signal Level (Volts)')
    grid on
  5. Clean up — When you no longer need AIVoice, you should remove it from memory and from the MATLAB workspace.

    delete(AIVoice)
    clear AIVoice

Note that when using software triggers, you must specify the TriggerType value before the TriggerCondition value. The output from this example is shown below.

The first logged sample has a signal level value of at least 0.2 volt, and this value corresponds to time = 0. Note that after you issue the getdata function, 87,200 samples remain in the engine.

AIVoice.SamplesAvailable
ans =
       87200

Execute the Trigger

For an analog input trigger to occur, you must follow these steps:

  1. Configure the appropriate trigger properties.

  2. Issue the start function.

  3. Issue the trigger function if TriggerType value is Manual.

Once the trigger occurs, data logging is initiated. The device object and hardware device stop executing when the requested samples are acquired, a run-time error occurs, or you issue the stop function.

    Note   After a trigger occurs, the number of samples specified by SamplesPerTrigger is acquired for each channel group member before the next trigger can occur.

Trigger Delays

Trigger delays allow you to control exactly when data is logged after a trigger occurs. You can log data either before the trigger or after the trigger. Logging data before the trigger occurs is called pretriggering, while logging data after a trigger occurs is called posttriggering.

You configure trigger delays with the TriggerDelay property. Pretriggers are specified by a negative TriggerDelay value, while posttriggers are specified by a positive TriggerDelay value. You can delay data logging in time or in samples using the TriggerDelayUnits property. When TriggerDelayUnits is set to Samples, data logging is delayed by the specified number of samples. When the TriggerDelayUnits property is set to Seconds, data logging is delayed by the specified number of seconds.

Capture Pretrigger Data

In some circumstances, you might want to capture data before the trigger occurs. Such data is called pretrigger data. When capturing pretrigger data, the SamplesPerTrigger property value includes the data captured before and after the trigger occurs. Capturing pretrigger data is illustrated below.

You can capture pretrigger data for manual triggers and software triggers. If TriggerType is Manual, and the trigger function is issued before the trigger delay passes, then a warning is returned and the trigger is ignored (the trigger event does not occur).

You cannot capture pretrigger data for immediate triggers or device-specific hardware triggers.

    Note   Pretrigger data has negative relative time values associated with it. This is because time = 0 corresponds to the time the trigger event occurs and data logging is initiated.

Capture Posttrigger Data

In some circumstances, you might want to capture data after the trigger occurs. Such data is called posttrigger data. When capturing posttrigger data, the SamplesPerTrigger property value and the number of posttrigger samples are equal. Capturing posttrigger data is illustrated below.

You can capture posttrigger data using any supported trigger type.

Acquire Voice Activated Pretriggers

This example modifies daqdoc5_3 such that 500 pretrigger samples are acquired. You can run this example by typing daqdoc5_4 at the MATLAB Command Window.

  1. Create a device object — Create the analog input object AIVoice for a sound card. The installed adaptors and hardware IDs are found with daqhwinfo.

    AIVoice = analoginput('winsound');
    %AIVoice = analoginput('nidaq','Dev1');
    %AIVoice = analoginput('mcc',1);
  2. Add channels — Add one hardware channel to AIVoice.

    chan = addchannel(AIVoice,1);
    %chan = addchannel(AIVoice,0); % For NI and MCC
    
  3. Configure property values — Define a 2-second acquisition, and configure a software trigger. The source of the trigger is chan, and the trigger executes when a rising voltage level has a value of at least 0.2 volt. Additionally, 500 pretrigger samples are collected.

    duration = 2; % two second acquisition
    AIVoice.SampleRate = 44100
    ActualRate = AIVoice.SampleRate;
    AIVoice.SamplesPerTrigger = (ActualRate*duration)
    AIVoice.TriggerChannel = chan
    AIVoice.TriggerType = Software
    AIVoice.TriggerCondition = Rising
    AIVoice.TriggerConditionValue = 0.2
    AIVoice.TriggerDelayUnits = Samples
    AIVoice.TriggerDelay = -500
  4. Acquire data — Start AIVoice, acquire the specified number of samples, and extract the first 1000 samples from the engine as sample-time pairs.

    start(AIVoice)
    wait(AIVoice,duration+1)
    [data,time] = getdata(AIVoice,1000);

    Plot all the extracted data.

    plot(time,data)
    xlabel('Time (sec.)')
    ylabel('Signal Level (Volts)')
    grid on
  5. Clean up When you no longer need AIVoice, you should remove it from memory and from the MATLAB workspace.

    delete(AIVoice)
    clear AIVoice

The output from this example is shown below. Note that the pretrigger data constitutes half of the 1000 samples extracted from the engine. Additionally, pretrigger data has negative time associated with it because time = 0 corresponds to the time the trigger event occurs and data logging is initiated.

Repeat Triggers

You can configure triggers to occur once (one-shot acquisition) or multiple times. You control trigger repeats with the TriggerRepeat property. If TriggerRepeat is set to its default value of 0, then the trigger occurs once. If TriggerRepeat is set to a positive integer value, then the trigger is repeated the specified number of times. If TriggerRepeat is set to inf, then the trigger repeats continuously and you can stop the device object only by issuing the stop function.

Acquiring Voice Activated and Repeat Triggers

This example modifies daqdoc5_3 such that two triggers are issued. The specified amount of data is acquired for each trigger and stored in separate variables. The Timeout value is set to five seconds. Therefore, if getdata does not return the specified number of samples in the time given by the Timeout property plus the time required to acquire the data, the acquisition will be aborted.

You can run this example by typing daqdoc5_5 at the MATLAB Command Window.

  1. Create a device object — Create the analog input object AIVoice for a sound card. The installed adaptors and hardware IDs are found with daqhwinfo.

    AIVoice = analoginput('winsound');
    %AIVoice = analoginput('nidaq','Dev1');
    %AIVoice = analoginput('mcc',1);
  2. Add channels — Add one hardware channel to AIVoice.

    chan = addchannel(AIVoice,1);
    %chan = addchannel(AIVoice,0); % For NI and MCC
  3. Configure property values — Define a 1-second total acquisition time and configure a software trigger. The source of the trigger is chan, and the trigger executes when a rising voltage level has a value of at least 0.2 volt. Additionally, the trigger is repeated once when the trigger condition is met.

    duration = 0.5; % One-half second acquisition for each trigger
    AIVoice.SampleRate = 44100
    ActualRate = AIVoice.SampleRate;
    AIVoice.Timeout = 5
    AIVoice.SamplesPerTrigger = (ActualRate*duration)
    AIVoice.TriggerChannel = chan
    AIVoice.TriggerType = Software
    AIVoice.TriggerCondition = Rising
    AIVoice.TriggerConditionValue = 0.2
    AIVoice.TriggerRepeat = 1
  4. Acquire data — Start AIVoice, acquire the specified number of samples, extract all the data from the first trigger as sample-time pairs, and extract all the data from the second trigger as sample-time pairs. Note that you can extract the data acquired from both triggers with the command getdata(AIVoice,44100).

    start(AIVoice)
    wait(AIVoice,duration+1)
    [d1,t1] = getdata(AIVoice);
    [d2,t2] = getdata(AIVoice);

    Plot the data for both triggers.

    subplot(211), plot(t1,d1), grid on, hold on
    axis([t1(1)-0.05 t1(end)+0.05 -0.8 0.8])
    xlabel('Time (sec.)'), ylabel('Signal level (Volts)'),
    title('Voice Activation First Trigger')
    subplot(212), plot(t2,d2), grid on
    axis([t2(1)-0.05 t2(end)+0.05 -0.8 0.8])
    xlabel('Time (sec.)'), ylabel('Signal level (Volts)')
    title('Voice Activation Second Trigger')
  5. Clean up — When you no longer need AIVoice, you should remove it from memory and from the MATLAB workspace.

    delete(AIVoice)
    clear AIVoice

The data acquired for both triggers is shown below.

As described in Extract Data from the Engine, if you do not specify the amount of data to extract from the engine with getdata, then the amount of data returned is given by the SamplesPerTrigger property. You can return data from multiple triggers with one call to getdata by specifying the appropriate number of samples. When you return data that spans multiple triggers, a NaN is inserted in the data stream between trigger events. Therefore, an extra "sample" (the NaN) is stored in the engine and returned by getdata. Identifying these NaNs allows you to locate where and when each trigger was issued in the data stream.

The figure below illustrates the data stored by the engine during a multiple-trigger acquisition. The data acquired for each trigger is given by the SamplesPerTrigger property value. The relative trigger times are shown on the Time axis where the first trigger time corresponds to t1 (0 seconds by definition), the second trigger time corresponds to t2, and so on.

The following code modifies daqdoc5_5 so that multiple-trigger data is extracted from the engine with one call to getdata.

returndata = ActualRate*duration*(AIVoice.TriggerRepeat + 1);
start(AIVoice)
wait(AIVoice,duration+1)
[d,t] = getdata(AIVoice,returndata);

Plot the data.

plot(t,d)
xlabel('Time (sec.)')
ylabel('Signal Level (Volts)')
title('Voice Activation for Both Triggers')
grid on

The multiple-trigger data is shown below.

You can find the relative trigger times by searching for NaNs in the returned data. You can find the index location of the NaN in d or t using the isnan function.

index = find(isnan(d))
index =
       22051

With this information, you can find the relative time for the second trigger.

t2time = t(index+1)
t2time =
    0.5980

How Many Triggers Occurred?

You can find out how many triggers occurred with the TriggersExecuted property value. The trigger number for each trigger executed is also recorded by the EventLog property. A convenient way to access event log information is with the showdaqevents function.

For example, suppose you create the analog input object ai for a sound card and add one channel to it. ai is configured to acquire 40,000 samples with five triggers using the default sampling rate of 8000 Hz.

ai = analoginput('winsound');
ch = addchannel(ai,1);
ai.TriggerRepeat = 4;
start(ai)

TriggersExecuted returns the number of triggers executed.

ai.TriggersExecuted
ans =
      5

showdaqevents returns information for all the events that occurred while ai was executing.

showdaqevents(ai)
   1 Start               ( 10:22:04, 0 )
   2 Trigger#1           ( 10:22:04, 0 )          Channel: N/A
   3 Trigger#2           ( 10:22:05, 8000 )       Channel: N/A
   4 Trigger#3           ( 10:22:06, 16000 )      Channel: N/A
   5 Trigger#4           ( 10:22:07, 24000 )      Channel: N/A
   6 Trigger#5           ( 10:22:08, 32000 )      Channel: N/A
   7 Stop                ( 10:22:09, 40000 )

For more information about recording and retrieving events, refer to Record and Retrieve Event Information.

When Did the Trigger Occur?

You can find the absolute time of the first trigger event with the InitialTriggerTime property value. The absolute time is returned using the MATLAB clock format.

[year month day hour minute seconds]

For example, the absolute time of the first trigger event for the preceding example is

abstime = ai.InitialTriggerTime
abstime =
1.0e+003 *
    1.9990    0.0040    0.0170    0.0100    0.0220    0.0041

To convert the clock vector to a more convenient form, you can use the sprintf function.

t = fix(abstime);
sprintf('%d:%d:%d', t(4),t(5),t(6))
ans =
10:22:4

You can also use the showdaqevents function to return the absolute time of each trigger event. For more information about trigger events, refer to Record and Retrieve Event Information.

Device-Specific Hardware Triggers

Many data acquisition devices possess the ability to accept a hardware trigger. Hardware triggers are processed directly by the hardware and can be either a digital signal or an analog signal. Hardware triggers are often used when speed is required because a hardware device can process an input signal much faster than software.

The device-specific hardware triggers are presented to you as additional property values. Hardware triggers for Measurement Computing and National Instruments devices are discussed below and in the properties.

Note that the available hardware trigger support depends on the board you are using. Refer to your hardware documentation for detailed information about its triggering capabilities.

Measurement Computing

When using Measurement Computing hardware, there are additional trigger types and trigger conditions available to you. These device-specific property values fall into two categories: hardware digital triggering and hardware analog triggering.

The device-specific trigger types and trigger conditions are described below and in the properties.

Analog Input TriggerType and TriggerCondition Values for MCC Hardware

TriggerType Value

TriggerCondition Value

Description

HwDigital

GateHigh

The trigger occurs as long as the digital signal is high.

GateLow

The trigger occurs as long as the digital signal is low.

TrigHigh

The trigger occurs when the digital signal is high.

TrigLow

The trigger occurs when the digital signal is low.

TrigPosEdge

The trigger occurs when the positive (rising) edge of the digital signal is detected.

{TrigNegEdge}

The trigger occurs when the negative (falling) edge of the digital signal is detected.

HwAnalog

{TrigAbove}

The trigger occurs when the analog signal makes a transition from below the specified value to above.

TrigBelow

The trigger occurs when the analog signal makes a transition from above the specified value to below.

GateNegHys

The trigger occurs when the analog signal is more than the specified high value. The acquisition stops if the analog signal is less than the specified low value.

GatePosHys

The trigger occurs when the analog signal is less than the specified low value. The acquisition stops if the analog signal is more than the specified high value.

GateAbove

The trigger occurs as long as the analog signal is more than the specified value.

GateBelow

The trigger occurs as long as the analog signal is less than the specified value.

GateInWindow

The trigger occurs as long as the analog signal is within the specified range of values.

GateOutWindow

The trigger occurs as long as the analog signal is outside the specified range of values.

Hardware Digital Triggering.  If TriggerType is HwDigital, the trigger is given by a digital (TTL) signal. For example, to trigger your acquisition when the positive edge of a digital signal is detected:

ai = analoginput('mcc',1);
addchannel(ai,0:7);
ai.TriggerType = HwDigital
ai.TriggerCondition = TrigPosEdge

The diagram below illustrates how you connect a digital trigger signal to a PCI-DAS1602/16 board. A/D External Trigger corresponds to pin 45.

Hardware Analog Triggering.  If TriggerType is HwAnalog, the trigger is given by an analog signal. For example, to trigger your acquisition when the trigger signal is between -4 volts and 4 volts:

ai = analoginput('mcc',1);
addchannel(ai,0:7);
ai.TriggerType = HwAnalog;
ai.TriggerCondition = GateInWindow;
ai.TriggerConditionValue = [-4.0 4.0];

The diagram below illustrates how you connect an analog trigger signal to a PCI-DAS1602/16 board. AI Ch 0-7 corresponds to pins 2-17, while Analog Trigger In corresponds to pin 43.

National Instruments

When using National Instruments (NI) hardware, there are additional trigger types and trigger conditions available to you. These device-specific property values fall into two categories: hardware digital triggering and hardware analog triggering.

The device-specific trigger types and trigger conditions are described below and in the properties.

Analog Input TriggerType and TriggerCondition Property Values for NI Hardware

TriggerType Value

TriggerCondition Value

Description

HwDigital

{NegativeEdge}

The trigger occurs when the negative (falling) edge of a digital signal is detected.

PositiveEdge

The trigger occurs when the positive (rising) edge of a digital signal is detected.

HwAnalogChannelor HwAnalogPin

{AboveHighLevel}

The trigger occurs when the analog signal is above the specified value.

BelowLowLevel

The trigger occurs when the analog signal is below the specified value.

HighHysteresis

The trigger occurs when the analog signal is greater than the specified high value with hysteresis given by the specified low value.

InsideRegion

The trigger occurs when the analog signal is inside the specified region.

LowHysteresis

The trigger occurs when the analog signal is less than the specified low value with hysteresis given by the specified high value.

Hardware Digital Triggering.  If TriggerType is HwDigital, the trigger occurs when the falling edge of a digital (TTL) signal is detected. The following example illustrates how to configure a hardware digital trigger.

ai = analoginput('nidaq','Dev1');
addchannel(ai,0:7);
ai.TriggerType = HwDigital')

The diagram below illustrates how you connect a digital trigger signal to an MIO-16E Series board. PFI0/TRIG1 corresponds to pin 11.

Hardware Analog Triggering.  If TriggerType is HwAnalogPin, the trigger is given by a low-range analog signal (typically between -10 and 10 volts) connected to the appropriate trigger pin. For example, to trigger your acquisition when the trigger signal is between -4 volts and 4 volts:

ai = analoginput('nidaq','Dev1');
addchannel(ai,0:7);
ai.TriggerType = HwAnalogPin)
ai = TriggerCondition = InsideRegion
ai.TriggerConditionValue = [-4.0 4.0]

If TriggerType is HwAnalogChannel, the trigger is given by an analog signal and the trigger channel is the first channel in the channel group (MATLAB index of one). The valid range of the analog trigger signal is given by the full-scale range of the trigger channel. The following example illustrates how to configure such a trigger where the trigger channel is assigned the descriptive name TrigChan and the default TriggerCondition property value is used.

ai = analoginput('nidaq','Dev1');
addchannel(ai,0:7);
ai.Channel(1),'ChannelName','TrigChan')
ai.TriggerChannel = ai.Channel(1)
ai.TriggerType = HwAnalogChannel
ai.TriggerConditionValue = 0.2

The diagram below illustrates how you can connect an analog trigger signal to an MIO-16E Series board.

Was this topic helpful?