Main Content

Simulink.sdi.addTrigger

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

Since R2020b

collapse all in page

    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.

    example

    Examples

    collapse all

    Open Live Script

    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

    collapse all

    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.

    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.

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

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

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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.

    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

    See Also

    Objects

    Functions

    Topics