View source for Papyrus-RT/User/User Guide/Getting Started/v0.7-8

[[File:PapyrusForRealTime-Logo-Icon.png|left|bottom-align|]]<br/><br/><span style="font-family: Helvetica,Arial,sans-serif; font-size: 48px;"><b>Getting Started with Papyrus for RealTime v0.7/0.8</b></span><br/><br/><br/>

__TOC__

{{Note | Note | This document was created for Papyrus-RT v0.7/0.8 and no longer reflect the current state of the tool.}}

= Introduction =

This tutorial will show the creation of a simple model using '''Papyrus for RealTime version 0.7.0''' (and 0.8, based on Eclipse Mars).

'''As a precondition to going through this tutorial, you must have Papyrus for Real Time installed and the tool '''open'''. Please see [[Papyrus-RT/User#Installation | Installing Papyrus-RT]] for the various methods to install Papyrus for Real Time.

'''Note''': <code>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.</code>

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 [https://www.eclipse.org/papyrus-rt/content/overview.php Papyrus Overview] page.

The model that will be created as part of this tutorial is a simple, &quot;PingPong&quot; game with two players. 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.

== Select File -> New -> Papyrus Project ==

[[Image:Papyrus-rt-Select_New_Papyrus_Project.png]]

== Selecting the language to be used for the model ==

In the resulting dialog:

# 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
# Click on '''[Next]'''.

[[Image:Papyrus-rt-Select-model-language.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.

# 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 &quot;'''PingPong'''&quot;.
# 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.
# Enter &quot;'''PingPong'''&quot; as the model file name.
# Click on '''[Next]'''

[[Image:Papyrus-rt-define-the-project.png]]

== Provide model initialization information ==

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

# The &quot;Root model element&quot; is a representation of the model itself. For this tutorial, and for consistency, we will name it &quot;'''PingPong'''&quot;.
# There is no more information to add on this dialog as they are already set in the wizard. Click '''[Finish]''' to create the project and contained model.

As shown in the image below, you should now have a project named &quot;PingPong&quot; containing a &quot;PingPong&quot; model in the Project Explorer as well as that model opened in the Model Explorer.

[[Image:Papyrus-rt-model-initialization-info.png]]

== Project and Model Created ==

After expanding the &quot;PingPong&quot; project in the Project Explorer and the &quot;PingPong&quot; model in the Model Explorer, you will see that they have both been created and are now available for modeling.

[[Image:Papyrus-rt-project-and-model-created.png]]

= Add profiles the model =

A lot has been done already to create an empty model and you have seen, in the previous step, that the base UML-RT profile has been applied. There are a few more components that need to be added to enhance the experience and the capabilities of the tool.

The first step will be to add some profiles.

== Select the PingPong model in the Model Explorer and, in the Properties View, select the "Profile" tab. ==

We will start by adding two profiles to the model:

* &quot;'''UML RT StateMachines'''&quot; defines stereotypes and rules for state machines to support UML-RT specific semantics;
* &quot;'''UML-RT C++ Property Set Profile'''&quot; defines stereotypes that enable more precise code generation for many model elements.

Both these profiles are part of the Papyrus-RT distribution and have already been registered during installation.

# With the &quot;PingPong&quot; model selected in the Model Explorer, click on the &quot;Profile&quot; tab of the Properties view.
# Click on the &quot;'''Apply registered profile'''&quot; button

[[Image:Papyrus-rt-select-pingpong-profile-model-properties.png]]

== Select the profiles to be added to the model ==

# In the resulting dialog, select the both the &quot;'''UML RT StateMachines'''&quot; and &quot;'''UML-RT C++ Property Set Profile'''&quot; entries.
# Click '''[OK]'''

[[Image:Papyrus-rt-select-additional-profiles.png]]

== Add profiles to the model ==

# In the resulting dialog, click &quot;Select All&quot;
# Note that both profiles are checked
# Click '''[OK]'''

[[Image:Papyrus-rt-add-profiles.png]]

== The new profiles are now applied. ==

[[Image:Papyrus-rt-new-profiles-applied.png]]

= Add UML-RT Runtime Services Library =

A model library containing elements and protocols from the UML-RT Runtime Services layer is also available. This library contains class definitions and protocols that are useful, and in some cases, essential, for the creation of UML-RT models.

This library needs to be imported before it can be used.

== Open the package import dialog ==

# Right-click on the model in the Model Explorer and select &quot;'''Import &gt; Import Registered Package'''&quot;

[[Image:Papyrus-rt-import-registered-package.png]]

== Import the "UML-RT Runtime Services" package ==

# In the resulting dialog, select the &quot;'''UML-RT Runtime Services'''&quot; package from the list
# Click '''[OK]'''

[[Image:Papyrus-rt-import-umlrt-runtime-services.png]]

== Import all parts for the UML-RT model library ==

# Click on '''[Load All]'''
# Note that only the top-level element is selected - that is the expected behavior as it contains everything.
# Click on '''[OK]'''

[[Image:Papyrus-rt-import-all-umlrt-model-library.png]]

== Repeat the previous steps and select "UMLPrimitiveTypes" as the library to import. ==

The &quot;'''UMLPrimitiveTypes'''&quot; library contains the standard UML types. These can be used to specify property types. To use more specific or specialized base types, you could also use the &quot;'''AnsiCLibrary'''&quot; or the properties defined as part of the &quot;'''RTCppProperties'''&quot; stereotype. In this tutorial, we will not have a need to use specific types.

== The model libraries are now available to the model developer ==

You can now see that both the &quot;'''RTS'''&quot; and &quot;'''UML Primitive Types'''&quot; libraries are imported into the model.

'''Note 1:''' Neither of these model libraries are stored within the &quot;'''PingPong'''&quot; model. They are actually part of Papyrus-RT plugins and are &quot;read-only&quot;. You can, however, still make use of their content as part of the modelling of &quot;'''PingPong'''&quot;.

'''Note 2''': The code generator handles the &quot;'''RTS'''&quot; library is a special way and will not generate code for it as it only reflects the actual runtime services, which are provided separately as part of the Papyrus-RT distribution.

We are now ready to start our modelling our PingPong system.

[[Image:Papyrus-rt-model-libraries-now-available.png]]

= Create a protocol to specify the messages that can be exchanged between players =

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 &quot;Capsules&quot; 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, &quot;ball&quot;. However, to better explore the concept of protocols, we will define our &quot;PingPong&quot; protocol to have one outgoing protocol message called &quot;ping&quot; and one incoming protocol message called &quot;pong&quot;.

== Create the protocol ==

The first step is to create the protocol itself.

# Right-click on the &quot;PingPong&quot; model in the Model Explorer and select &quot;'''UMLRealTime &gt; Protocol'''&quot;

You now have a &quot;protocol&quot; in the Model Explorer.

[[Image:Papyrus-rt-create-protocol.png]]

== Rename the protocol ==

Give the protocol a better name.

# Right-click on the protocol in the Model Explorer
# Select &quot;'''Rename'''&quot;
# In the dialog, provide &quot;'''PingPong'''&quot; as the new name
# Click '''[OK]'''
# The protocol has been renamed

[[Image:Papyrus-rt-rename-protocol.png]]

== Add protocol messages to the protocol ==

A protocol is actually a complex construct and, as part of the UML-RT DSML, we are hiding its complexity so you do not need to know what lies beneath to create models!

Our protocol will &quot;ping&quot; its opponent and, in return, will respond to a &quot;pong&quot;. This tells us that there will be a &quot;ping&quot; outgoing protocol message and a &quot;pong&quot; 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 &quot;serve&quot;! In this tutorial, we will define the protocol from the point fo the player that will &quot;ping&quot;.

# Right-click on the protocol
# Select to create a &quot;'''UMLRealTime &gt; ProtocolMessage Out'''&quot;.
# Expand the protocol (by clicking on the right-pointing triangle at its left) and notice that a new protocol message is available.

[[Image:Papyrus-rt-add-protocol-messages.png]]

== Rename the outgoing protocol message ==

Right-click on the new protocol message, select &quot;Rename&quot;, and change its name to &quot;ping&quot;.

[[Image:Papyrus-rt-rename-outgoing-protocol-message.png]]

== Add a "pong" Incoming Protocol Message ==

To create the &quot;pong&quot; message, use the same process as for the creation of the &quot;ping&quot; protocol message, above, opting to create a &quot;ProtocolMessageIn&quot; instead and renaming the protocol message &quot;pong&quot;

# Right-click on the PingPong protocol and select &quot;'''UMLRealTime &gt; ProtocolMessageIn'''&quot;
# Rename the resulting protocol message to &quot;'''pong'''&quot;
# You now have a &quot;'''pong'''&quot; protocol message in addition to &quot;ping&quot;.

[[Image:Papyrus-rt-add-pong-incoming-protocol-message.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.

[[Image:Papyrus-rt-pingpong-protocol-complete.png]]

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

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

;'''Two capsules representing the two players (&quot;Pinger&quot; and &quot;Ponger&quot;)'''
: 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, and that would be a less interesting model for a tutorial.

;'''A top capsule representing the complete system (&quot;Top&quot;)'''
: 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 =

Let's start by creating the &quot;Pinger&quot; capsule

== Create the Pinger capsule ==

# Right-click on the PingPong model in the Model Explorer and select &quot;'''UMLRealTime &gt; Capsule'''&quot;
# Rick-click on the newly created capsule and select &quot;'''Rename'''&quot; to change its name to &quot;'''Pinger'''&quot;

[[Image:Papyrus-rt-create-pinger-capsule.png]]

== Open Pinger's Composite Structure Diagram ==

Because of the importance of capsule containment in UML-RT, and for the convenience of the user, a composite structure diagram is automatically created for each capsule.

# Click on the right-facing triangle to the left of the &quot;Pinger&quot; capsule to show its contents
# The element displayed is Pinger's composite structure diagram. Double-click on it
# The diagram is now shown in the editor view
# A tab at the bottom indicating the diagram name. Tabs at the bottom of the editor view allow you to easily switch between open diagrams

[[Image:Papyrus-rt-open-pinger-csd.png]]

== Add a port to Pinger and set its type ==

Pinger still needs to communicate with Ponger when it hits the ball. To do this, it needs a port that implements the protocol that we defined earlier.

# In the editor pane, select the '''Port''' entry in the &quot;'''Nodes'''&quot; section of the Palette, click on the right border of &quot;'''Pinger'''&quot; (on the diagram)
# In the resulting dialog, click on [...] to select the protocol
# Expand &quot;PingPong&quot;
# Select &quot;'''«Protocol» PingPong'''&quot;
# Click [OK]
# Click [OK]

[[Image:Papyrus-rt-add-port-to-pinger.png]]

== Rename the port ==

By default, the port will be created with the name in edit mode. At this point, you can just type in its name: 

There are three other ways to rename the port:

* Double-click on the port label and enter the new name
* Right click on the port in the Model Explorer, select &quot;Rename&quot;, and enter the new name
* Select the &quot;Name&quot; property in the Properties view and enter the new name

'''Note''': ports are properties of the capsule and are typically named with a leading lowercase character.

[[Image:Papyrus-rt-rename-pinger-port.png]]

== Add IO libraries ==

In order to see the execution of the model, once generated and built, we will need to print something to the screen, i.e., to &quot;stdout&quot;. In order to do so, we will need to specify the header files that need to be included to give the capsule access to these C++ functions.

This is accomplished though stereotype properties that are used by the code generator to create the correct includes in the generated code.

# Make sure that the &quot;'''Pinger'''&quot; capsule is selected and its Properties displayed with its &quot;Profile&quot; tab selected.
# Click on the '''[+]''', right of &quot;'''Applied Stereotypes'''&quot;
# In the resulting dialog, double-lclick on the &quot;'''CapsuleProperties'''&quot; entry in the &quot;'''Applicable Stereotypes'''&quot; box to move it to the &quot;'''Applied Stereotypes'''&quot; and click '''[OK]''' to apply the stereotype. This stereotype allows the modeler to set C++ specific constructs to help in the development of the executable model.
# Expand the &quot;CapsuleProperties: stereotype to see its properties and select the &quot;implementationPreface&quot; property.
# In the &quot;Implementation box, type in the following: #include &lt;iostream&gt;

That's all we need for now, we will see how to use this import during the creation of the the capsule's behavior.

[[Image:Papyrus-rt-add-pinger-io-libraries.png]]

== Create Pinger's state machine ==

In UML-RT, all behavior is modeled using hierarchical state machines.

These state machines are dubbed &quot;reactive&quot; because actions (or chains of actions) can only be taken as a result of a message being received on the capsule's ports - so they always react to a message. Reception of a message typically results in one of the state machine's transitions being taken. Each transition exiting from a state has a trigger defined by a port and signal (i.e., protocol message for that port), determining when they can be taken (triggered). Fine-grained actions, typically as opaque expressions, can be provided for transitions, as well as for states' entry and exit.

Pseudostates can also be used to implement logic (choice points), continuation (junction, state entry and exit points - limited to a single outgoing transition), and history (deep and shallow).

Each state machine has an initial pseudostate that is triggered when the state machine if first instantiated, providing initialization capability.

# Right-click on &quot;'''Pinger'''&quot; in the Model Explorer and select &quot;'''New Diagram &gt; StateMachine Diagram'''&quot;
# In the resulting dialog, name the state machine diagram &quot;'''Pinger'''&quot;
# Click '''[OK]'''
# [Optional] Rename the state machine to &quot;'''Pinger'''&quot;
# Both the state machine and its diagram are now available

[[Image:Papyrus-rt-create-pinger-state-machine.png]]

== Set the state machine's stereotype and properties ==

'''Note''': The tooling does not yet set all the properties for a UML-RT state machine, so you will have to set them manually.

# Keeping the &quot;'''Pinger'''&quot; state machine selected in the Model Explorer, use the Profile tab of the Properties Explorer to add the &quot;'''RTStateMachine'''&quot; stereotype to the state machine.
# Expand the &quot;'''Pinger'''&quot; state machine in the Model Explorer to show and select the contained &quot;'''Region1'''&quot; region and then add the &quot;'''RTRegion'''&quot; stereotype to it.

1.

[[Image:Papyrus-rt-set-pinger-state-machine-stereotype.png]]

== Create the state machine's content ==

The state machine for Pinger is rather simple. It consists of a single state &quot;'''Playing'''&quot; with a self-transition triggered on receiving the &quot;'''pong'''&quot; message on the &quot;'''pingPort'''&quot;.

However, we will also want &quot;'''Pinger'''&quot; to start the match, so we will need to do so during or right after the initialisation of the capsule. We can do this because capsule behavior only starts after all static capsule parts are created, so the message queues are already in place to receive messages. Because we do not want to have to issue the same code twice, and since &quot;'''Pinger'''&quot; will send a ball each time it receives a pong message, we will use a junction point to be able to reuse a transition's code.

# Using the Palette's &quot;'''Nodes'''&quot; drawer, add an &quot;'''Initial'''&quot; pseudostate to the top left of the capsule's state machine and apply the &quot;'''RTPseudostate'''&quot; stereotype to it. You can leave its name as is or change it as you please.
# Using the Palette's &quot;'''Nodes'''&quot; drawer, add a &quot;'''State'''&quot; below and to the right of the &quot;'''Initial&quot;''' pseudostate, name it &quot;'''Playing'''&quot;, and apply the &quot;'''RTState'''&quot; stereotype to it.
# Using the Palette's &quot;Edges&quot; drawer, draw a &quot;'''Transition'''&quot; from &quot;'''Initial'''&quot; to &quot;'''Playing'''&quot; named &quot;'''initial'''&quot;, and another from &quot;'''Playing'''&quot; to itself named &quot;'''onPong'''&quot;. '''Note 1:''' The start and end are very important when drawing a transition and it defines the direction, the first click being the origin and the second the destination. '''Note 2:''' It is a good idea to name transitions as this helps in understanding the diagram and, also, in debugging later on - here, we have used a short form of the trigger event. '''Note 3:''' Setting the transition to be &quot;rectilinear&quot; is useful when drawing state machines: right-click on a transition and select &quot;Format &gt; Line Style &gt; Rectilinear Style Routing.

[[Image:Papyrus-rt-create-pinger-state-machine-content.png]]

== Add "onPong:" transition trigger to the state machine ==

As indicated previously, the &quot;'''Initial'''&quot; transition does not need a trigger as it is taken automatically when the state machine is first instantiated. However, for the &quot;'''onPong'''&quot; transition to be taken, we will need to define a trigger for the transition that will determine when the transition can be taken.

# Select the &quot;'''onPong'''&quot; transition. In the Properties view's UML Tab, click on the '''[+]''' to the right of the &quot;'''Trigger'''&quot; field to create a new Trigger.
# In the resulting &quot;'''Create a new Trigger'''&quot; dialog, set the name to &quot;'''onPong'''&quot;.
# Click on the '''[+]''' to the right of the &quot;'''Port'''&quot;
# On the resulting dialog, find the &quot;'''pinger'''&quot; port under the &quot;'''Pinger'''&quot; capsule, double-click on it to transfer it to the right box
# Click '''[OK]''', closing the dialog and bringing back the &quot;'''Create a new Trigger'''&quot; dialog
# Click on the '''[...]''' to the right of &quot;'''Protocol message'''&quot; to bring up the &quot;'''Protocol Message'''&quot; dialog
# Select the &quot;'''pong'''&quot; protocol message.
# Click on '''[OK]''', closing the dialog and bringing back the &quot;'''Create a new Trigger'''&quot; dialog and then '''[OK]''' again to close that dialog
# The trigger is now complete.

[[Image:Papyrus-rt-add-onpong-transition-trigger-2.png]]

== Add an effect to the "onPong" transition to log it was taken. ==

So that we can be sure that the &quot;'''onPong'''&quot; is indeed taken, let's add an effect to log this.

# Select the &quot;'''OnPong'''&quot; transition. In the Properties view's UML Tab, click on the '''[+]''' to the right of the &quot;'''Effect'''&quot; field to create a new action and select &quot;'''Opaque behavior'''&quot;.
# In the resulting dialog, set the name to &quot;logTransition&quot;.
# Click on the '''[+]''' to the right of &quot;'''Language'''&quot; to bring up the language selection dialog
# Double-click on &quot;'''C++'''&quot; from the selection dialog to move it to the selected item box. We are using C++ as the coding language within the tool to match our C++ runtime service library
# Click '''[OK]'''
# In the blank box to the right of the language selection, type &quot;std::cout &lt;&lt; &quot;onPong transition taken!&quot; &lt;&lt; std::endl;&quot;. This log command will enable us to see when the transition is taken when running the resulting executable.
# Click '''[OK]'''.
# The transition now contains an effect that will be executed each time the transition is taken.

[[Image:Papyrus-rt-add-onpong-transition-effect.png]]

== Add the "Playing" entry action behavior to the state machine ==

We will now create an action that happens each time the &quot;'''Playing'''&quot; state is entered. This approach allows us to have this code in a single location, whether the transition into the &quot;'''Playing'''&quot; state is from the &quot;'''initial'''&quot; or the &quot;'''OnPong'''&quot; transition, allowing this player to both start the game and keep on playing, as per our requirements. This action will consist in sending a &quot;'''ping'''&quot; message to the other player, represented by the &quot;'''Ponger'''&quot;capsule. To do this, we'll add an entry action to that state to handle that.

# Select the &quot;'''Playing'''&quot; state. In the Properties view's UML Tab, click on the '''[+]''' to the right of the &quot;'''Entry'''&quot; field to create a new entry action and select &quot;'''Opaque Behavior'''&quot;, just like you did int the previous step.
# In the resulting dialog, set the name to &quot;'''sendPing'''&quot;.
# Click on the '''[+]''' to the right of &quot;'''Language'''&quot;
# In the resulting dialog, set &quot;'''C++'''&quot; as the language, clicking [OK] to get back to the opaque behavior creation dialog.
# In the blank box to the right of the language selection, type the following code: if ( pinger.ping().send() ) { std::cout &lt;&lt; &quot;Ping sent!&quot; &lt;&lt; std::endl; } else { std::cout &lt;&lt; &quot;Error sending Ping!&quot; &lt;&lt; std::endl; }
# Click '''[OK]''' to get back to the Properties view

'''Note:''' the syntax to send a message on a port is &quot;'''().''''''('''''').send()'''&quot;. In the case above, no parameters were defined for the &quot;'''ping'''&quot; protocol message. There are other variants of the send command that allows, for example, to send a message to one slot of a replicated capsule part. The &quot;'''Send()'''&quot; operation returns the number of messages sent, so returning &quot;'''0'''&quot;, which is equivalent to &quot;'''false'''&quot;, indicates an error.

[[Image:Papyrus-rt-add-playing-state-entry-action.png]]

= Create the Ponger Capsule =

The &quot;'''Ponger'''&quot; capsule will be created in the same way as the &quot;'''Pinger'''&quot; capsule was in the previous step. So the instructions below should be familiar to you, even when abbreviated.

== Create the Ponger capsule ==

# Right-click on the PingPong model in the Model Explorer and select &quot;'''UMLRealTime &gt; Capsule'''&quot;
# Rick-click on the newly created capsule and select &quot;'''Rename'''&quot; to change its name to &quot;'''Ponger'''&quot;

[[Image:Papyrus-rt-create-ponger-capsule.png]]

== Open Ponger's Composite Structure Diagram ==

# Expand &quot;Ponger&quot; in the model explorer and double-click on the &quot;Ponger&quot; composite structure diagram to open it in the editor view.

[[Image:Papyrus-rt-open-ponger-csd.png]]

== Add a port to Ponger and set its type ==

'''Ponger''' will need to communicate with '''Pinger''' when it receives the ball, that is, it will have to respond by sending the ball back. To do this, it needs a port that implements the &quot;'''PingPong'''&quot; protocol we defined earlier.

# In the Model Explorer, select the &quot;'''PingPong'''&quot; protocol and drag it to the left border of &quot;'''Ponger'''&quot; on the composite structure diagram.
# In the resulting dialog, click on &quot;'''Protocol drop to create External Behavior Port'''&quot;

[[Image:Papyrus-rt-add-port-to-ponger.png]]

== Rename the port and set its conjugation ==

In order to be able to communicate, connected ports must have opposite conjugation. Since we left the conjugation of the &quot;pinger&quot; port in &quot;Pinger&quot; to the default, we have to change this port to be conjugated.

# Rename the port to &quot;ponger&quot;.
# Click in the box to the left of &quot;Is conjugated&quot;

[[Image:Papyrus-rt-rename-ponger-port-and-set-conjugation.png]]

== Add IO libraries ==

Just like we did with &quot;Pinger&quot;, we will use the C++ standard &quot;cout&quot; to log messages, showing that the model is indeed executed.

# Make sure that the &quot;'''Pinger'''&quot; capsule is selected and its Properties displayed with its &quot;Profile&quot; tab selected.
# Click on the '''[+]''', right of &quot;'''Applied Stereotypes'''&quot;
# In the resulting dialog, double-lclick on the &quot;'''CapsuleProperties'''&quot; entry in the &quot;'''Applicable Stereotypes'''&quot; box to move it to the &quot;'''Applied Stereotypes'''&quot; and click '''[OK]''' to apply the stereotype. This stereotype allows the modeler to set C++ specific constructs to help in the development of the executable model.
# Expand the &quot;CapsuleProperties: stereotype to see its properties and select the &quot;implementationPreface&quot; property.
# In the &quot;Implementation box, type in the following: #include

That's all we need for now, we will see how to use this import during the creation of the the capsule's behavior.

[[Image:Papyrus-rt-add-ponger-io-libraries.png]]

== Create Ponger's state machine ==

# Right-click on &quot;'''Ponger'''&quot; in the Model Explorer and select &quot;'''New Diagram &gt; StateMachine Diagram'''&quot;
# In the resulting dialog, name the state machine diagram &quot;'''Ponger'''&quot; and click '''[OK]'''
# Rename the state machine to &quot;'''Ponger'''&quot;
# Both the state machine and its diagram are now available

[[Image:Papyrus-rt-create-ponger-state-machine.png]]

== Set the state machine's stereotype and properties ==

'''Note''': The tooling does not yet set all the properties for a UML-RT state machine, so you will have to set them manually.

# Keeping the &quot;'''Ponger'''&quot; state machine selected in the Model Explorer, use the Profile tab of the Properties Explorer to add the &quot;'''RTStateMachine'''&quot; stereotype to the state machine.
# Expand the &quot;'''Ponger'''&quot; state machine in the Model Explorer to show and select the contained &quot;'''Region1'''&quot; region and then add the &quot;'''RTRegion'''&quot; stereotype to it.

1.

[[Image:Papyrus-rt-set-ponger-state-machine-stereotype.png]]

== Create the state machine's content ==

The &quot;Ponger&quot; state machine will greatly resemble the one that we created for &quot;'''Pinger'''&quot;. The main difference is that since &quot;'''Ponger'''&quot; will not be initiating the game, all its action can be defined as part of an &quot;'''onPing'''&quot; transition - there is no need to create an entry action in this case.

Similarly to &quot;'''Pinger'''&quot;, the state machine for &quot;'''Ponger'''&quot; consists of a single state &quot;'''Playing'''&quot; with a self-transition triggered on receiving the &quot;'''ping'''&quot; message on the &quot;'''ponger'''&quot; port.

However, &quot;'''Ponger'''&quot; will not be initiating the game, so its action can be defined entirely as part of an &quot;'''onPing'''&quot; transition - there is no need to create an entry action in this case.

# Using the Palette's &quot;'''Nodes'''&quot; drawer, add an &quot;'''Initial'''&quot; pseudostate to the top left of the capsule's state machine and apply the &quot;'''RTPseudostate'''&quot; stereotype to it. You can leave its name as is or change it as you please.
# Using the Palette's &quot;'''Nodes'''&quot; drawer, add a &quot;'''State'''&quot; below and to the right of the &quot;'''Initial&quot;''' pseudostate, name it &quot;'''Playing'''&quot;, and apply the &quot;'''RTState'''&quot; stereotype to it.
# Using the Palette's &quot;Edges&quot; drawer, draw a &quot;'''Transition'''&quot; from &quot;'''Initial'''&quot; to &quot;'''Playing'''&quot; named &quot;'''initial'''&quot;, and another from &quot;'''Playing'''&quot; to itself named &quot;'''onPing'''&quot;.

'''Note 1:''' The start and end are very important when drawing a transition and it defines the direction, the first click being the origin and the second the destination.''* Note 2:''* It is a good idea to name transitions as this helps in understanding the diagram and, also, in debugging later on - here, we have used a short form of the trigger event. '''Note 3:''' Setting the transition to be &quot;rectilinear&quot; is useful when drawing state machines: right-click on a transition and select &quot;Format &gt; Line Style &gt; Rectilinear Style Routing.

[[Image:Papyrus-rt-create-ponger-state-machine-s-content.png]]

== Add "onPing:" transition trigger to the state machine ==

As indicated previously, the &quot;'''Initial'''&quot; transition does not need a trigger as it is taken automatically when the state machine is first instantiated. However, for the &quot;'''onPing'''&quot; transition to be taken, we will need to define a trigger for the transition that will determine when the transition can be taken.

# Select the &quot;'''onPing'''&quot; transition. In the Properties view's UML Tab, click on the '''[+]''' to the right of the &quot;'''Trigger'''&quot; field to create a new Trigger.
# In the resulting &quot;'''Create a new Trigger'''&quot; dialog, set the name to &quot;'''onPing'''&quot;.
# Click on the '''[+]''' to the right of the &quot;'''Port'''&quot;
# On the resulting dialog, find the &quot;'''ponger'''&quot; port under the &quot;'''Ponger'''&quot; capsule, double-click on it to transfer it to the right box
# Click '''[OK]''', closing the dialog and bringing back the &quot;'''Create a new Trigger'''&quot; dialog
# Click on the '''[...]''' to the right of &quot;'''Protocol message'''&quot; to bring up the &quot;'''Protocol Message'''&quot; dialog
# Select the &quot;'''ping'''&quot; protocol message.
# Click on '''[OK]''', closing the dialog and bringing back the &quot;'''Create a new Trigger'''&quot; dialog and then '''[OK]''' again to close that dialog
# The trigger is now complete and the results are shown below.

[[Image:Papyrus-rt-add-onping-transition-trigger.png]]

== Add an effect to the "onPing" transition to log it was taken. ==

So that we can be sure that the &quot;'''onPing'''&quot; is indeed taken, let's add an effect to log this.

# Select the &quot;'''OnPing'''&quot; transition. In the Properties view's UML Tab, click on the '''[+]''' to the right of the &quot;'''Effect'''&quot; field to create a new action and select &quot;'''Opaque behavior'''&quot;.
# In the resulting dialog, set the name to &quot;logTransition&quot;.
# Click on the '''[+]''' to the right of &quot;'''Language'''&quot; to bring up the language selection dialog
# Double-click on &quot;'''C++'''&quot; from the selection dialog to move it to the selected item box. We are using C++ as the coding language within the tool to match our C++ runtime service library
# Click '''[OK]'''
# In the blank box to the right of the language selection, type the following code:

if ( ponger.pong().send() ) { std::cout &lt;&lt; &quot;Pong sent!&quot; &lt;&lt; std::endl; } else { std::cout &lt;&lt; &quot;Error sending Ping!&quot; &lt;&lt; std::endl; }

This will send back a pong message to &quot;Pinger&quot; and display a message indicating whether the send was successful or not. This enables us to see when the transition is taken when running the resulting executable. 1. Click '''[OK]'''. 1. The transition now contains an effect that will be executed each time the transition is taken and the results are shown below.

[[Image:Papyrus-rt-add-onping-transition-effect.png]]

= Implement the System as the Top Capsule =

As described previously, the top capsule represents the system to be built. As such, it will not be contained in any other capsule and will contain the capsules required to implement its capabilities.

In the context of this tutorial, our Top capsule will contain instances of both &quot;'''Pinger'''&quot; and &quot;'''Ponger'''&quot; as well as the connection between them.

<code>'''Note''': At present, the top capsule '''''must''''' '''be named &quot;Top&quot;. This is a limitation until we complete the implementation of the build specification mechanism.'''</code>

== Create the Top capsule ==

Using the steps from the creation of the &quot;'''Pinger'''&quot; capsule, create the &quot;'''Top'''&quot; capsule and its composite structure diagram, but stop before the creation of the port as &quot;'''Top'''&quot; does not require any ports.

# Right-click on the PingPong model in the Model Explorer and select &quot;'''UMLRealTime &gt; Capsule'''&quot;
# Rick-click on the newly created capsule and select &quot;'''Rename'''&quot; to change its name to &quot;'''Top'''&quot;
# Open the composite structure diagram for &quot;'''Top'''&quot;

[[Image:Papyrus-rt-create-top-capsule.png]]

== Add Pinger to the Top Capsule Structure ==

We can now start populating the &quot;'''Top'''&quot; capsule by creating an instance of &quot;'''Pinger'''&quot; within its structure.

# Drag and drop &quot;'''Pinger'''&quot; from the Model Explorer inside of &quot;'''Top'''&quot;'s structure, on the left side.
# In the resulting dialog, click on &quot;'''Capsule drop to create CapsulePart'''&quot;.
# You will see that the &quot;instance&quot; is called &quot;'''pinger'''&quot;.
# Expanding &quot;'''Top'''&quot; in the Model Explorer reveals the new &quot;'''«CapsulePart» piner:Pinger'''&quot; property added to the capsule.

'''Fun fact''': <code>&quot;pinger&quot; is not an instance, but a &quot;part&quot;. In this case the part contains a single instance of &quot;Pinger&quot;. However, a part can have a multiplicity, and therefore contain multiple instances (or not if it's multiplicity has a lower bound of 0).</code>

[[Image:Papyrus-rt-add-pinger-to-top-capsule.png]]

== Adjust the representation of the pinger capsule part ==

'''Workaround''': The tooling does not yet automatically show the ports of capsule parts, so you will have to do that manually.

# In the Model Explorer, select the the &quot;pinger&quot; port under the &quot;Pinger&quot; capsule and drop it onto the &quot;pinger&quot; capsule part in Top.
# Move the port so it will be on the right side of the &quot;pinger&quot; capsule part.

[[Image:Papyrus-rt-adjust-pinger-capsule-part-representation.png]]

== Add Ponger to the Top capsule ==

# Repeat the steps you used to add &quot;'''Pinger'''&quot; to the &quot;'''Top'''&quot; capsule, but this time using the &quot;'''Ponger'''&quot; capsule.

[[Image:Papyrus-rt-add-ponger-to-top-capsule.png]]

== Connect the two capsule parts ==

# Select the &quot;'''Connector'''&quot; tool from the '''Palette'''
# Draw a connector from one port to the other (it does not matter from which port you start).

[[Image:Papyrus-rt-connect-the-two-capsule-parts.png]]

= Execute the model =

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

== Generate the code ==

Now that the model is complete, let's generate the code.

# Right-click on the model in the Model Explorer and select &quot;'''UML-RT Code Generator'''&quot;
# Click [OK] on the dialog that shows the results
# A CDT project is created and the C++ code is generated within it.

[[Image:Papyrus-rt-generate-the-code.png]]
== Setup the Build environment ==

In order to be able to compile and link the generated code, the build environment must be set up. The first requirement is regarding the compiler version supported out of the box by the RTS. Within Papyrus for Real Time v0.7.0, the RTS library was pre-built using g++ 4.7.2 (even though the configuration says 4.6.3...), so it is recommended to have that version installed as the default.

If you do not have g++ 4.7.2 installed and do not wish to install it, you can follow the instructions at [[Papyrus-RT/User_Guide/Building_the_RTS | Building the RTS]]

==  Compile the model ==

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

The integration with CDT is not yet complete. To build the system, you will have to go to the command line.

# Open a terminal and go to the folder where the code was generated, in this case, the folder name would be '''/PingPong_CDTProject/src''', replacing &quot;&quot; with the path to your workspace location, e.g., &quot;~/workspaces/GettingStarted&quot;.
# If there is no &quot;'''umlrt.rts'''&quot; folder in that location, you will need to create a link using ln -s /plugins/org.eclipse.papyrusrt.rts_/umlrts ./umlrts.rt where:  is the path to the folder where Eclipse is installed, e.g. &quot;~/Apps/Eclipse&quot;  is the latest version of the plugin, e.g., &quot;0.5.0.201506181214&quot;
# Type &quot;make&quot; at the command prompt to compile and link the model's generated code.

[[Image:Papyrus-rt-compile-the-model.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...

# At the command prompt, type &quot;'''./main'''&quot;
# Quickly type &quot;Ctrl-c&quot; to kill the execution

[[Image:Papyrus-rt-run-the-model-executable.png]]

= Congratulations! =

[[Image:Papyrus-rt-congratulations.png]]