Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Papyrus-RT/User/User Guide/Getting Started

PapyrusForRealTime-Logo-Icon.png


Getting Started with Papyrus for RealTime v0.9


Introduction

This tutorial will show the creation of a simple model using Papyrus for RealTime version 0.9.0 (based on Eclipse Neon).

Warning2.png
Installation
As a precondition to going through this tutorial, you must have Papyrus for Real Time installed and the tool open. Please see the Papyrus-RT User installation page for information on installing Papyrus for Real Time.


Note.png
Linux
The instructions in this tutorial are illustrated using Linux. Steps and images may differ slightly if the installation is done on a different operating system (both Windows and Mac OS are supported for developing models). Some of these differences have been indicated when known, but some may also be missing.


Note.png
PDF Version
A PDF version of this tutorial is also available.


This exercise will show the creation of a project and model and how UML-RT concepts can be used to easily create the application's structure and behavior.

At its base, a UML-RT model consists of capsules (UML active classes with composite structure) that communicate through ports defined by protocols (collaboration specifications) These protocols specify the messages (signals) that can be exchanged between capsules, as well as their payloads. Hierarchical state machines are used to represent the behavior of capsules, where transitions between states are triggered by messages received on the capsule's ports.

If you are not familiar with UML-RT and want to know a bit more, you should take a look at the initial Papyrus-RT Overview page. Note that this page reflects an early version of Papyrus-RT and visual elements shown on that page may not completely match those of this tutorial. The concepts, however, ar the same).

The model that will be created as part of this tutorial is a simple "PingPong" model. In this model, implemented using UML-RT, two players will be playing an eternal game of ping pong.

It is a very simple model that will show how a UML-RT model is constructed. Each player will be portrayed using UML-RT capsules and a UML-RT protocol will be used to define how the ball is exchanged between players through ports on each player capsule.

Create a Papyrus for Real Time Project containing a UML-RT model.

Papyrus for Real Time is a Domain-Specific Modeling Language (DSML) tool based on Papyrus. We will use the Papyrus Project creation wizard to create a project configured for Papyrus for Real Time.

Workspace

After starting Papyrus-RT and dismissing the welcome screen, you are presented with the Papyrus-RT workspace

GSwPRT09Workspace.png

Select File -> New -> Papyrus Project

GSwPRT09NewPapyrusProject.png

Selecting the language to be used for the model

In the resulting dialog:

  1. Select UML-RT as the language for the model that will be created by clicking on the radio button next to the UML-RT icon
  2. Click on [Next].

GSwPRT09SelectModelLanguage.png

Define the project

You can now define the project's name and its location, as well as the name of the model file that will be created.

  1. Enter the name for the project. This project can hold multiple artefacts and will contain a Papyrus model by default. For this tutorial, we will use the name "PingPong".
  2. By default, the project will be created in the current workspace. You can, however, select an alternative location if, for example, you wish to store your project under source control.
  3. Enter "PingPong" as the model file name.
  4. Click on [Next]

GSwPRT09DefineProject.png

Provide model initialization information

There is more information that can be provided to create a useful model.

  1. The "Root model element" is a representation of the model itself. For this tutorial, and for consistency, we will name it "PingPong".
  2. The wizard let's you select a template of the model you are creating, select "UML-RT for C++"
  3. There is no more information to add on this wizard page as they are already set in the wizard. Click [Finish] to create the project and its contained model.

Note that there are three templates that you can select in the v0.9 version of Papyrus-RT:

  1. UML-RT for structural modelling: only provides support for capsule, ports, and protocol. Capsule state machines cannot be created when this template is used.
  2. UML-RT basic: provides all UML-RT capabilities, including the creation of capsule state machines to express the behaviour of capsules. However, no target language is set for code generation.
  3. UML-RT for C++: provides all the capabilities to create UML-RT models that can generate C++ code. This includes the the UML-RT RTS and C++ primitive types libraries.

