Skip to main content

Simulate functions using a sequence diagram

Presentation​

This tutorial focuses on using the sequence diagram object in Virtual Bench to visualize and simulate dynamic system interactions. At its core, this virtual bench element represents lifelines, where flows appear dynamically during the simulation. In this tutorial, we will focus on the specific usage of the sequence diagram to represent the functions within the model that the user has previously created. For this we will go through the example of a Smart Home System.

Preparing the Model in Papyrus Designer​

First, the user must have designed a model within Papyrus Designer, carefully structured into multiple functions, with each function corresponding to a lifeline in the simulated sequence diagram. The Smart Home System is divided into the following functions:

  • A Smartphone App, for the User to control the system.
  • A Smart Hub, to supervise the orders and the connected objects.
  • A Light, connected to the smart hub.

Here is an example of the model you can aim for in this tutorial.

Sequence diagram of a user turning the light on through a smartphone app, whose command goes through the smart hub until the light.

Export functional flows​

In Papyrus Designer, the flows imported to the simulation are typically those that are interconnected with the external environment of the model, such as interactions between the system and external actors like the User. However, in our case, the flows of interest are interconnected internaly between the various functions within the system itself. These internal flows are not inherently accessible from outside the model, meaning additional steps are required to make them visible and usable within the simulation.

The following steps explain how to export functional flows using the modeling tool.

Step 1: Allocate Cross-Functional Flows in the WB Diagram​

  1. Open the WB Diagram in your model, located in the Function tab.

    In the Overview context, in the Function Tab, the SmartHomeWB architecture diagram is located under SequenceDiagramSmartHome > SmartHomeSystem > SmartHome.

  2. Right-click on the background of the diagram and select:
    Allocate Cross-Functional Flows to the Engineer.

    A right-click has opened a contextual menu in which one of the option is being selected: Allocate Cross-Functional Flows to the Engineer.

  3. Again, right-click on the background of the WB Diagram and choose: Edit > Update Connections.

    On the SmartHomeWB diagram, a right-click has opened a contextual menu in which Edit > Update Connections has been selected.

  4. It is recommended that you take the time to rearrange the connectors between elements.

    The SmartHomeWB diagram has been manually rearranged in order to distinguish each connector.
Note

The previous steps have created the connectors between simuOut and your functions.

Review and clean up the connections.

Please make sure that a function is not connected to both broadcast and simuOut. If it is the case, remove the broadcast connector.

Step 2: Update Connections in the Structure Diagram​

  1. Open the Structure Diagram in the Service tab.

    In the Overview context, in the Service Tab, the SmartHomeSystem Structure architecture diagram is located under SequenceDiagramSmartHome > SmartHomeSystem > SmartHomeSystem.

  2. Here again, Right-click on the background and select:
    Edit > Update Connections.

    On the SmartHomeSystem Structure's diagram, a right-click has opened a contextual menu in which Edit > Update Connections has been selected.

  3. Rearrange the diagram:

    The SmartHomeSystem Structure diagram has been manually rearranged in order to distinguish each connector.
Review and clean up the connections.

As before, review and delete extra connections to ensure no connection exists between:

  • SimOut and OutputCustomer/OutputEnvironment.
  • Broadcast and OutputEngineer.

Step 3: Update Connections in the Project Structure​

  1. In the Model Explorer, navigate to the Project Structure.

    In the Model Explorer, the Project Structure architecture diagram is located under ModelPackage > ProjectPackage > ProductPackage > Simulation > ProjectClass > ProjectStructure

  2. One last time, Right-click on the diagram's background and choose: Edit > Update Connections.

    On the Project Structure's diagram, a right-click has opened a contextual menu in which Edit > Update Connections has been selected.

  3. Rearrange the diagram:

    The Project Structure diagram has been manually rearranged in order to distinguish each connector.
Review and clean up the connections.

As before, review and delete extra connections:

  • Connections from the system to itsUser or itsEnvironment should NOT link to itsEngineer.
  • Ensure OutputEngineer only connects to itsEngineer.

Step 4: Update Model Mappings​

  1. In the Model Explorer, right-click on the first element (ModelPackage) and select:
    Migration > Update Model Mappings. In Model Explorer, a right-click on ModelPackage will show a contextual menu in which you can access to Migration > Update Model Mappings.

