<?xml version='1.0' ?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
<title>eTrice User Guide</title>
<chapter id="eTriceOverview">
<title>eTrice Overview</title>
<section id="WhatiseTrice">
<title>What is eTrice?</title>
<para>eTrice provides an implementation of the ROOM modeling language (Real Time Object Oriented Modeling) together with editors, code generators for Java, C++ and C code and exemplary target middleware.</para>
<para>The model is defined in textual form (Xtext) with graphical editors (Graphiti) for the structural and behavioral (i.e. state machine) parts. </para>
</section>
<section id="WhoshoulduseeTrice">
<title>Who should use eTrice?</title>
<para>Basically everyone who develops eventdriven realtime or embedded systems. </para>
<para>If you have other ideas how to use it, tell us!</para>
</section>
<section id="HowDoesItWork">
<title>How Does It Work?</title>
<para>TODO</para>
</section>
<section id="WhoisBehindeTrice">
<title>Who is Behind eTrice?</title>
<para>TODO</para>
</section>
</chapter>
<chapter id="IntroductiontotheROOMLanguage">
<title>Introduction to the ROOM Language</title>
<section id="ScopeofROOM">
<title>Scope of ROOM</title>
</section>
<section id="BasicConcepts">
<title>Basic Concepts</title>
</section>
<section id="Benefits">
<title>Benefits</title>
</section>
<section id="ExecutionModels">
<title>Execution Models</title>
<section id="LogicalMachine">
<title>Logical Machine</title>
<itemizedlist>
<listitem>
<para>run to completion</para>
</listitem>
</itemizedlist>
</section>
<section id="QueueBasedExecutionModel">
<title>Queue Based Execution Model</title>
</section>
<section id="PolledExecutionModel">
<title>Polled Execution Model
not implemented yet</title>
</section>
<section id="HybridExecutionModel">
<title>Hybrid Execution Model
not implemented yet</title>
</section>
</section>
</chapter>
<chapter id="TutorialHelloWorld">
<title>Tutorial HelloWorld</title>
<section id="Scope">
<title>Scope</title>
<para>In this tutorial you will build your first very simple eTrice model. The goal is to learn the work flow of eTrice and to understand a few basic features of ROOM. You will perform the following steps:</para>
<orderedlist>
<listitem>
<para>create a new model from scratch</para>
</listitem>
<listitem>
<para>add a very simple state machine to an actor</para>
</listitem>
<listitem>
<para>generate the source code</para>
</listitem>
<listitem>
<para>run the model</para>
</listitem>
<listitem>
<para>open the message sequence chart</para>
</listitem>
</orderedlist>
</section>
<section id="Createanewmodelfromscratch">
<title>Create a new model from scratch</title>
<para>The easiest way to create a new eTrice Project is to use the eclipse project wizard. From the eclipse file menu select
<citation>File->New->Project</citation> and create a new eTrice project and name it
<citation>HelloWorld</citation>
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld10.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>The wizard creates everything that is needed to create, build and run a eTrice model. The resulting project should look like this:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld11.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Within the model directory the model file
<citation>HelloWorld.room</citation> was created. Open the
<citation>HelloWorld.room</citation> file and position the cursor at the very beginning of the file. Open the content assist with Ctrl+Space and select
<citation>model skeleton</citation>.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld12.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Edit the template variables and remove the artefacts from the wizard. </para>
<para>The resulting model code should look like this:</para>
<literallayout><code>RoomModel HelloWorld {
LogicalSystem System_HelloWorld {
SubSystemRef subsystem : SubSystem_HelloWorld
}
SubSystemClass SubSystem_HelloWorld {
ActorRef application : HelloWorldTop
}
ActorClass HelloWorldTop {
}
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>The goal of eTrice is to describe distributed systems on a logical level. In the current version not all elements will be supported. But as prerequisite for further versions the following elements are mandatory for an eTrice model:</para>
<itemizedlist>
<listitem>
<para>the
<citation>LogicalSystem</citation>
</para>
</listitem>
<listitem>
<para>at least one
<citation>SubSystemClass</citation>
</para>
</listitem>
<listitem>
<para>at least one
<citation>ActorClass</citation>
</para>
</listitem>
</itemizedlist>
<para>The
<citation>LogicalSystem</citation> represents the complete distributed system and contains at least one
<citation>SubSystemRef</citation>. The
<citation>SubSystemClass</citation> represents an address space and contains at least one
<citation>ActorRef</citation>. The
<citation>ActorClass</citation> is the building block of which an application will be built of. It is in general a good idea to define a top level actor that can be used as reference within the subsystem.
</para>
<para>The outline view of the textual ROOM editor shows the main modeling elements in an easy to navigate tree.</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld02.PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="Createastatemachine">
<title>Create a state machine</title>
<para>We will implement the Hello World code on the initial transition of the
<citation>HelloWorldTop</citation> actor. Therefore open the state machine editor by right clicking the
<citation>HelloWorldTop</citation> actor in the outline view and select
<citation>Edit Behavior</citation>.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld03.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>The state machine editor will be opened. Drag and drop an
<citation>Initial Point</citation> from the tool box to the diagram into the top level state. Drag and drop a
<citation>State</citation> from the tool box to the diagram. Confirm the dialogue with
<citation>ok</citation>. Select the
<citation>Transition</citation> in the tool box and draw the transition from the
<citation>Initial Point</citation> to the State. Open the transition dialogue by double clicking the caption of the transition and fill in the action code.
</para>
<literallayout><code>System.out.println("Hello World !");
</code></literallayout>
<para>The result should look like this:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld04.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Save the diagram and inspect the model file. Note that the textual representation was created after saving the diagram.</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld05.PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="Buildandrunthemodel">
<title>Build and run the model</title>
<para>Now the model is finished and source code can be generated. The project wizard has created a workflow that is responsible to generate the source code. From
<citation>HelloWorld/src/workflow</citation> right click
<citation>HelloWorld.mwe2</citation> and run it as MWE2Workflow. All model files in the model directory will be generated.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld06.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>The code will be generated to the src-gen directory. The main function will be contained in
<citation>SubSystem_HelloWorldRunner.java</citation>. Select this file and run it as Java application.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld07.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>The Hello World application starts and the string will be printed on the console window. To stop the application the user must type
<citation>quit</citation> in the console window.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld08.PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="OpentheMessageSequenceChart">
<title>Open the Message Sequence Chart</title>
<para>During runtime the application produced a MSC and wrote it to a file. Open /org.eclipse.etrice.doc.tutorials/tmp/log/SubSystem_HelloWorld_Async.seq using Trace2UML (it is open source and can be obtained from http://trace2uml.tigris.org/). You should see something like this:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/015-HelloWorld09.PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="Summary">
<title>Summary</title>
<para>Now you have generated your first eTrice model from scratch. You can switch between diagram editor and model (.room file) and you can see what will be generated during editing and saving the diagram files.
You should take a look at the generated source files to understand how the state machine is generated and the life cycle of the application. The next tutorials will deal with more complex hierarchies in structure and behavior.</para>
</section>
</chapter>
<chapter id="TutorialBlinky">
<title>Tutorial Blinky</title>
<section id="Scope2">
<title>Scope</title>
<para>This tutorial describes how to use the
<citation>TimingService</citation>, how to combine a generated model with manual code and how to model a hierarchical state machine. The idea of the tutorial is to switch a LED on and off. The behavior of the LED should be: blinking in a one second interval for 5 seconds, stop blinking for 5 seconds, blinking, stop,...
For this exercise we will use a little GUI class that will be used in more sophisticated tutorials too. The GUI simulates a pedestrian traffic crossing. For now, just a simple LED simulation will be used from the GUI.
</para>
<para>To use the GUI please copy the package
<citation>de.protos.PedLightGUI</citation> to your
<citation>src</citation> directory. The package contains four java classes which implement a small window with a 3-light traffic light which simulates the signals for the car traffic and a 2-light traffic light which simulates the pedestrian signals.
</para>
<para>The GUI looks like this:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky08.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Within this tutorial we just will toggle the yellow light.</para>
<para>You will perform the following steps:</para>
<orderedlist>
<listitem>
<para>create a new model from scratch</para>
</listitem>
<listitem>
<para>define a protocol</para>
</listitem>
<listitem>
<para>create an actor structure</para>
</listitem>
<listitem>
<para>create a hierarchical state machine</para>
</listitem>
<listitem>
<para>use the predefined
<citation>TimingService</citation>
</para>
</listitem>
<listitem>
<para>combine manual code with generated code</para>
</listitem>
<listitem>
<para>build and run the model</para>
</listitem>
<listitem>
<para>open the message sequence chart</para>
</listitem>
</orderedlist>
</section>
<section id="Createanewmodelfromscratch2">
<title>Create a new model from scratch</title>
<para>Remember exercise
<citation>HelloWorld</citation>.
Create a new eTrice project and name it
<citation>Blinky</citation>
Open the
<citation>Blinky.room</citation> file and copy the following code into the file or use content assist to create the model.
</para>
<literallayout><code>RoomModel Blinky {
LogicalSystem System_Blinky {
SubSystemRef subsystem : SubSystem_Blinky
}
SubSystemClass SubSystem_Blinky {
ActorRef application : BlinkyTop
}
ActorClass BlinkyTop {
}
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
</section>
<section id="Addtwoadditionalactorclasses">
<title>Add two additional actor classes</title>
<para>Position the cursor outside any class definition and right click the mouse within the editor window. From the context menu select
<citation>Content Assist</citation>
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky02.png"/>
</imageobject>
</mediaobject>
</para>
<para>Select
<citation>ActorClass – actor class skeleton</citation> and name it
<citation>Blinky</citation>.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky01.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Repeat the described procedure and name the new actor
<citation>BlinkyController</citation>.
</para>
<para>Save the model and visit the outline view.</para>
</section>
<section id="Createanewprotocol">
<title>Create a new protocol</title>
<para>With the help of
<citation>Content Assist</citation> create a
<citation>ProtocolClass</citation> and name it
<citation>BlinkyControlProtocol</citation>.
Inside the brackets use the
<citation>Content Assist</citation> (CTRL+Space) to create two incoming messages called
<citation>start</citation> and
<citation>stop</citation>.
</para>
<para>The resulting code should look like this:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky03.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>With Ctrl-Shift+F or selecting
<citation>Format</citation> from the context menu you can format the text. Note that all elements are displayed in the outline view.
</para>
</section>
<section id="ImporttheTimingService">
<title>Import the Timing Service</title>
<para>Switching on and off the LED is timing controlled. Therefore a timing service is needed. To import the timing service in the outline view right click to
<citation>SubSystem_Blinky</citation>. Select
<citation>Edit Structure</citation>. Drag and Drop an
<citation>ActorRef</citation> to the
<citation>SubSystem_Blinky</citation> and name it
<citation>application</citation>. From the actor class drop down list select
<citation>BlinkyTop</citation>. Do the same clicks for the timing service. Name it
<citation>timingService</citation> and from the drop down list select
<citation>room.basic.service.timing.ATimingService</citation>. Draw a
<citation>LayerConnection</citation> from
<citation>application</citation> to each service provision point (SPP) of the
<citation>timingService</citation>. The resulting structure should look like this:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky06.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>The current version of eTrice does not provide a graphical element for a service access point (SAP). Therefore the SAPs to access the timing service must be added in the .room file. Open the
<citation>Blinky.room</citation> file and navigate to the
<citation>Blinky</citation> actor. Add the following line to the structure of the actor:
</para>
<literallayout><code>SAP timer: room.basic.service.timing.PTimeout
</code></literallayout>
<para>Do the same thing for
<citation>BlinkyController</citation>.
</para>
<para>The resulting code should look like this:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky07.PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="Finishthemodelstructure">
<title>Finish the model structure</title>
<para>From the outline view right click to
<citation>Blinky</citation> and select
<citation>Edit Structure</citation>. Drag and Drop an
<citation>Interface Port</citation> to the boarder of the
<citation>Blinky</citation> actor. Note that an interface port is not possible inside the the actor. Name the port
<citation>ControlPort</citation> and select
<citation>BlinkyControlProtocol</citation> from the drop down list. Uncheck
<citation>Conjugated</citation> and
<citation>Is Relay Port</citation>. Klick
<citation>ok</citation>. The resulting structure should look like this:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky04.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Repeat the above steps for the
<citation>BlinkyController</citation>. Make the port
<citation>Conjugated</citation>
</para>
<para>Keep in mind that the protocol defines
<citation>start</citation> and
<citation>stop</citation> as incoming messages.
<citation>Blinky</citation> receives this messages and therefore
<citation>Blinky</citation>'s
<citation>ControlPort</citation> must be a regular port and
<citation>BlinkyController</citation>'s
<citation>ControlPort</citation> must be a conjugated port.
</para>
<para>From the outline view right click
<citation>BlinkyTop</citation> and select
<citation>Edit Structure</citation>.
</para>
<para>Drag and Drop an
<citation>ActorRef</citation> inside the
<citation>BlinkyTop</citation> actor. Name it
<citation>blinky</citation>. From the actor class drop down list select
<citation>Blinky</citation>. Do the same for
<citation>controller</citation>. Connect the ports via the binding tool. The resulting structure should look like this:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky05.PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="ImplementtheBehavior">
<title>Implement the Behavior</title>
<para>The application should switch on and off the LED for 5 seconds in a 1 second interval, than stop blinking for 5 seconds and start again. To implement this behavior we will implement two FSMs. One for the 1 second interval and one for the 5 second interval. The 1 second blinking should be implemented in
<citation>Blinky</citation>. The 5 second interval should be implemented in
<citation>BlinkyController</citation>. First implement the Controller.
</para>
<para>Right click to
<citation>BlinkyController</citation> and select
<citation>Edit Behavior</citation>.
Drag and Drop the
<citation>Initial Point</citation> and two
<citation>States</citation> into the top state. Name the states
<citation>on</citation> and
<citation>off</citation>.
Use the
<citation>Transition</citation> tool to draw transitions from
<citation>init</citation> to
<citation>off</citation> from
<citation>on</citation> to
<citation>off</citation> and from
<citation>off</citation> to
<citation>on</citation>.
</para>
<para>Open the transition dialog by double click the arrow to specify the trigger event and the action code of each transition. Note that the initial transition does not have a trigger event.</para>
<para>The dialog should look like this:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky09.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>The defined ports will be generated as a member attribute of the actor class from type of the attached protocol. So, to send e message you must state
<citation>port.message(param);</citation>. In this example
<citation>ControlPort.start()</citation> sends the
<citation>start</citation> message via the
<citation>ControlPort</citation> to the outside world. Assuming that
<citation>Blinky</citation> is connected to this port, the message will start the one second blinking FSM. It is the same thing with the
<citation>timer</citation>. The SAP is also a port and follows the same rules. So it is clear that
<citation>timer.Start(5000);</citation> will send the
<citation>Start</citation> message to the timing service. The timing service will send a
<citation>timeoutTick</citation> message back after 5000ms.
</para>
<para>Within each transition the timer will be restarted and the appropriate message will be sent via the
<citation>ControlPort</citation>.
</para>
<para>The resulting state machine should look like this:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky10.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Save the diagram and inspect the
<citation>Blinky.room</citation> file. The
<citation>BlinkyController</citation> should look like this:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky11.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Now we will implement
<citation>Blinky</citation>. Due to the fact that
<citation>Blinky</citation> interacts with the GUI class a view things must to be done in the model file.
</para>
<para>Double click
<citation>Blinky</citation> in the outline view to navigate to
<citation>Blinky</citation> within the model file.
Add the following code:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky12.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>
<citation>usercode1</citation> will be generated at the beginning of the file, outside the class definition.
<citation>usercode2</citation> will be generated within the class definition. The code imports the GUI class and instantiates the window class. Attributes for the carLights and pedLights will be declared to easily access the lights in the state machine.
The Operation
<citation>destroyUser()</citation> is a predefined operation that will be called during shutdown of the application. Within this operation, cleanup of manual coded classes can be done.
</para>
<para>Now design the FSM of
<citation>Blinky</citation>. Open the behavior diagram of
<citation>Blinky</citation> by right clicking the
<citation>Blinky</citation> actor in the outline view. Create two states named
<citation>blinking</citation> and
<citation>off</citation>. Right click to
<citation>blinking</citation> and create a subgraph.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky13.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Create the following state machine. The trigger events between
<citation>on</citation> and
<citation>off</citation> are the
<citation>timeoutTick</citation> from the
<citation>timer</citation> port.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky14.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Create entry code for both states by right clicking the state and select
<citation>Edit State...</citation>
</para>
<para>Entry code of
<citation>on</citation> is:
</para>
<literallayout><code>timer.Start(1000);
carLights.setState(TrafficLight3.YELLOW);
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>Entry code of
<citation>off</citation> is:
</para>
<literallayout><code>timer.Start(1000);
carLights.setState(TrafficLight3.OFF);
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>Navigate to the Top level state by double clicking the
<citation>/blinking</citation> state. Create the following state machine:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky15.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>The trigger event from
<citation>off</citation> to
<citation>blinking</citation> is the
<citation>start</citation> event from the
<citation>ControlPort</citation>.The trigger event from
<citation>blinking</citation> to
<citation>off</citation> is the
<citation>stop</citation> event from the
<citation>ControlPort</citation>.
</para>
<para>Action code of the init transition is:</para>
<literallayout><code>carLights = light.getCarLights();
pedLights = light.getPedLights();
carLights.setState(TrafficLight3.OFF);
pedLights.setState(TrafficLight2.OFF);
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>Action code from
<citation>blinking</citation> to
<citation>off</citation> is:
</para>
<literallayout><code>timer.Kill();
carLights.setState(TrafficLight3.OFF);
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>The complete resulting model looks like this:</para>
<literallayout><code>RoomModel Blinky {
LogicalSystem System_Blinky {
SubSystemRef subsystem: SubSystem_Blinky
}
SubSystemClass SubSystem_Blinky {
ActorRef application: BlinkyTop
ActorRef timingService: room.basic.service.timing.ATimingService
LayerConnection ref application satisfied_by timingService.timer
LayerConnection ref application satisfied_by timingService.timeout
}
ActorClass BlinkyTop {
Structure {
ActorRef blinky: Blinky
ActorRef controller: BlinkyController
Binding blinky.ControlPort and controller.ControlPort
}
Behavior { }
}
ActorClass Blinky {
Interface {
Port ControlPort: BlinkyControlProtocoll
}
Structure {
usercode1{
"import de.protos.PedLightGUI.*;"
}
usercode2 {
"private PedestrianLightWndNoTcp light = new PedestrianLightWndNoTcp();"
"private TrafficLight3 carLights;"
"private TrafficLight2 pedLights;"
}
external Port ControlPort
SAP timer: room.basic.service.timing.PTimeout
}
Behavior {
Operation destroyUser(){
"light.closeWindow();"
}
StateMachine {
Transition init: initial -> off {
action {
"carLights = light.getCarLights();"
"pedLights = light.getPedLights();"
"carLights.setState(TrafficLight3.OFF);"
"pedLights.setState(TrafficLight2.OFF);"
}
}
Transition tr0: off -> tp0 of blinking {
triggers {
<start: ControlPort>
}
}
Transition tr1: blinking -> off {
triggers {
<stop: ControlPort>
}
action {
"timer.Kill();"
"carLights.setState(TrafficLight3.OFF);"
}
}
State off
State blinking {
subgraph {
Transition tr0: my tp0 -> on
Transition tr1: on -> off {
triggers {
<timeoutTick: timer>
}
}
Transition tr2: off -> on {
triggers {
<timeoutTick: timer>
}
}
Transition init: initial -> on { }
EntryPoint tp0
State on {
entry {
"timer.Start(1000);"
"carLights.setState(TrafficLight3.YELLOW);"
}
}
State off {
entry {
"timer.Start(1000);"
"carLights.setState(TrafficLight3.OFF);"
}
}
}
}
}
}
}
ActorClass BlinkyController {
Interface {
conjugated Port ControlPort: BlinkyControlProtocoll
}
Structure {
external Port ControlPort
SAP timer: room.basic.service.timing.PTimeout
}
Behavior {
StateMachine {
Transition init: initial -> on {
action {
"timer.Start(5000);"
"ControlPort.start();"
}
}
Transition goOff: on -> off {
triggers {
<timeoutTick: timer>
}
action {
"ControlPort.stop();"
"timer.Start(5000);"
}
}
Transition goOn: off -> on {
triggers {
<timeoutTick: timer|timeoutTick: timer>
}
action {
"ControlPort.start();"
"timer.Start(5000);"
}
}
State on
State off
}
}
}
ProtocolClass BlinkyControlProtocoll {
incoming {
Message start()
Message stop()
}
outgoing { }
}
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>The model is complete now. You can run and debug the model as described in getting started. Have fun.</para>
</section>
<section id="Summary2">
<title>Summary</title>
<para>Run the model and take a look at the generated MSCs. Inspect the generated code to understand the runtime model of eTrice. Within this tutorial you have learned how to create a hierarchical FSM with group transitions and history transitions and you have used entry code. You are now familiar with the basic features of eTrice. The further tutorials will take this knowledge as a precondition.</para>
</section>
</chapter>
<chapter id="TutorialSendingData">
<title>Tutorial Sending Data</title>
<section id="Scope3">
<title>Scope</title>
<para>This tutorial shows how data will be sent in a eTrice model. Within the example you will create two actors (MrPing and MrPong). MrPong will simply loop back every data it received.
MrPing will send data and verify the result. </para>
<para>You will perform the following steps:</para>
<orderedlist>
<listitem>
<para>create a new model from scratch</para>
</listitem>
<listitem>
<para>create a data class</para>
</listitem>
<listitem>
<para>define a protocol with attached data</para>
</listitem>
<listitem>
<para>create an actor structure</para>
</listitem>
<listitem>
<para>create two simple state machines</para>
</listitem>
<listitem>
<para>build and run the model</para>
</listitem>
</orderedlist>
</section>
<section id="Createanewmodelfromscratch3">
<title>Create a new model from scratch</title>
<para>Remember exercise
<citation>HelloWorld</citation>.
Create a new eTrice project and name it
<citation>SendingData</citation>
Open the
<citation>SendingData.room</citation> file and copy the following code into the file or use content assist to create the model.
</para>
<literallayout><code>RoomModel SendingData {
LogicalSystem SendingData_LogSystem {
SubSystemRef SendingDataAppl:SendingData_SubSystem
}
SubSystemClass SendingData_SubSystem {
ActorRef SendigDataTopRef:SendingDataTop
}
ActorClass SendingDataTop {
}
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
</section>
<section id="Addadataclass">
<title>Add a data class</title>
<para>Position the cursor outside any class definition and right click the mouse within the editor window. From the context menu select
<citation>Content Assist</citation> (or Ctrl+Space).
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData01.png"/>
</imageobject>
</mediaobject>
</para>
<para>Select
<citation>DataClass – data class skeleton</citation> and name it
<citation>DemoData</citation>.
Remove the operations and ass the following Attributes:
</para>
<literallayout><code> DataClass DemoData {
Attribute int32Val: int32 = "4711"
Attribute int8Array [ 10 ]: int8 = "{1,2,3,4,5,6,7,8,9,10}"
Attribute float64Val: float64 = "0.0"
Attribute stringVal: string = "\"empty\""
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>Save the model and visit the outline view.
Note that the outline view contains all data elements as defined in the model. </para>
</section>
<section id="Createanewprotocol2">
<title>Create a new protocol</title>
<para>With the help of
<citation>Content Assist</citation> create a
<citation>ProtocolClass</citation> and name it
<citation>PingPongProtocol</citation>. Create the following messages:
</para>
<literallayout><code>ProtocolClass PingPongProtocol {
incoming {
Message ping(data: DemoData)
Message pingSimple(data:int32)
}
outgoing {
Message pong(data: DemoData)
Message pongSimple(data:int32)
}
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
</section>
<section id="CreateMrPingandMrPongActors">
<title>Create MrPing and MrPong Actors</title>
<para>With the help of
<citation>Content Assist</citation> create two new actor classes and name them
<citation>MrPing</citation> and
<citation>MrPong</citation>. The resulting model should look like this:
</para>
<literallayout><code>RoomModel SendingData {
LogicalSystem SendingData_LogSystem {
SubSystemRef SendingDataAppl: SendingData_SubSystem
}
SubSystemClass SendingData_SubSystem {
ActorRef SendigDataTopRef: SendingDataTop
}
ActorClass SendingDataTop { }
DataClass DemoData {
Attribute int32Val: int32 = "4711"
Attribute int8Array [ 10 ]: int8 = "{1,2,3,4,5,6,7,8,9,10}"
Attribute float64Val: float64 = "0.0"
Attribute stringVal: string = "\"empty\""
}
ProtocolClass PingPongProtocol {
incoming {
Message ping(data: DemoData)
Message pingSimple(data: int32)
}
outgoing {
Message pong(data: DemoData)
Message pongSimple(data: int32)
}
}
ActorClass MrPing {
Interface { }
Structure { }
Behavior { }
}
ActorClass MrPong {
Interface { }
Structure { }
Behavior { }
}
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>The outline view should look like this:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData03.png"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="DefineActorStructureandBehavior">
<title>Define Actor Structure and Behavior</title>
<para>Save the model and visit the outline view. Within the outline view, right click on the
<citation>MrPong</citation> actor and select
<citation>Edit Structure</citation>. Select an
<citation>Interface Port</citation> from the toolbox and add it to MrPong. Name the Port
<citation>PingPongPort</citation> and select the
<citation>PingPongProtocol</citation>
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData02.png"/>
</imageobject>
</mediaobject>
</para>
<para>Do the same with MrPing but mark the port as
<citation>conjugated</citation>
</para>
<section id="DefineMrPongsbehavior">
<title>Define MrPongs behavior</title>
<para>Within the outline view, right click MrPong and select
<citation>Edit Behavior</citation>. Create the following state machine:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData04.png"/>
</imageobject>
</mediaobject>
</para>
<para>The transition dialogues should look like this:
For
<citation>ping</citation>:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData05.png"/>
</imageobject>
</mediaobject>
</para>
<para>For
<citation>pingSimple</citation>:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData06.png"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="DefineMrPingbehavior">
<title>Define MrPing behavior</title>
<para>Within the outline view double click MrPing. Navigate the cursor to the behavior of MrPing. With the help of content assist create a new operation.</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData07.png"/>
</imageobject>
</mediaobject>
</para>
<para>Name the operation
<citation>printData</citation> and define the DemoData as a parameter.
</para>
<para>Fill in the following code:</para>
<literallayout><code>Operation printData(d: DemoData) : void {
"System.out.printf(\"d.int32Val: %d\\n\",d.int32Val);"
"System.out.printf(\"d.float64Val: %f\\n\",d.float64Val);"
"System.out.printf(\"d.int8Array: \");"
"for(int i = 0; i<d.int8Array.length; i++) {"
"System.out.printf(\"%d \",d.int8Array[i]);}"
"System.out.printf(\"\\nd.stringVal: %s\\n\",d.stringVal);"
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>For MrPing create the following state machine:</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData08.png"/>
</imageobject>
</mediaobject>
</para>
<para>The transition dialogues should look like this:</para>
<para>For
<citation>init</citation>:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData09.png"/>
</imageobject>
</mediaobject>
</para>
<para>For
<citation>wait1</citation>:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData10.png"/>
</imageobject>
</mediaobject>
</para>
<para>For
<citation>next</citation>:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData11.png"/>
</imageobject>
</mediaobject>
</para>
<para>For
<citation>wait2</citation>:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData12.png"/>
</imageobject>
</mediaobject>
</para>
</section>
</section>
<section id="Definethetoplevel">
<title>Define the top level</title>
<para>Open the Structure from SendingDataTop and add MrPing and MrPong as a reference. Connect the ports.</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/025-SendingData13.png"/>
</imageobject>
</mediaobject>
</para>
<para>The model is finished now and the model file should look like this:</para>
<literallayout><code>RoomModel SendingData {
LogicalSystem SendingData_LogSystem {
SubSystemRef SendingDataAppl: SendingData_SubSystem
}
SubSystemClass SendingData_SubSystem {
ActorRef SendigDataTopRef: SendingDataTop
}
ActorClass SendingDataTop {
Structure {
ActorRef ref0: MrPing
ActorRef ref1: MrPong
Binding ref0.PingPongPort and ref1.PingPongPort
}
Behavior { }
}
ActorClass MrPing {
Interface {
conjugated Port PingPongPort: PingPongProtocol
}
Structure {
external Port PingPongPort
}
Behavior {
Operation printData(d: DemoData) : void {
"System.out.printf(\"d.int32Val: %d\\n\",d.int32Val);"
"System.out.printf(\"d.float64Val: %f\\n\",d.float64Val);"
"System.out.printf(\"d.int8Array: \");"
"for(int i = 0; i<d.int8Array.length; i++) {"
"System.out.printf(\"%d \",d.int8Array[i]);}"
"System.out.printf(\"\\nd.stringVal: %s\\n\",d.stringVal);"
}
StateMachine {
Transition wait2: waitForPong -> waitForPong {
triggers {
<pong: PingPongPort>
}
action {
"printData(data);"
}
}
Transition wait1: waitForPongSimple -> waitForPongSimple {
triggers {
<pongSimple: PingPongPort guard {
"data < 10"
}>
}
action {
"// keep in mind that MrPong increments"
"PingPongPort.pingSimple(data);"
"System.out.printf(\"data: %d\\n\",data);"
}
}
Transition next: waitForPongSimple -> waitForPong {
triggers {
<pongSimple: PingPongPort>
}
action {
"System.out.printf(\"data: %d\\n\",data);"
""
"DemoData d = new DemoData();"
"// send the default values"
"PingPongPort.ping(d);"
"d.int32Val=815;"
"for (int i = 0; i<d.int8Array.length;i++){"
"\td.int8Array[i]=(byte)(i+100);"
"\t}"
"d.stringVal=\"some contents\";"
"d.float64Val=3.141234;"
"PingPongPort.ping(d);"
}
}
Transition init0: initial -> waitForPongSimple {
action {
"PingPongPort.pingSimple(0);"
}
}
State waitForPong
State waitForPongSimple
}
}
}
ActorClass MrPong {
Interface {
Port PingPongPort: PingPongProtocol
}
Structure {
external Port PingPongPort
}
Behavior {
StateMachine {
Transition init: initial -> looping { }
Transition tr0: looping -> looping {
triggers {
<ping: PingPongPort>
}
action {
"PingPongPort.pong(data);"
}
}
Transition tr1: looping -> looping {
triggers {
<pingSimple: PingPongPort>
}
action {
"PingPongPort.pongSimple(data+1);"
}
}
State looping
}
}
}
ProtocolClass PingPongProtocol {
incoming {
Message ping(data: DemoData)
Message pingSimple(data: int32)
}
outgoing {
Message pong(data: DemoData)
Message pongSimple(data: int32)
}
}
DataClass DemoData {
Attribute int32Val: int32 = "4711"
Attribute int8Array [ 10 ]: int8 = "{1,2,3,4,5,6,7,8,9,10}"
Attribute float64Val: float64 = "0.0"
Attribute stringVal: string = "\"empty\""
}
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
</section>
<section id="Generateandrunthemodel">
<title>Generate and run the model</title>
<para>With the MWe2 workflow generate the code and run the model.
The output should look like this:</para>
<blockquote>
<para>
type ‚quit’ to exit
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 1
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 2
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 3
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 4
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 5
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 6
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 7
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 8
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 9
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPongSimple
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
data: 10
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPong
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
/SendingData_SubSystem/SendigDataTopRef/ref1 -> looping
d.int32Val: 4711
d.float64Val: 0,000000
d.int8Array: 1 2 3 4 5 6 7 8 9 10
d.stringVal: empty
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPong
d.int32Val: 815
d.float64Val: 3,141234
d.int8Array: 100 101 102 103 104 105 106 107 108 109
d.stringVal: some contents
/SendingData_SubSystem/SendigDataTopRef/ref0 -> waitForPong
quit
echo: quit</para>
</blockquote>
<blockquote>
<para></para>
</blockquote>
</section>
<section id="Summary3">
<title>Summary</title>
<para>Within the first loop an integer value will be incremented from
<citation>MrPong</citation> and sent back to
<citation>MrPing</citation>. As long as the guard is true
<citation>MrPing</citation> sends back the value.
</para>
<para>Within the
<citation>next</citation> transition,
<citation>MrPing</citation> creates a data class and sends the default values. Than
<citation>MrPing</citation> changes the values and sends the class again. At this point you should note that during the send operation, a copy of the data class will be created and sent. Otherwise it would not be possible to send the same object two times, even more it would not be possible to send a stack object at all.
In future versions of eTrice an additional mechanism to send references will be implemented. However, keep in mind that sending references transfers the responsibility of the life cycle of the sent object to the user. It looks simple but is a very common source of failures.
</para>
</section>
</chapter>
<chapter id="TutorialPedestrianLights">
<title>Tutorial Pedestrian Lights</title>
<section id="Scope4">
<title>Scope</title>
<para>The scope of this tutorial is to demonstrate how to receive model messages from outside the model. Calling methods which are not part of the model is simple and you have already done this within the blinky tutorial (this is the other way round: model => external code). Receiving events from outside the model is a very common problem and a very frequently asked question. Therefore this tutorial shows how an external event (outside the model) can be received from the model.</para>
<para>This tutorial is not like hello world or blinky. Being familiar with the basic tool features is mandatory for this tutorial. The goal is to understand the mechanism not to learn the tool features.</para>
<para>The idea behind the exercise is, to control a Pedestrian crossing light. We will use the same GUI as for the blinky tutorial but now we will use the
<citation>REQUEST</citation> button to start a FSM, which controls the traffic lights.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/020-Blinky08.PNG"/>
</imageobject>
</mediaobject>
</para>
<para>The
<citation>REQUEST</citation> must lead to a model message which starts the activity of the lights.
</para>
<para>There are several possibilities to receive external events (e.g. TCP/UDP Socket, using OS messaging mechanism), but the easiest way is, to make a port usable from outside the model. To do that a few steps are necessary:</para>
<orderedlist>
<listitem>
<para>specify the messages (within a protocol) which should be sent into the model</para>
</listitem>
<listitem>
<para>model an actor with a port (which uses the specified protocol) and connect the port to the receiver </para>
</listitem>
<listitem>
<para>the external code should know the port (import of the port class)</para>
</listitem>
<listitem>
<para>the external code should provide a registration method, so that the actor is able to allow access to this port</para>
</listitem>
<listitem>
<para>the port can be used from the external code</para>
</listitem>
</orderedlist>
</section>
<section id="Setupthemodel">
<title>Setup the model</title>
<itemizedlist>
<listitem>
<para>Use the
<citation>New Model Wizzard</citation> to create a new eTrice project and name it
<citation>PedLightsController</citation>.
</para>
</listitem>
<listitem>
<para>Copy the package
<citation>de.protos.PedLightGUI</citation> to your
<citation>src</citation> directory (see blinky tutorial).
</para>
</listitem>
<listitem>
<para>In PedestrianLightWndNoTcp.jav uncomment line 15 (import), 36, 122 (usage) and 132-134 (registration).</para>
</listitem>
<listitem>
<para>Copy the following model to your model file:</para>
</listitem>
</itemizedlist>
<literallayout><code>RoomModel PedLightsController {
LogicalSystem LogSys_PedLights {
SubSystemRef application: SubSys_PedLights
}
SubSystemClass SubSys_PedLights {
ActorRef PedLightsTopRef: PedLightsTop
ActorRef timingService: room.basic.service.timing.ATimingService
LayerConnection ref PedLightsTopRef satisfied_by timingService.timer
LayerConnection ref PedLightsTopRef satisfied_by timingService.timeout
}
ActorClass PedLightsTop {
Structure {
ActorRef adapter: GuiAdapter
ActorRef controller: Controller
Binding adapter.ControlPort and controller.ControlPort
}
Behavior { }
}
ActorClass GuiAdapter {
Interface {
conjugated Port ControlPort: PedControlProtocol
}
Structure {
usercode1 {
"import PedLightGUI.*;"
}
usercode2 {
"private PedestrianLightWndNoTcp lights = new PedestrianLightWndNoTcp(\"Pedestrian Lights\",\" external port connection \");"
"private TrafficLight3 carLights;"
"private TrafficLight2 pedLights;"
}
external Port ControlPort
}
Behavior {
Operation destroyUser() {
"lights.closeWindow();"
}
StateMachine {
Transition init: initial -> running {
action {
"carLights=lights.getCarLights();"
"pedLights=lights.getPedLights();"
"carLights.setState(TrafficLight3.OFF);"
"pedLights.setState(TrafficLight2.OFF);"
"lights.setPort(ControlPort);"
}
}
Transition tr0: running -> running {
triggers {
<setCarLights: ControlPort>
}
action {
"carLights.setState(state);"
}
}
Transition tr1: running -> running {
triggers {
<setPedLights: ControlPort>
}
action {
"pedLights.setState(state);"
}
}
State running
}
}
}
ActorClass Controller {
Interface {
Port ControlPort: PedControlProtocol
}
Structure {
usercode1 {
"import PedLightGUI.*;"
}
external Port ControlPort
SAP timer: room.basic.service.timing.PTimeout
}
Behavior {
StateMachine {
Transition init: initial -> off { }
Transition tr0: off -> carsGreen {
triggers {
<start: ControlPort>
}
action {
"timer.Start(700);"
"ControlPort.setCarLights(TrafficLight3.GREEN);"
"ControlPort.setPedLights(TrafficLight2.RED);"
}
}
Transition tr1: carsGreen -> carsYellow {
triggers {
<timeoutTick: timer>
}
action {
"timer.Start(700);"
"ControlPort.setCarLights(TrafficLight3.YELLOW);"
"ControlPort.setPedLights(TrafficLight2.RED);"
}
}
Transition tr2: carsYellow -> carsRed {
triggers {
<timeoutTick: timer>
}
action {
"timer.Start(1500);"
"ControlPort.setCarLights(TrafficLight3.RED);"
"ControlPort.setPedLights(TrafficLight2.GREEN);"
}
}
Transition tr3: carsRed -> carsYellowRed {
triggers {
<timeoutTick: timer>
}
action {
"timer.Start(700);"
"ControlPort.setCarLights(TrafficLight3.YELLOW_RED);"
"ControlPort.setPedLights(TrafficLight2.RED);"
}
}
Transition tr4: carsYellowRed -> carsGreen2 {
triggers {
<timeoutTick: timer>
}
action {
"timer.Start(700);"
"ControlPort.setCarLights(TrafficLight3.GREEN);"
"ControlPort.setPedLights(TrafficLight2.RED);"
}
}
Transition tr5: carsGreen2 -> off {
triggers {
<timeoutTick: timer>
}
action {
"ControlPort.setCarLights(TrafficLight3.OFF);"
"ControlPort.setPedLights(TrafficLight2.OFF);"
}
}
State off
State carsGreen
State carsYellow
State carsRed
State carsYellowRed
State carsGreen2
}
}
}
ProtocolClass PedControlProtocol {
incoming {
Message start()
}
outgoing {
Message setCarLights(state: int32)
Message setPedLights(state: int32)
}
}
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<itemizedlist>
<listitem>
<para>Arrange the Structure and the Statemachines to understand the model </para>
</listitem>
</itemizedlist>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/030-PedLights01.PNG"/>
</imageobject>
</mediaobject>
The
<citation>GuiAdapter</citation> represents the interface to the external code. It registers its
<citation>ControlPort</citation> by the external code.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/030-PedLights02.PNG"/>
</imageobject>
</mediaobject>
Visit the initial transition to understand the registration. The actor handles the incoming messages as usual and controls the traffic lights as known from blinky.
</para>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/030-PedLights03.PNG"/>
</imageobject>
</mediaobject>
The
<citation>Controller</citation> receives the
<citation>start</citation> message and controls the timing of the lights. Note that the
<citation>start</citation> message will be sent from the external code whenever the
<citation>REQUEST</citation> button is pressed.
</para>
<itemizedlist>
<listitem>
<para> Visit the model and take a closer look to the following elements:</para>
</listitem>
</itemizedlist>
<orderedlist>
<listitem>
<para>PedControlProtocol => notice that the start message is defined as usual</para>
</listitem>
<listitem>
<para>Initial transition of the
<citation>GuiAdapter</citation> => see the registration
</para>
</listitem>
<listitem>
<para>The
<citation>Controller</citation> => notice that the
<citation>Controller</citation> receives the external message (not the
<citation>GuiAdapter</citation>). The
<citation>GuiAdapter</citation> just provides its port and handles the incoming messages.
</para>
</listitem>
<listitem>
<para>Visit the hand written code => see the import statement of the protocol class and the usage of the port.</para>
</listitem>
</orderedlist>
<itemizedlist>
<listitem>
<para>Generate and test the model</para>
</listitem>
<listitem>
<para>Take a look at the generated MSC => notice that the start message will shown as if the
<citation>GuiAdapter</citation> had sent it.
</para>
</listitem>
</itemizedlist>
<para>
<mediaobject>
<imageobject>
<imagedata fileref="images/030-PedLights04.PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="Whydoesitworkandwhyisitsafe">
<title>Why does it work and why is it safe?</title>
<para>The tutorial shows that it is generally possible to use every port from outside the model as long as the port knows its peer. This is guaranteed by describing protocol and the complete structure (especially the bindings) within the model.
The only remaining question is: Why is it safe and does not violate the „run to completion” semantic. To answer this question, take a look at the
<citation>MessageService.java</citation> from the runtime environment. There you will find the receive method which puts each message into the queue.
</para>
<literallayout><code> @Override
public synchronized void receive(Message msg) {
if (msg!=null) {
messageQueue.push(msg);
notifyAll(); // wake up thread to compute message
}
}
</code></literallayout>
<blockquote>
<para></para>
</blockquote>
<para>This method is synchronized. That means, regardless who sends the message, the queue is secured. If we later on (e.g. for performance reasons in C/C++) distinguish between internal and external senders (same thread or not), care must be taken to use the external (secure) queue.</para>
</section>
</chapter>
<chapter id="ROOMConcepts">
<title>ROOM Concepts</title>
<section id="MainConcepts">
<title>Main Concepts</title>
<section id="ActorClass">
<title>ActorClass</title>
</section>
<section id="Port">
<title>Port</title>
</section>
<section id="Protocol">
<title>Protocol</title>
</section>
</section>
</chapter>
</book>