Note that these templates build on top of each other, so even if you select one of the first two templates, you can still add the profiles and libraries to get to the "UML-RT for C++" configuration

GSwPRT09ModelInit.png

Project and Model Created

You now have an empty model ready to be populated!

GSwPRT09ProjectModelCreated.png

Note.png
Tip:Code Snippet View
Although not use as part of this tutorial, many Papyrus-RT users like to have the Code Snippet View displayed along with the Properties View. This can be accomplished by dragging the Code Snippet View to the right of the Properties View.


Our project: PingPong

For this tutorial, we will be creating a simple model of a ping pong game, with two players.

The system will consist of two capsules ("active classes) that will communicate to show whose turn it is to hit the ball. Because the system is run by computer, no errors will be made playing, so you will have to kill the executable when testing, else it will run forever...

So let's get started!

Create a protocol

Let's start by determining how the PingPong ball will go from one player to the other. To do this, we can think of the ping pong ball as a message to the other player to which they need to reply (hit the ball back). In UML-RT, the structure that governs the messages that can be exchanged between entities (players in this case) is a protocol.

Protocols define protocol messages that define how messages can be sent and received between model elements (called "Capsules" in UML-RT - more on that later). These protocol messages can be incoming, outgoing, or symmetrical (i.e., both ingoing and outgoing).

In the case of protocols that are not purely symmetric, i.e., that have either or both incoming and outgoing messages, there is also a need for the concept of conjugation, i.e., of reversing the role of the protocol, a concept that will be addressed further when used later in this tutorial.

In the case of this Getting Started tutorial, we could create a symmetric protocol where there would be a single symmetrical protocol message called, for example, "ball". However, to better explore the concept of protocols, we will define our "PingPong" protocol to have one outgoing protocol message called "ping" and one incoming protocol message called "pong".

Create the protocol

The first step is to create the protocol itself.

  1. Right-click on the "PingPong" model in the Model Explorer and select "New UML-RT Child > Protocol"
  2. The name of the protocol is highlighted, name the protocol "PingPongProtocol" and hit return.

You can also see the protocol and its messages in the Properties view.

You now have a "protocol" in the Model Explorer.

GSwPRT09CreateProtocol 1.png GSwPRT09CreateProtocol 2.png

Add protocol messages to the protocol

As mentioned previously, a protocol may contain many different "protocol messages" that specify "operations" and their associated data.

Our protocol will "ping" its opponent and, in return, will respond to a "pong". This tells us that there will be a "ping" outgoing protocol message and a "pong" incoming protocol message.

Tip: Protocols should be defined from the client's perspective. In practice, this means that the provider of the service defined by the protocol will have their ports conjugated and the client's ports will by un-conjugated. This makes sense as there will typically be more clients than service providers, so adopting this best practice will reduce the number of ports that need to be conjugated.

In the case of this model, it does not matter as there is no distinct service provider or client. After all, in a game of ping pong, both sides "serve"! For this tutorial, we will consider that the player that starts the game will be sending the "ping" and will therefore be the "server" / "Service Provider."

  1. Right-click on the protocol
  2. Select to create a "New UML-RT Child > InProtocolMessage".
  3. The protocol message is created and its name is ready to be edited in the model explorer in the model explorer .
  4. Rename the protocol message to "ping" (remember, as the server, the port will be conjugated, so it will have to be the opposite of the action we expect, so incoming).

GSwPRT09AddProtocolMessages.png

Add the "pong" Protocol Message

To create the "pong" message, use the same process as for the creation of the "ping" protocol message, above, except that you will instead create a "ProtocolMessageOut" and name the protocol message "pong"

  1. Right-click on the PingPong protocol and select "New UML-RT Child > OutProtocolMessage"
  2. Rename the resulting protocol message to "pong"
  3. You now have a "pong" protocol message in addition to "ping".

GSwPRT09AddPongProtocolMessage.png

The "PingPong" protocol is now complete

The protocol and its protocol messages can now be seen in both the Model Explorer and the Properties view.

GSwPRT09PingPongProtocolComplete.png

Defining the Tutorial's "PingPong" System's Structure

Now that we have a protocol, we can move on to creating the structure of the "PingPong System."

We will need to create three capsules for this tutorial model:

  • Two capsules that will be representing the two players: "Pinger" ("player 1")** and "Ponger"** (player 2). We will be creating two capsules to highlight some aspects of the communication mechanisms, especially related to how ports are used with asymmetric protocols. If we had a symmetric protocol, we could simply use two instances of the same capsule, but that would be a less interesting model for a tutorial. Also note that, in this example, the two capsules will be slightly different as one has the added responsibility to start the game
  • A top capsule representing the complete system ("Top") In UML-RT, the building blocks are capsules and there is always a top capsule that represents the system to be built. The complete set of capsules that are required to implement the system's functionality are then included by the containment hierarchy from this top capsule.

Create the Pinger capsule

This capsule will represent the starting player in the game. As such, it will be responsible for sending the first "ball" (message). It will also have to react when receiving the ball from the other player.

Create the Pinger ("player 1") capsule

Let's start by creating the Pinger capsule.

  1. Right-click on the PingPong model in the Model Explorer and select "New UML-RT Child > Capsule"
  2. After the capsule is created, it's name is selected for edition, name it "Pinger"

PRT09-10-CreatePingerCapsule.png

Look at the Pinger capsule and open it's diagram

Now that we have a capsule, let's have a look at what it contains and at its diagram.

  1. Expand the Pinger capsule in the model explorer by clicking on the triangle at the beginning of its Model Explorer entry. You will notice that there is already a contained element: Pinger's diagram link. In Papyrus-RT, every capsule has a capsule diagram, this link is a quick way to open it
  2. That diagram link is also accessible from the "Editor" under the View heading.

GSwPRT09OpenPingerCapsuleDiagram.png

Open Pinger's capsule diagram

To do this, simply double-click on either of the diagram described in the previous step (or single-click on the blue textual link in the editor view list)

One open, you will see:

  1. The representation of the Pinger capsule. It does not contain much right now, but we will work on that in this tutorial.
  2. A editor tab is added at the bottom of the editor. This is useful when you have multiple diagram open so you can easily navigate between them
  3. A tool palette providing you with the various tools that are relevant when working on a diagram in the context of the capsule's structure (in this case).

PRT09-10PingerCapsuleDiagram.png

Add an external port to Pinger

In order to be able to communicate, Pinger will need an external port through which it can send messages to other capsules. Let's add this port now.

  1. Click on "Port" in the tool palette.
  2. Click on the right border of the Pinger capsule.
  3. In the resulting dialog, select "Port with Existing Protocol"
  4. In the resulting dialog, expand the "PingPong" model entry and select the "PingPong" protocol that was created earlier.
  5. Name the resulting port "pingPort". This can be done by using the direct editor available on the port name.
  6. Since we have decided that Ping would be the "server" capsule, we also have to change the conjugation of its port. To do so, look in the Properties view just below the Editor, and make sure that the "UML-RT" tab is selected
  7. Click on the box to the left of "Is conjugated".
  8. When the port is conjugated, you will notice that its graphical element will change from being all black to getting a white fill, graphically showing the conjugation state.
Note.png
Context menu
A quicker way to change the conjugation of a port is to right-click on the port and select UML-RT Properties > Is Conjugated


GSwPRT09AddPingerExternalPort1.png GSwPRT09AddPingerExternalPort2.png GSwPRT09AddPingerExternalPort3.png GSwPRT09AddPingerExternalPort4.png GSwPRT09AddPingerExternalPort5.png

Add a log port

If we want to make sure that the model actually runs correctly, we will need to get some information displayed. The Papyrus-RT runtime provides a logging mechanism to allow the model to print out information. In the current version, it only does this to stdout, but this capability is extensible to use other output targets.

So all that is needed to be able to log event to the screen is to add a log port to the capsule.

  1. Select the Port tool and create a port in the middle of the capsule
  2. In the resulting dialog, select the "Log" entry
  3. Leave the name as is. You have now create a log port through which you can print messages. We will see how to use it when we add the behaviour to the capsule.

PRT009-10AddLogPort.png

Create Pinger's state machine

As mentioned, the behaviour of a capsule is represented by a state machine, but one is not provided by default as some capsules may not need to have behaviour.Examples of capsules not needing behaviour are for container capsules, such as "Top", and some patterns, such as dynamic forwarding.

  1. Right-click on the Pinger capsule in the Model Explorer and select "New UML-RT Child > StateMachine" to create the state machine.
  2. The state machine is created and its diagram is available from the Editor's View list.

PRT09-10CreatePingerStateMachine.png

Add the Pinger StateMachine behaviour

  1. Now that we have a state machine, let's add the behaviour to it: open the Pinger::StateMachine. You will notice that we already provide you with the initial pseudostate and a state ("State1") to get you started
  2. Move these two initial elements to better positions, as shown and rename "State1" to "Playing" (hint: use the Properties tab)
  3. We will also add a transition that will be taken when the other player returns the ball. Using the transition tool draw a transition from the "Playing" state to itself.

GSwPRT09AddPingerStateMachineBehaviour 1.png GSwPRT09AddPingerStateMachineBehaviour 2.png

Add initial transition action

All that is now left is to add some triggers (which allow for transitions to be taken as a response to a message) and code block (remember, we are using C++ as the "Action Language".

Let's start with the Initial Transition. Note that the initial transition is always taken once, when the capsule is instantiated, so it does not need an trigger.

  1. Click on the Initial transition and then open the Code Snippet View" in the Properties View area. Make sure that the "Effect" tab is selected at the bottom of the view.
  2. In the code snippet view, add the following code:
// Start the game by sending a "ping" to the other player
log.log("Starting game");
if ( pingPort.ping().send() ) {
    log.log( "ping sent!");
} else {
    log.log( "Error sending Ping!");
}

GSwPRT09AddInitialTransitionAction.png

Edit the trigger and code for self transition

  1. Select the transition in the diagram and switch to the Properties view.

PRT09-10EditSelfTransitionTriggerAndCode.png

Add the transition trigger

  1. Click on the [+] button in the Trigger section to create a new trigger.
  2. From the resulting dialog, select the pingPort.
  3. From the list of protocol messages, select the pong protocol message.
  4. Click OK to set the trigger.
  5. You now have a trigger defined for this transition. When the model runs, any message received while in the Playing state will result in this transition being taken.
  6. Notice that the transition name has be set to the name of the protocol message selected, providing a clue on the diagram as to when the transition is triggered.

PRT09-10AddTransitionTrigger.png

Add code for the transition

The only thing left to do for this transition is to add its code. The basic steps are the same as those taken previously to add the code for the initial transition

  1. Click on the transition and the Code Snippet View to bring up the C++ editor for the transition. Make sure that the "Effect" tab is selected at the bottom of the view.
  2. Type in the following code (you will notice that it is very similar to that of the initial transition):
// Reply to a pong message by sending a ping.
log.log("Pong received!");
if ( pingPort.ping().send() ) {
    log.log( "ping sent!");
} else {
    log.log( "Error sending Ping!");
}

PRT09-10AddTransitionCode.png

You are now done with the creation of the Pinger capsule!

Create the "Ponger" capsule

To create the "Ponger" capsule, simply follow the same steps as when Pinger was created, with the following differnces:

  • The capsule will be named "Ponger" instead of "Pinger"
  • The port is named "pong" and is not conjugated.
  • You should place the port on the left edge of the capsule, instead of the right. This will allow us to put both capsules side by side so that their ports will be easy to connect.
  • The capsule's state machine will be different as it does not need to start the game and it will not return the fifth ball in order to stop the game.

Create the "Ponger" capsule's structure

Create the Ponger capsule's structure using the same instructions as for the Pinger capsule structure, but with the following changes:

  • The capsule is named "Ponger"
  • The external port is placed on the left edge of the capsule, instead of the right. This will make it easier for us to connect the capsules when we put both side by side.
  • The external port is named "pongPort"
  • The external port is not conjugated.
  • The log port is created in the same way

The result should be as shown below.

PRT09-10CreatePongerCapsuleStructure.png

Create the Ponger Capsule's statemachine

Create the Ponger capsule's statemachine using the same instructions as for the Pinger capsule structure, but with the following changes:

  • The intial transition code will simply log that Ponger is ready to play:

log.log("Ponger is ready");

  • The self-transition's trigger will be on PongPort's ping protocol message.
  • The self-transition's code will simply send a pong for every Ping received.

The result should be as shown below.

GSwPRT09CreatePongerStateMachine.png

Create the "Top" system capsule

Although it is possible to generate the various capsules on their own, the interactions between them would not happen until their ports are interconnected.

To do this, we create a "Top" capsule that will contain instances of the capsules that we can then connect. Once this is done, we can generate the code for that "Top" capsule and execute it.

Note that, although it is not a requirement, the "Top" capsule we will create in here will be only structural, it will not, by itself, implement behaviour, other than that of its contained capsule parts.

Create the "Top" capsule

  1. Create a new capsule in the model and name it "Top".
  2. Open Top's capsule diagram.
  3. From the model explorer, drag and drop a Pinger capsule into Top's compartment, on the left side.
  4. From the model explorer, drag and drop a Ponger capsule into Top's compartment, on the right side. Aim to have their ports vertically aligned.
  5. Use the Connector tool from the palette to draw a connector between each capsule part's ports.
  6. That's it! You have created the Top capsule with two capsule parts that can now communicate with each other!

PRT09-10CreateTopCapsule.png

Execute the model

Now that the model is complete, we can execute it.

Set the top capsule

First, we need to identify which capsule to use as the "top" capsule. This is typically something that is done only once.

  1. Right-click on the "Top" capsule in the Model Explorer to bring up the context menu
  2. Select "Set as default top capsule"

Although there are no visible changes, the capsule is now set as the "Top" capsule.

GSwPRT09SetTopCapsule.png

Generate the model

Now that the "top" capsule is set, you can generate the code from the model.

  1. Right-click on the model's root element ("PingPong" at the top of the Model Explorer).
  2. Select "Generate code (incremental)"
  3. Click OK the resulting dialog

GSwPRT09GenerateModel.png

Generated model code

When generating the code for the model, a CDT project is created to hold the code.

PRT09-10GeneratedModel.png

Compile the model

To compile and run the model, you will need a compatible build environment. At present, we support Linux.

Note.png
Use of command line
The integration with CDT is not yet complete. To build the system, you will have to go to the command line.
Note.png
Using an OS other than Linux
If you are using an operating system other than Linux, you can still compile and run your model. Go to Compiling and running Papyrus for Real Time applications for alternatives


  1. Open a terminal and go to the folder where the code was generated, in this case, the folder name would be <workspace>/PingPong_CDTProject/src, replacing "<workspace>" with the path to your workspace location, e.g., "~/workspaces/GettingStarted".
  2. Type "make" at the command prompt to compile and link the model's generated code.

GSwPRT09CompileModel.png

Run the model's executable

You can then run the executable, making sure to kill it soon after it starts, else it'll run forever...

  1. At the command prompt, type "./TomMain"
  2. Quickly type "Ctrl-c" to kill the execution

GSwPRT09RunModelExecutable.png

Congratulations!

Papyrus-rt-congratulations.png

Previous Tutorial versions

Back to the top