Main Content

addMessage

Add message to interaction between lifelines

Since R2024b

    Description

    message = addMessage(operand,sourceLifeline,sourcePort,destLifeline,destPort,label) adds a message between the lifelines specified by sourceLifeline and destinationLifeline within the operand specified by operand, where sourcePort and destPort are the ports on the corresponding components. The message message is also assigned the label message label.

    example

    message = addMessage(___,After=existingElement) specifies options using one or more name-value arguments in addition to the input arguments in previous syntaxes. For example, to add the fragment fragment after an existing fragment, set existingElement to a valid fragment object.

    example

    Examples

    collapse all

    Create a sequence diagram programmatically to describe the scenario of a pedestrian crossing the street at an intersection with traffic lights.

    To learn more about sequence diagrams, see Author Sequence Diagrams Interactively.

    Open Traffic Light Example

    Load the TLExample architecture model.

    model = systemcomposer.openModel('TLExample');

    TLExample architecture model with various components.

    Create a new sequence diagram named 'InhibitCopy'.

    diagram = model.addInteraction('InhibitCopy');

    Add Lifelines

    Add a lifeline for each component in the architecture.

    sourceLifeline = diagram.addLifeline('TLExample/source');
    pollerLifeline = diagram.addLifeline('TLExample/poller');
    switchLifeline = diagram.addLifeline('TLExample/switch');
    lampLifeline = diagram.addLifeline('TLExample/lampController');
    controllerLifeline = diagram.addLifeline('TLExample/controller');

    Get the root fragment and root operand of the interaction.

    rootFragment = diagram.RootFragment;
    rootOperand = rootFragment.Operands(1);

    Add Messages and Fragments

    Add two messages to the root operand.

    sourceToPollerMsg = rootOperand.addMessage(sourceLifeline, "switchout", pollerLifeline, "sw", "rising(sw-1){sw==1}");
    pollerToSwitchMsg = rootOperand.addMessage(pollerLifeline, "switchEvent", switchLifeline, "switchEvent", "switchEvent{switchEvent==1}");

    Add an alternative fragment to the root operand.

    altFrag = rootOperand.addFragment('Alt');

    Specify the guard expressions for each operand of the alternative fragment.

    op1 = altFrag.Operands(1);
    op1.Guard = "switch/inhibit==0";
    op2 = altFrag.addOperand("switch/inhibit==1");

    Add two messages to the first operand of the alternative fragment.

    switchToLampControllerMsg1 = op1.addMessage(switchLifeline, "lampColor", lampLifeline, "switchPed", "switchPed{switchPed==1}");
    switchToControllerMsg = op1.addMessage(switchLifeline, "switchPush", controllerLifeline, "pedRequest", "pedRequest");

    Add a message to the second operand of the alternative fragment.

    switchToLampControllerMsg2 = op2.addMessage(switchLifeline, "lampColor", lampLifeline, "switchPed", "switchPed{switchPed==2}");

    Add Duration Constraints

    Add a duration constraint between the two messages in the first operand of the alternative fragment.

    startEvent = switchToLampControllerMsg1.End;
    endEvent = switchToControllerMsg.End;
    expression = "t > 12msec";
    durationConstraint = diagram.addDurationConstraint(startEvent, endEvent, expression);

    Open Sequence Diagram

    Open the newly created sequence diagram.

    open(diagram);

    Newly created sequence diagram called 'InhibitCopy'.

    Input Arguments

    collapse all

    Operand, specified as a systemcomposer.interaction.Operand object.

    Source lifeline, specified as a systemcomposer.interaction.Lifeline object.

    Example: "source"

    Source port, specified as a character vector or string.

    Data Types: char | string

    Destination lifeline, specified as a systemcomposer.interaction.Lifeline object.

    Example: "dest"

    Destination port, specified as a character vector or string.

    Data Types: char | string

    Message label specified as a character vector or string.

    A message label has a trigger, an optional guard, and an optional constraint in the form of trigger[guard]{constraint}. trigger represents the identifying event for this message. guard represents an additional condition to determine whether the message occurs. constraint is an expression that is expected to be true when this message occurs.

    • In signal events, the trigger follows this format: direction(signal [+|-] value), which specifies a triggering edge with a direction and an expression. The direction can be:

      • Rising — The edge expression is rising from strictly below zero to a value equal to or greater than zero.

      • Falling — The edge expression is falling from strictly above zero.

      • Crossing — The edge expression either rising or falling past zero.

    • In message events, the trigger is in the format port, which specifies the name of the input message port and represents the arrival of a message.

    • A guard in square brackets on the message label is a MATLAB® Boolean expression that is an additional condition to determine whether the message occurs. Evaluation of the guard only occurs once the software detects a valid trigger. During execution, the sequence diagram waits to proceed to the next message until the guard expression evaluates to true.

    • A constraint in curly brackets on the message label is a MATLAB Boolean expression that specifies an expected value of inputs to the destination lifeline. During execution, the evaluation of the constraint determines whether the sequence diagram shows a pass or fail for that message.

    Example: "rising(sw-1)"

    Data Types: char | string

    Existing element in sequence diagram after which to place new fragment, specified as one of these objects:

    Output Arguments

    collapse all

    Added message, returned as a systemcomposer.interaction.Message object.

    More About

    collapse all

    Version History

    Introduced in R2024b