Store 
| Products & Services | Solutions | Academia | Support | User Community | Company |
 |
Download Product Updates | | |  |
Get Pricing | | | |
Trial Software |
| Documentation → Data Acquisition Toolbox |
| Products & Services | Solutions | Academia | Support | User Community | Company |
|
Download Product Updates | | | |
Get Pricing | | | |
Trial Software |
| Documentation → Data Acquisition Toolbox |
| Contents | Index |
| Learn more about Data Acquisition Toolbox |
| On this page… |
|---|
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 |
|---|---|
Indicate the absolute time of the first trigger. | |
Specify that the hardware device starts when a manual trigger is issued. | |
Specify the M-file callback function to execute when a trigger occurs. | |
Specify the channel serving as the trigger source. | |
Specify the condition that must be satisfied before a trigger executes. | |
Specify one or more voltage values that must be satisfied before a trigger executes. | |
Specify the delay value for data logging. | |
Specify the units in which trigger delay data is measured. | |
Specify the number of additional times the trigger executes. | |
Indicate the number of triggers that execute. | |
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.
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 5-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 reference pages in Base Properties — Alphabetical List 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.
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 Repeating Triggers.
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.
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.
This example demonstrates 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.
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);Add channels — Add one hardware channel to AIVoice.
chan = addchannel(AIVoice,1); %chan = addchannel(AIVoice,0); % For NI and MCC
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; % two second acquisition set(AIVoice,'SampleRate',44100) ActualRate = get(AIVoice,'SampleRate'); set(AIVoice,'SamplesPerTrigger',ActualRate*duration) set(AIVoice,'TriggerChannel',chan) set(AIVoice,'TriggerType','Software') set(AIVoice,'TriggerCondition','Rising') set(AIVoice,'TriggerConditionValue',0.2)
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 onClean 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 =
87200For an analog input trigger to occur, you must follow these steps:
Issue the start function.
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 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.
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. |
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.
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.
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);Add channels — Add one hardware channel to AIVoice.
chan = addchannel(AIVoice,1); %chan = addchannel(AIVoice,0); % For NI and MCC
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 set(AIVoice,'SampleRate',44100) ActualRate = get(AIVoice,'SampleRate'); set(AIVoice,'SamplesPerTrigger',ActualRate*duration) set(AIVoice,'TriggerChannel',chan) set(AIVoice,'TriggerType','Software') set(AIVoice,'TriggerCondition','Rising') set(AIVoice,'TriggerConditionValue',0.2) set(AIVoice,'TriggerDelayUnits','Samples') set(AIVoice,'TriggerDelay',-500)
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 onClean 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.
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.
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.
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);Add channels — Add one hardware channel to AIVoice.
chan = addchannel(AIVoice,1); %chan = addchannel(AIVoice,0); % For NI and MCC
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 set(AIVoice,'SampleRate',44100) ActualRate = get(AIVoice,'SampleRate'); set(AIVoice,'Timeout',5) set(AIVoice,'SamplesPerTrigger',ActualRate*duration) set(AIVoice,'TriggerChannel',chan) set(AIVoice,'TriggerType','Software') set(AIVoice,'TriggerCondition','Rising') set(AIVoice,'TriggerConditionValue',0.2) set(AIVoice,'TriggerRepeat',1)
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')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 Extracting 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 onThe 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 =
22051With this information, you can find the relative time for the second trigger.
t2time = t(index+1)
t2time =
0.5980You 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);
set(ai,'TriggerRepeat',4);
start(ai)TriggersExecuted returns the number of triggers executed.
ai.TriggersExecuted
ans =
5showdaqevents 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 Recording and Retrieving Event Information.
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.0041To 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:4You can also use the showdaqevents function to return the absolute time of each trigger event. For more information about trigger events, refer to Recording and Retrieving Event Information.
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 Computingand National Instruments devices are discussed below and in Base Properties — Alphabetical List.
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.
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 Base Properties — Alphabetical List.
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);
set(ai,'TriggerType','HwDigital')
set(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);
set(ai,'TriggerType','HwAnalog');
set(ai,'TriggerCondition','GateInWindow');
set(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.
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 Base Properties — Alphabetical List.
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);
set(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);
set(ai,'TriggerType','HwAnalogPin')
set(ai,'TriggerCondition','InsideRegion')
set(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);
set(ai.Channel(1),'ChannelName','TrigChan')
set(ai,'TriggerChannel',ai.Channel(1))
set(ai,'TriggerType','HwAnalogChannel')
set(ai,'TriggerConditionValue',0.2)The diagram below illustrates how you can connect an analog trigger signal to an MIO-16E Series board.
 | Managing Acquired Data | Events and Callbacks |  |
Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.
| © 1984-2009- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |
