Simulink.sdi.addTrigger

Add trigger to signal to control display updates in the Simulation Data Inspector

Since R2020b

Syntax

Simulink.sdi.addTrigger(sig)

Simulink.sdi.addTrigger(sig,Name,Value)

Description

Simulink.sdi.addTrigger(sig) adds a rising-edge trigger using normal mode and auto-level to the Simulink.sdi.Signal object, sig. The trigger determines when plots in the Simulation Data Inspector update to display new data for streaming signals.

Simulink.sdi.addTrigger(sig,Name,Value) adds trigger to the specified signal with trigger settings specified by one or more name-value pair arguments. For example, 'Mode','Normal' configures normal mode behavior for the trigger. Triggers in the Simulation Data Inspector behave the same as triggers in the Scope block. For details regarding trigger types and settings, see Scope Triggers Panel.

Examples

Programmatically Configure Triggers in the Simulation Data Inspector

Add a trigger to a signal in the Simulation Data Inspector to specify criteria that determine when to update plots to display fresh data. Triggers can allow you to capture transient signal behavior and can help stabilize the display of periodic signals so you can take measurements.

Simulate the Triggers model. Data in the model logs to the Simulation Data Inspector.

open_system('Triggers');
out = sim('Triggers');

Then, add a trigger to the Pulse signal. Configure the trigger as a falling-edge trigger with a threshold of 0.5.

trigRun = Simulink.sdi.getCurrentSimulationRun('Triggers');
pulseSig = getSignalsByName(trigRun,'Pulse');
Simulink.sdi.addTrigger(pulseSig,'Type','Edge','Level',0.5);

You can verify that the trigger was added and configured correctly by opening the Simulation Data Inspector using Simulink.sdi.view and clicking the trigger icon next to the Pulse signal to check the configuration. You can also use the Simulink.sdi.getTrigger function to check which signal is used to generate trigger events and the trigger configuration.

[sig,trigOpts] = Simulink.sdi.getTrigger;

sig.Name

ans = 
'Pulse'

trigOpts

trigOpts = struct with fields:
                       Mode: 'Auto'
                       Type: 'Edge'
                   Position: 0.5000
                      Delay: 0
    SourceChannelComplexity: 'Scalar'
                   Polarity: 'Positive'
                  AutoLevel: 1
                      Level: 0.5000
                 UpperLevel: 0
                 LowerLevel: 4.6673e-62
                 Hysteresis: 0
                    MinTime: 0
                    MaxTime: Inf
                    Timeout: 0
                    Holdoff: 0

When you do not want to use a trigger to control when the Simulation Data Inspector updates the plots with fresh data, you can remove the trigger using the Simulink.sdi.removeTrigger function.

Simulink.sdi.removeTrigger

You can verify that the trigger was removed in the Simulation Data Inspector UI or using the Simulink.sdi.getTrigger function. The Simulink.sdi.getTrigger function returns an empty array of Simulink.sdi.Signal objects when no trigger is configured in the Simulation Data Inspector.

sig = Simulink.sdi.getTrigger;
size(sig)

ans = 1×2

     0     0

Input Arguments

sig — Signal used to detect trigger events

Simulink.sdi.Signal object

Signal used to detect trigger events, specified as a Simulink.sdi.Signal object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Type','PulseWidth','Polarity','Falling' configures a falling-edge, auto-leveled trigger in auto mode.

Mode — When display updates in response to trigger event

Auto (default) | Normal | Once

When display updates in response to trigger event, specified as the comma-separated pair consisting of 'Mode' and one of these options:

• Auto — Plots update in response to each trigger event, and the plots update if no trigger event occurs for the duration of time range displayed.

• Normal — Plots update in response to each trigger event.

• Once — Plots update in response to the first trigger event. You can manually rearm the trigger using the Simulation Data Inspector.

Example: 'Mode','Normal' configures the trigger to use normal mode.

Position — Where trigger event appears in plot

50 (default) | numeric percentage

Where trigger event appears in plot, specified as the comma-separated pair consisting of 'Position' and a numeric percentage. By default, the trigger event appears in the middle of the plot, with a position of 0.5, or at the 50% position within the time span.

Example: 'Position',.3 positions the trigger event at the 30% point within the time span.

Type — Type of trigger to add to signal

Edge (default) | PulseWidth | Transition | Runt | Window | Timeout

Type of trigger to add to signal, specified as the comma-separated pair consisting of 'Type' and one of these options:

• Edge — Trigger when the signal crosses a threshold.

• PulseWidth — Trigger when the signal crosses twice between a low threshold and high threshold within a specified time.

• Transition — Trigger when the signal crosses a high threshold and a low threshold within a specified time.

• Runt — Trigger when a signal crosses a low threshold or a high threshold twice within a specified time.

• Window — Trigger when a signal stays within or outside a range defined by a high threshold and a low threshold for a specified time.

• Timeout — Trigger when a signal stays above or below a threshold longer than a specified time.

For details regarding options for each type of trigger, see Scope Triggers Panel.

Example: 'Type','PulseWidth' configures a pulse width trigger.

Polarity — Direction of signal value change that causes trigger event

valid polarity for trigger type

Direction of signal value change that causes trigger event, specified as the comma-separated pair consisting of 'Polarity' and a valid polarity for the trigger type.

Trigger Type	Polarity Options
Edge	Rising — Trigger when the signal crosses the threshold while increasing in value. Falling — Trigger when the signal crosses the threshold while decreasing in value. Either — Trigger when the signal crosses the threshold while increasing or decreasing in value.
PulseWidth	Positive — Trigger on a rising pulse when the signal crosses the low threshold for a second time. Negative — Trigger on a falling pulse when the signal crosses the high threshold for a second time. Either — Trigger on both rising and falling pulses.
Transition	RiseTime — Trigger when the signal increases to cross from the low to the high threshold within the specified time. FallTime — Trigger when the signal decreases to cross from the high threshold to the low threshold within the specified time. Either — Trigger when the signal increases or decreases to cross the low and high thresholds within the specified time.
Runt	Positive — Trigger on a rising pulse when the signal crosses the low threshold for a second time without crossing the high threshold. Negative — Trigger on a falling pulse when the signal crosses the high threshold for a second time without crossing the low threshold. Either — Trigger on rising or falling pulses that stay within the specified value thresholds.
Window	Inside — Trigger when a signal stays within the specified value range for a duration between the MinTime and MaxTime. The trigger event occurs when the signal exits the specified value range. Outside — Trigger when a signal is outside the specified value range for a duration between the MinTime and the MaxTime. The trigger event occurs when the signal reenters the specified value range. Either — Trigger when the signal is inside or outside of the specified value range for a duration between the MinTime and the MaxTime.
Timeout	Rising — Trigger when the signal remains above the threshold for longer than the specified time. Falling — Trigger when the signal remains below the threshold for longer than the specified time. Either — Trigger when the signal remains either above or below the threshold for longer than the specified time.

Example: 'Type','Edge','Polarity','Rising' configures a rising-edge trigger.

AutoLevel — Whether to automatically determine trigger levels

true or 1 (default) | false or 0

Whether to automatically determine trigger levels, specified as the comma-separated pair consisting of 'AutoLevel' and true or false.

When you want to specify thresholds for the trigger, specify 'AutoLevel' as false.

Example: 'AutoLevel',false configures a trigger to use a user-specified level.

Level — Threshold for trigger events

numeric scalar

Threshold for trigger events, specified as the comma-separated pair consisting of 'Level' and a numeric scalar.

You can only specify the 'Level' name-value pair when you specify the 'Type' name-value pair as 'Edge' or 'Timeout'.

Example: 'Type','Timeout','Level','0.5' configures a timeout trigger with a threshold of 0.5.

Hysteresis — Signal value change required around threshold to cause trigger event

numeric scalar

Signal value change required around threshold to cause trigger event, specified as the comma-separated pair consisting of 'Hysteresis' and a numeric scalar. Specifying a hysteresis for the trigger results in noise rejection for trigger events.

