diff options
Diffstat (limited to 'plugins/org.eclipse.etrice.doc/html/etrice.html')
| -rw-r--r-- | plugins/org.eclipse.etrice.doc/html/etrice.html | 718 |
1 files changed, 715 insertions, 3 deletions
diff --git a/plugins/org.eclipse.etrice.doc/html/etrice.html b/plugins/org.eclipse.etrice.doc/html/etrice.html index 4696be669..a31da9355 100644 --- a/plugins/org.eclipse.etrice.doc/html/etrice.html +++ b/plugins/org.eclipse.etrice.doc/html/etrice.html @@ -100,7 +100,41 @@ </dl>
</dd>
<dt>
-<span class="chapter"><a href="#ROOMConcepts">5. ROOM Concepts</a></span>
+<span class="chapter"><a href="#TutorialSendingData">5. Tutorial Sending Data</a></span>
+</dt>
+<dd>
+<dl>
+<dt>
+<span class="section"><a href="#Scope3">Scope</a></span>
+</dt>
+<dt>
+<span class="section"><a href="#Createanewmodelfromscratch3">Create a new model from scratch</a></span>
+</dt>
+<dt>
+<span class="section"><a href="#Addadataclass">Add a data class</a></span>
+</dt>
+<dt>
+<span class="section"><a href="#Createanewprotocol2">Create a new protocol</a></span>
+</dt>
+<dt>
+<span class="section"><a href="#CreateMrPingandMrPongActors">Create MrPing and MrPong Actors</a></span>
+</dt>
+<dt>
+<span class="section"><a href="#DefinetheActorsStructureandBehavior">Define the Actors Structure and Behavior</a></span>
+</dt>
+<dt>
+<span class="section"><a href="#Definethetoplevel">Define the top level</a></span>
+</dt>
+<dt>
+<span class="section"><a href="#Generateandrunthemodel">Generate and run the model</a></span>
+</dt>
+<dt>
+<span class="section"><a href="#Summary3">Summary</a></span>
+</dt>
+</dl>
+</dd>
+<dt>
+<span class="chapter"><a href="#ROOMConcepts">6. ROOM Concepts</a></span>
</dt>
<dd>
<dl>
@@ -1151,12 +1185,690 @@ carLights.setState(TrafficLight3.OFF); <br> <p>Run the model and take 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.</p>
</div>
</div>
-<div class="chapter" title="Chapter 5. ROOM Concepts">
+<div class="chapter" title="Chapter 5. Tutorial Sending Data">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title">
+<a name="TutorialSendingData"></a>Chapter 5. Tutorial Sending Data</h2>
+</div>
+</div>
+</div>
+<div class="section" title="Scope">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title" style="clear: both">
+<a name="Scope3"></a>Scope</h2>
+</div>
+</div>
+</div>
+<p>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 sent data and verify the result. </p>
+<p>You will perform the following steps:</p>
+<div class="orderedlist">
+<ol class="orderedlist" type="1">
+<li class="listitem">
+<p>create a new model from scratch</p>
+</li>
+<li class="listitem">
+<p>create a data class</p>
+</li>
+<li class="listitem">
+<p>define a protocol with attached data</p>
+</li>
+<li class="listitem">
+<p>create an actor structure</p>
+</li>
+<li class="listitem">
+<p>create two simple state machines</p>
+</li>
+<li class="listitem">
+<p>build and run the model</p>
+</li>
+</ol>
+</div>
+</div>
+<div class="section" title="Create a new model from scratch">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title" style="clear: both">
+<a name="Createanewmodelfromscratch3"></a>Create a new model from scratch</h2>
+</div>
+</div>
+</div>
+<p>Remember exercise
+ [<span class="citation">HelloWorld</span>].
+ Create a new eTrice project and name it
+ [<span class="citation">SendingData</span>]
+ Open the
+ [<span class="citation">SendingData.room</span>] file and copy the following code into the file or use content assist to create the model.
+ </p>
+<div class="literallayout">
+<p>
+<code class="code">RoomModel SendingData {<br>
+ LogicalSystem SendingData_LogSystem {<br>
+ SubSystemRef SendingDataAppl:SendingData_SubSystem <br>
+ }<br>
+ SubSystemClass SendingData_SubSystem {<br>
+ ActorRef SendigDataTopRef:SendingDataTop <br>
+ }<br>
+ ActorClass SendingDataTop {<br>
+ }<br>
+ }<br>
+
+</code>
+</p>
+</div>
+<div class="blockquote">
+<blockquote class="blockquote">
+<p></p>
+</blockquote>
+</div>
+</div>
+<div class="section" title="Add a data class">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title" style="clear: both">
+<a name="Addadataclass"></a>Add a data class</h2>
+</div>
+</div>
+</div>
+<p>Position the cursor outside any class definition and right click the mouse within the editor window. From the context menu select
+ [<span class="citation">Content Assist</span>] (or Ctrl+Space).
+ </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData01.png"></div>
+<p>
+
+</p>
+<p>Select
+ [<span class="citation">DataClass – data class skeleton</span>] and name it
+ [<span class="citation">DemoData</span>].
+ Remove the operations and ass the following Attributes:
+ </p>
+<div class="literallayout">
+<p>
+<code class="code"> DataClass DemoData {<br>
+ Attribute int32Val: int32 = "4711"<br>
+ Attribute int8Array [ 10 ]: int8 = "{1,2,3,4,5,6,7,8,9,10}"<br>
+ Attribute float64Val: float64 = "0.0"<br>
+ Attribute stringVal: string = "\"empty\""<br>
+ }<br>
+
+</code>
+</p>
+</div>
+<div class="blockquote">
+<blockquote class="blockquote">
+<p></p>
+</blockquote>
+</div>
+<p>Save the model and visit the outline view.
+ Note that the outline view contains all data elements as defined in the model. </p>
+</div>
+<div class="section" title="Create a new protocol">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title" style="clear: both">
+<a name="Createanewprotocol2"></a>Create a new protocol</h2>
+</div>
+</div>
+</div>
+<p>With the help of
+ [<span class="citation">Content Assist</span>] create a
+ [<span class="citation">ProtocolClass</span>] and name it
+ [<span class="citation">PingPongProtocol</span>]. Create the following messages:
+ </p>
+<div class="literallayout">
+<p>
+<code class="code">ProtocolClass PingPongProtocol {<br>
+ incoming {<br>
+ Message ping(data: DemoData)<br>
+ Message pingSimple(data:int32)<br>
+ }<br>
+ outgoing {<br>
+ Message pong(data: DemoData)<br>
+ Message pongSimple(data:int32)<br>
+ }<br>
+ } <br>
+
+</code>
+</p>
+</div>
+<div class="blockquote">
+<blockquote class="blockquote">
+<p></p>
+</blockquote>
+</div>
+</div>
+<div class="section" title="Create MrPing and MrPong Actors">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title" style="clear: both">
+<a name="CreateMrPingandMrPongActors"></a>Create MrPing and MrPong Actors</h2>
+</div>
+</div>
+</div>
+<p>With the help of
+ [<span class="citation">Content Assist</span>] create two new actor classes and name them
+ [<span class="citation">MrPing</span>] and
+ [<span class="citation">MrPong</span>]. The resulting model should look like this:
+ </p>
+<div class="literallayout">
+<p>
+<code class="code">RoomModel SendingData {<br>
+
+<br>
+ LogicalSystem SendingData_LogSystem {<br>
+ SubSystemRef SendingDataAppl: SendingData_SubSystem<br>
+ }<br>
+
+<br>
+ SubSystemClass SendingData_SubSystem {<br>
+ ActorRef SendigDataTopRef: SendingDataTop<br>
+ }<br>
+
+<br>
+ ActorClass SendingDataTop { }<br>
+
+<br>
+ DataClass DemoData {<br>
+ Attribute int32Val: int32 = "4711"<br>
+ Attribute int8Array [ 10 ]: int8 = "{1,2,3,4,5,6,7,8,9,10}"<br>
+ Attribute float64Val: float64 = "0.0"<br>
+ Attribute stringVal: string = "\"empty\""<br>
+ }<br>
+
+<br>
+ ProtocolClass PingPongProtocol {<br>
+ incoming {<br>
+ Message ping(data: DemoData)<br>
+ Message pingSimple(data: int32)<br>
+ }<br>
+ outgoing {<br>
+ Message pong(data: DemoData)<br>
+ Message pongSimple(data: int32)<br>
+ }<br>
+ }<br>
+
+<br>
+ ActorClass MrPing {<br>
+ Interface { }<br>
+ Structure { }<br>
+ Behavior { }<br>
+ }<br>
+
+<br>
+ ActorClass MrPong {<br>
+ Interface { }<br>
+ Structure { }<br>
+ Behavior { }<br>
+ }<br>
+} <br>
+
+<br>
+
+</code>
+</p>
+</div>
+<div class="blockquote">
+<blockquote class="blockquote">
+<p></p>
+</blockquote>
+</div>
+<p>The outline view should look like this:</p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData03.png"></div>
+<p>
+
+</p>
+</div>
+<div class="section" title="Define the Actors Structure and Behavior">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title" style="clear: both">
+<a name="DefinetheActorsStructureandBehavior"></a>Define the Actors Structure and Behavior</h2>
+</div>
+</div>
+</div>
+<p>Save the model and visit the outline view. Within the outline view, right click on the
+ [<span class="citation">MrPong</span>] actor and select
+ [<span class="citation">Edit Structure</span>]. Select an
+ [<span class="citation">Interface Port</span>] from the toolbox and add it to MrPong. Name the Port
+ [<span class="citation">PingPongPort</span>] and select the
+ [<span class="citation">PingPongProtocol</span>]
+ </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData02.png"></div>
+<p>
+
+</p>
+<p>Do the same with MrPing but mark the port as
+ [<span class="citation">conjugated</span>]
+ </p>
+<div class="section" title="Define MrPongs behavior">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="DefineMrPongsbehavior"></a>Define MrPongs behavior</h3>
+</div>
+</div>
+</div>
+<p>Within the outline view, right click MrPong and select
+ [<span class="citation">Edit Behavior</span>]. Create the following state machine:
+ </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData04.png"></div>
+<p>
+
+</p>
+<p>The transition dialogues should look like this:
+ For
+ [<span class="citation">ping</span>]:
+ </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData05.png"></div>
+<p>
+
+</p>
+<p>For
+ [<span class="citation">pingSimple</span>]:
+ </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData06.png"></div>
+<p>
+
+</p>
+</div>
+<div class="section" title="Define MrPing behavior">
+<div class="titlepage">
+<div>
+<div>
+<h3 class="title">
+<a name="DefineMrPingbehavior"></a>Define MrPing behavior</h3>
+</div>
+</div>
+</div>
+<p>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.</p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData07.png"></div>
+<p>
+
+</p>
+<p>Name the operation
+ [<span class="citation">printData</span>] and define the DemoData as a parameter.
+ </p>
+<p>Fill in the following code:</p>
+<div class="literallayout">
+<p>
+<code class="code">Operation printData(d: DemoData) : void {<br>
+ "System.out.printf(\"d.int32Val: %d\\n\",d.int32Val);"<br>
+ "System.out.printf(\"d.float64Val: %f\\n\",d.float64Val);"<br>
+ "System.out.printf(\"d.int8Array: \");"<br>
+ "for(int i = 0; i<d.int8Array.length; i++) {"<br>
+ "System.out.printf(\"%d \",d.int8Array[i]);}"<br>
+ "System.out.printf(\"\\nd.stringVal: %s\\n\",d.stringVal);"<br>
+ }<br>
+
+</code>
+</p>
+</div>
+<div class="blockquote">
+<blockquote class="blockquote">
+<p></p>
+</blockquote>
+</div>
+<p>For MrPing create the following state machine:</p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData08.png"></div>
+<p>
+
+</p>
+<p>The transition dialogues should look like this:</p>
+<p>For
+ [<span class="citation">init</span>]:
+ </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData09.png"></div>
+<p>
+
+</p>
+<p>For
+ [<span class="citation">wait1</span>]:
+ </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData10.png"></div>
+<p>
+
+</p>
+<p>For
+ [<span class="citation">next</span>]:
+ </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData11.png"></div>
+<p>
+
+</p>
+<p>For
+ [<span class="citation">wait2</span>]:
+ </p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData12.png"></div>
+<p>
+
+</p>
+</div>
+</div>
+<div class="section" title="Define the top level">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title" style="clear: both">
+<a name="Definethetoplevel"></a>Define the top level</h2>
+</div>
+</div>
+</div>
+<p>Open the Structure from SendingDataTop and add MrPing and MrPong as a reference. Connect the ports.</p>
+<p>
+
+</p>
+<div class="mediaobject">
+<img src="images/025-SendingData13.png"></div>
+<p>
+
+</p>
+<p>The model is finished now and the model file should look like this:</p>
+<div class="literallayout">
+<p></p>
+</div>
+<div class="literallayout">
+<p>
+<code class="code">RoomModel SendingData {<br>
+
+<br>
+ LogicalSystem SendingData_LogSystem {<br>
+ SubSystemRef SendingDataAppl: SendingData_SubSystem<br>
+ }<br>
+
+<br>
+ SubSystemClass SendingData_SubSystem {<br>
+ ActorRef SendigDataTopRef: SendingDataTop<br>
+ }<br>
+
+<br>
+ ActorClass SendingDataTop {<br>
+ Structure {<br>
+ ActorRef ref0: MrPing<br>
+ ActorRef ref1: MrPong<br>
+ Binding ref0.PingPongPort and ref1.PingPongPort<br>
+ }<br>
+ Behavior { }<br>
+ }<br>
+
+<br>
+ ActorClass MrPing {<br>
+ Interface {<br>
+ conjugated Port PingPongPort: PingPongProtocol<br>
+ }<br>
+ Structure {<br>
+ external Port PingPongPort<br>
+ }<br>
+ Behavior {<br>
+
+<br>
+ Operation printData(d: DemoData) : void {<br>
+ "System.out.printf(\"d.int32Val: %d\\n\",d.int32Val);"<br>
+ "System.out.printf(\"d.float64Val: %f\\n\",d.float64Val);"<br>
+ "System.out.printf(\"d.int8Array: \");"<br>
+ "for(int i = 0; i<d.int8Array.length; i++) {"<br>
+ "System.out.printf(\"%d \",d.int8Array[i]);}"<br>
+ "System.out.printf(\"\\nd.stringVal: %s\\n\",d.stringVal);"<br>
+ }<br>
+
+<br>
+ StateMachine {<br>
+ Transition wait2: waitForPong -> waitForPong {<br>
+ triggers {<br>
+ <pong: PingPongPort><br>
+ }<br>
+ action {<br>
+ "printData(data);"<br>
+ }<br>
+ }<br>
+ Transition wait1: waitForPongSimple -> waitForPongSimple {<br>
+ triggers {<br>
+ <pongSimple: PingPongPort guard {<br>
+ "data < 10"<br>
+ }><br>
+ }<br>
+ action {<br>
+ "// keep in mind that MrPong increments"<br>
+ "PingPongPort.pingSimple(data);"<br>
+ "System.out.printf(\"data: %d\\n\",data);"<br>
+ }<br>
+ }<br>
+ Transition next: waitForPongSimple -> waitForPong {<br>
+ triggers {<br>
+ <pongSimple: PingPongPort><br>
+ }<br>
+ action {<br>
+ "System.out.printf(\"data: %d\\n\",data);"<br>
+ ""<br>
+ "DemoData d = new DemoData();"<br>
+ "// send the default values"<br>
+ "PingPongPort.ping(d);"<br>
+ "d.int32Val=815;"<br>
+ "for (int i = 0; i<d.int8Array.length;i++){"<br>
+ "\td.int8Array[i]=(byte)(i+100);"<br>
+ "\t}"<br>
+ "d.stringVal=\"some contents\";"<br>
+ "d.float64Val=3.141234;"<br>
+ "PingPongPort.ping(d);"<br>
+ }<br>
+ }<br>
+ Transition init0: initial -> waitForPongSimple {<br>
+ action {<br>
+ "PingPongPort.pingSimple(0);"<br>
+ }<br>
+ }<br>
+ State waitForPong<br>
+ State waitForPongSimple<br>
+ }<br>
+ }<br>
+ }<br>
+
+<br>
+ ActorClass MrPong {<br>
+ Interface {<br>
+ Port PingPongPort: PingPongProtocol<br>
+ }<br>
+ Structure {<br>
+ external Port PingPongPort<br>
+ }<br>
+ Behavior {<br>
+ StateMachine {<br>
+ Transition init: initial -> looping { }<br>
+ Transition tr0: looping -> looping {<br>
+ triggers {<br>
+ <ping: PingPongPort><br>
+ }<br>
+ action {<br>
+ "PingPongPort.pong(data);"<br>
+ }<br>
+ }<br>
+ Transition tr1: looping -> looping {<br>
+ triggers {<br>
+ <pingSimple: PingPongPort><br>
+ }<br>
+ action {<br>
+ "PingPongPort.pongSimple(data+1);"<br>
+ }<br>
+ }<br>
+ State looping<br>
+ }<br>
+ }<br>
+ }<br>
+
+<br>
+ ProtocolClass PingPongProtocol {<br>
+ incoming {<br>
+ Message ping(data: DemoData)<br>
+ Message pingSimple(data: int32)<br>
+ }<br>
+ outgoing {<br>
+ Message pong(data: DemoData)<br>
+ Message pongSimple(data: int32)<br>
+ }<br>
+ }<br>
+
+<br>
+ DataClass DemoData {<br>
+ Attribute int32Val: int32 = "4711"<br>
+ Attribute int8Array [ 10 ]: int8 = "{1,2,3,4,5,6,7,8,9,10}"<br>
+ Attribute float64Val: float64 = "0.0"<br>
+ Attribute stringVal: string = "\"empty\""<br>
+ }<br>
+}<br>
+
+</code>
+</p>
+</div>
+<div class="blockquote">
+<blockquote class="blockquote">
+<p></p>
+</blockquote>
+</div>
+</div>
+<div class="section" title="Generate and run the model">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title" style="clear: both">
+<a name="Generateandrunthemodel"></a>Generate and run the model</h2>
+</div>
+</div>
+</div>
+<p>With the MWe2 workflow generate the code and run the model.
+ The output should look like this:</p>
+<p>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</p>
+</div>
+<div class="section" title="Summary">
+<div class="titlepage">
+<div>
+<div>
+<h2 class="title" style="clear: both">
+<a name="Summary3"></a>Summary</h2>
+</div>
+</div>
+</div>
+<p>Within the first loop a integer value will be incremented from
+ [<span class="citation">MrPong</span>] and sent back to
+ [<span class="citation">MrPing</span>]. Is long as the guard is true
+ [<span class="citation">MrPing</span>] sends back the value.
+ </p>
+<p>Within the
+ [<span class="citation">next</span>] transition,
+ [<span class="citation">MrPing</span>] creates a data class and sends the default values. Than
+ [<span class="citation">MrPing</span>] 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 later versions of eTrice a additional mechanism to send references will be implemented. However, keep in mind that sending references takes the responsibility of the life cycle of the sent object to the user. It looks simple but is a very common source of failures.
+ </p>
+</div>
+</div>
+<div class="chapter" title="Chapter 6. ROOM Concepts">
<div class="titlepage">
<div>
<div>
<h2 class="title">
-<a name="ROOMConcepts"></a>Chapter 5. ROOM Concepts</h2>
+<a name="ROOMConcepts"></a>Chapter 6. ROOM Concepts</h2>
</div>
</div>
</div>
|