Step 5: Export Flows Summaries​

This step will be useful later as it will create a summary of the interfaces of each function. It will help Virtual Bench understand how the flows communicate to one function to another.

  1. To export SmartHomeBB and other functions flows:

    • In the Service tab, right-click and choose Navigate to locate SmartHomeBB in the Model Explorer.

      In Service Tab, SmartHomeBB is available under SequenceDiagramSmartHome > SmartHomeSystem > SmartHome > SmartHomeBB, and a right-click on it shows the following option: Navigate > Go to element (SmartHomeBB) > Model Explorer.

    • Now switch to the Model Explorer, the SmartHomeBB Service Class should be selected, Right-click on it and select:
      Generate > Interface Summary File.

      In Model Explorer, a right-click on SmartHomeBB allows to select the following option: Generate > Interface Summary File.

    This generates CSV files summarizing the flows at BB boundaries. These files will be available in the Export folder within your workspace.

  2. Repeat the process for the functions in the Function tab.

    • In the Function tab, find a function to start with, right-click and choose Navigate as we did earlier to locate the function in the Model Explorer.
    In Service Tab, SmarphoneApp, SmartHub and Light, are available in their associated subfolder of the same name.
    • Now switch to the Model Explorer, the Function Class should be selected, Right-click on it and select:
      Generate > Interface Summary File.
    • Don't forget to repeat the process for each function.

Generate the XML file.
By now, in your project's location, under the export folder, you should have generated a .xml file, a .csv file for your system's service, and a .csv file for each of the functions.

List of the exported files: SmartHomeSystem.xml ; SmartHome.csv ; Light .csv ; SmartHub .csv ; SmartphoneApp .csv.
Warning

If you are working on the white box or function level of your model as in this tutorial, make sure that your executable will generate using the white box level, and not the black box / service level. Follow this link to learn more about switching from white box to black box.

Several steps are described sequentially, 1. click on Service Tab ; 2. Open the Structure Diagram (Here, SmartHomeSystem Structure) ; 3. Select the service in the diagram (Here, SmartHome) ; 4. Open the Properties Tab ; 5. Select the three dots next to the Type Parameter (Here indicating SmartHomeWB before edition) ; 6. Select the BB (black box) version of the service (Here, SmartHomeBB) ; 7. Click OK.

Generate the executable.

Creating a Simulation in Virtual Bench​

With your model ready, you can transition to the simulation in Virtual Bench.

Creating a New Executable in Virtual Bench​

Follow these steps to create a new executable in Virtual Bench and import the necessary data.

Step 1: Create a New Executable​

Open Virtual Bench and create a new executable:

While the Project tab is opened, a small '+' sign is highlighted in front of the Executables folder.
  • Name the new executable (e.g. Smart Home Executable), and specify the path to the .exe file you previously generated out of your model (if you plan on using the launcher).
  • Import the previously generated XML file (Here SmartHomeSystem.xml).

Step 2: Import Generated CSV Files​

One by one, import each of the CSV files generated in the previous steps. To import, click the import icon next to your executable. A popup should appear, asking for a .csv file.

An import icon is available on the Virtual Bench executable folder.
Good to know

These CSV files contain the interface summaries and will populate some of the source and target functions of the executable’s flows. It will also automatically create the associated Model Parts, that represents the different lifelines or functions of your model, within Virtual Bench.

Don't forget to repeat the process for each generated CSV file.