You can only specify the 'Hysteresis' name-value pair when you specify the 'Type' name-value pair as 'Edge' or 'Timeout'.

Example: 'Type','Timeout','Hysteresis','0.05' configures a timeout trigger that requires the signal value to change by more than 0.05 around the threshold to cause a trigger event.

UpperLevel — Upper threshold for trigger event

numeric scalar

Upper threshold for trigger event, specified as the comma-separated pair consisting of 'UpperLevel' and a numeric scalar.

You can only specify the 'UpperLevel' name-value pair when you specify the 'Type' name-value pair as 'PulseWidth', 'Transition', 'Runt', or 'Window'.

Example: 'Type','PulseWidth','UpperLevel','0.9' configures a pulse width trigger with an upper threshold of 0.9.

LowerLevel — Lower threshold for trigger event

numeric scalar

Lower threshold for trigger event, specified as the comma-separated pair consisting of 'LowerLevel' and a numeric scalar.

You can only specify the 'LowerLevel' name-value pair when you specify the 'Type' name-value pair as 'PulseWidth', 'Transition', 'Runt', or 'Window'.

Example: 'Type','PulseWidth','LowerLevel','0.1' configures a pulse width trigger with a lower threshold of 0.1.

MinTime — Lower time limit for trigger event

numeric scalar

Lower time limit for trigger event, specified as the comma-separated pair consisting of 'MinTime' and a numeric scalar. You can only specify the 'MinTime' name-value pair when you specify the 'Type' name-value pair as 'PulseWidth', 'Transition', 'Runt', or 'Window'. The significance of the lower time limit depends on the type of trigger.

• 'PulseWidth' — Minimum pulse width for trigger event.

• 'Transition' — Minimum rise or fall time for trigger event.

• 'Runt' — Minimum pulse width for trigger event.

• 'Window' — Minimum time spent within or outside value range for trigger event.

Example: 'Type','PulseWidth','MinTime','0.1' configures a pulse width trigger with a minimum pulse width of 100ms.

MaxTime — Upper time limit for trigger event

numeric scalar

Upper time limit for trigger event, specified as the comma-separated pair consisting of 'MaxTime' and a numeric scalar. You can only specify the 'MaxTime' name-value pair when you specify the 'Type' name-value pair as 'PulseWidth', 'Transition', 'Runt', or 'Window'. The significance of the upper time limit depends on the type of trigger.

• 'PulseWidth' — Maximum pulse width for trigger event.

• 'Transition' — Maximum rise or fall time for trigger event.

• 'Runt' — Maximum pulse width for trigger event.

• 'Window' — Maximum time spent within or outside value range for trigger event.

Example: 'Type','PulseWidth','MaxTime','0.5' configures a pulse width trigger with a maximum pulse width of 500ms.

Timeout — Time threshold for timeout trigger

numeric scalar

Time threshold for timeout trigger, specified as the comma-separated pair consisting of 'Timeout' and a numeric scalar.

You can only specify the 'Timeout' name-value pair when you specify the 'Type' name-value pair as 'Timeout'.

Example: 'Type','Timeout','Timeout','0.5' configures a timeout trigger that causes an event when a signal is above or below the value threshold for longer than 500ms.

Delay — Trigger event offset from trigger position

numeric scalar

Trigger event offset from trigger position, specified as the comma-separated pair consisting of 'Delay' and a numeric scalar.

Example: 'Type','Edge','Delay','0.1' configures an edge trigger where the trigger position marker is displayed 100ms after the trigger event.

Holdoff — Minimum time between trigger events

numeric scalar

Minimum time between trigger events, specified as the comma-separated pair consisting of 'Holdoff' and a numeric scalar. After a trigger event, the display does not update again for at least the holdoff time.

Example: 'Type','Edge','Holdoff','1' configures an edge trigger with a holdoff of 1s. After a trigger event, the display does not update for at least 1s.

Alternative Functionality

You can add a trigger to a signal and configure the trigger options using the Simulation Data Inspector UI. For details, see Control Display of Streaming Data Using Triggers.

Version History

Introduced in R2020b