Step 3: Complete Missing Flow Configurations​

  1. Create the missing lifelines.

    Among the different Model Parts that the .csv files have created, the actors of the system are still missing because they are not part of the system. In our case, the missing actor is the User. We will then have to create its Model Part manually.

    • Go to your Virtual Bench executable sub-folder called Model Parts. By extending the folder, you should see that the model parts associated with your internal functions (and even the single internal service) are already created.

    • Click on the Model Parts '+' icon to add a new Model Part.

      In the Smart Home Executable, one of the folder called Model Parts contains Light ; SmartHub ; SmartphoneApp ; SmartHomeBB. The '+' icon next to the Model Parts folder is highlighted.

    • A new Model Part Configuration page should appear. Find an appropriate name (Here User). And most importantly, set the Type to External. Click Save.

  2. Review the flows in the executable:

    • Some flows will already have their source and target functions populated. This will apply to those which only depends on internal Model Parts such as flows connecting two internal functions.

    • However, flows that depend on an external source or target will need manual adjustment. In our example, the User (external actor) interacts with the system through the SmartphoneApp. The flow request_to_turn_the_light_on sent by the User will then not be entirely configured.

    • Once you have identified the flows that need manual adjustments, click on the configuration wheel next to the flow.

      In the Smart Home Executable, in the Flows folders, a wheel icon next to the flow request_to_turn_the_light_on is highlighted.

    • Now manually select the User as a model part source.

      In the flow configuration of request_to_turn_the_light_on, the User is selected as a model part source.

Creating a New Scenario in Virtual Bench​

Create a new scenario in Virtual Bench.

Before creating and using the sequence diagram, you will need to instantiate the previously created model parts in your scenario.

Step 1: Create a New Websocket​

In the Scenario tab, in the Websockets folder, create a new websocket using the new Smart Home Executable:

In the websocket creation popup, the selected executable is the Smart Home Executable, the name of the Websocket is SmartHomeWS, and its port has been set by default to 9002.

Step 2: Add model part instances​

  1. In the new Smart Home Websocket, you will find a folder called "Model part instances", click on the '+' icon next to it.

    In the Scenario tab, in the Websockets folder, under the new SmartHomeWS Websocket, there is an add icon next to the Model part instances folder

  2. From there, you can choose a model part, and click Save.

  3. Repeat this step, as many time as there are Model Part to instantiate.

  4. You should now see all the instances under the Model part instances folder, as such:

    In Model part instances, we can see the following instances: User, SmartHomeBB, SmartphoneApp, SmartHub, and Light.
Note

Among the instantiated model parts, there is the SmartHomeBB, which is the Black Box version of the model. This will not be useful if you only want the function visualisation, as it is the case in the following steps of the tutorial. However, it can still be useful if you later want to add a way to represent the model without the internal functions.

Step 3: Set up the Sequence Diagram​

In our case, we will be configuring the Sequence Diagram, to visualize the internal flows of our model.

  1. In any HMI context, in Edit Mode, add a Sequence Diagram by drag & dropping the element. The sequence diagram should not be configured and should display "No Selected Life Line".

    In Edit Mode, in an HMI context, a sequence diagram has been dragged and dropped into the scenario zone. The sequence diagram shows a unique empty lifeline saying No Selected Life Line.

  2. By selecting the element or double-clicking on it, open the element tab to the right-hand side. Open the Diagram flows tab, by clicking on it.

    Among all the icons of the element tab, there is an icon called Diagram Flows, represented by a double edged arrow.

  3. Except for the SmartHomeBB instance, select all model part instances in the order you want them to appear from left to right.

    Note

    You can still change the order later by right clicking on the sequence diagram, and choosing the "Edit and sort model parts/flows" option.

  4. Automatically, you should see all the eligible flows, relative to their sources and targets. If you want them in the simulation, select them too. In our case we will be selecting them all.

    All model part instances are selected, excepted for SmartHomeBB, and all the eligible flows are selected.

  5. Click "Save", this should update the sequence diagram.

Step 4: Run the scenario​

  1. Create a way to trigger the first flows of your scenario. In our case, the User request should be the initial trigger. Create a button to simulate the user input, along with the associated mapping.

    A red button, whose text is User Request

  2. Run the scenario. After the initial request of the User, the scenario should develop and display step by step the different flows.

    The sequence diagram displays three arrows, that represent a signal transmission between the user and the app, then between the app and the hub, and finally between the hub and the light.

Conclusion​

By following this tutorial, you’ve learned how to visualize and simulate dynamic system interactions at a function level, using sequence diagrams in Virtual Bench. You’ve successfully prepared your model in Papyrus Designer, exported the necessary flows, and set up the corresponding executable and CSV files in Virtual Bench. After configuring your scenario and flows, you were able to create a sequence diagram that visualizes how functions within your Smart Home System interact. You should now be able to use this knowledge with more complex sequences.