[doc.doc]directory AVIs added with two little video sequences

1 files changed, 113 insertions, 469 deletions

diff --git a/plugins/org.eclipse.etrice.doc/build/etrice.xml b/plugins/org.eclipse.etrice.doc/build/etrice.xml
index df1826ecf..db705641d 100644
--- a/plugins/org.eclipse.etrice.doc/build/etrice.xml
+++ b/plugins/org.eclipse.etrice.doc/build/etrice.xml
@@ -26,9 +26,118 @@
 		<title>Introduction to the ROOM Language</title>
 		<section id="ScopeofROOM">
 			<title>Scope of ROOM</title>
+			<para>This chapter will give a rough overview of what ROOM (
+				<emphasis role="bold">R</emphasis> eal time 
+				<emphasis role="bold">O</emphasis> bject 
+				<emphasis role="bold">O</emphasis> riented 
+				<emphasis role="bold">M</emphasis> odeling) is and where it is good for. It will try to answer the following questions:
+			</para>
+			<itemizedlist>
+				<listitem>
+					<para>Where does it come from?</para>
+				</listitem>
+				<listitem>
+					<para>Which kind of SW-Systems will be addressed?</para>
+				</listitem>
+				<listitem>
+					<para>What is the relation between OOP and ROOM?</para>
+				</listitem>
+				<listitem>
+					<para>What are the benefits of ROOM?</para>
+				</listitem>
+				<listitem>
+					<para>Which consequences must be taken into account?</para>
+				</listitem>
+			</itemizedlist>
+			<section id="Wheredoesitcomefrom">
+				<title>Where does it come from?</title>
+				<para>Room was developed in the 1990th on the background of the upcoming mobile applications with the goal to manage the complexity of such huge SW-Systems. From the very beginning ROOM has focused on a certain type of SW-Systems and, is in contrast to the UML, well suited for this kind of  systems. In this sense, ROOM is a DSL (Domain Specific Language) for distributed, event driven, real time systems. </para>
+				<para>Bran Selic, Garth Gullekson and Paul T. Ward have published the concepts 1994 in the book &#8222;REAL-TIME OBJECT-ORIENTED MODELING”. The company 
+					<citation>object time</citation> &#8482; developed a ROOM tool which was taken over from 
+					<citation>Rational SW</citation> &#8482; and later on from 
+					<citation>IBM</citation> &#8482;. Unfortunately the tool is no longer maintained from 
+					<citation>IBM</citation> &#8482;. The company 
+					<citation>Protos SW Gmbh</citation> &#8482; also developed a ROOM tool called 
+					<citation>trice</citation> &#8482; for controlling production machines. 
+					<citation>Trice</citation> &#8482; is the predecessor of eTrice (see Introduction to eTrice). 
+				</para>
+				<para>From our point of view ROOM provides still the clearest, simplest, completest and best suited modeling concepts for the real time domain. All later proposals like the UML does not fit such perfect to this kind of problems.</para>
+			</section>
+			<section id="WhichkindofSWSystemswillbeaddressed">
+				<title>Which kind of SW-Systems will be addressed?</title>
+				<para>As mentioned before ROOM addresses distributed, event driven, real time systems. But what is a &#8222;real time system”? ROOM defines a set of properties which are typically for a real time system. This properties are:</para>
+				<itemizedlist>
+					<listitem>
+						<para>Timeliness</para>
+					</listitem>
+					<listitem>
+						<para>dynamic internal structure</para>
+					</listitem>
+					<listitem>
+						<para>Reactiveness</para>
+					</listitem>
+					<listitem>
+						<para>Concurrent</para>
+					</listitem>
+					<listitem>
+						<para>Distributed</para>
+					</listitem>
+					<listitem>
+						<para>Reliable</para>
+					</listitem>
+				</itemizedlist>
+				<para>Each of this properties has potential to make SW development complex. If a given system can be characterized which some or all of this properties, ROOM might be applied to such a system.  </para>
+				<para>As an example take a look at a washing machine. The system has to react on user interactions, has to handle some error conditions like a closed water tap or a defective lye pump. It has to react simultaneously to all this inputs. It has to close the water valve in a certain time to avoid flooding the basement. 
+					So, the system can by characterized as timeliness, concurrent and reactive. As long as the washing machine does not transform to a laundry dryer by themself, the system has no dynamic internal structure and as long as all functions are running on a single microcontroller the (SW)-system is not distributed. 
+					ROOM fits perfect to such a system.</para>
+				<para>A SW system which mainly consists of transformations like signal processing or image processing (pure algorithms) cannot be characterized with any of the above mentioned properties. However, in the real world most of the SW systems will be a combination of both. ROOM can be mixed up with non model code. </para>
+			</section>
+			<section id="WhatistherelationbetweenOOPandROOM">
+				<title>What is the relation between OOP and ROOM?</title>
+				<para>The relation between classic object oriented programming and ROOM is comparable to the relation between assembler programming and C programming. It provides a shift of the object paradigm. As the picture shows, the classic object paradigm provides some kind of information hiding. Attributes can be accessed via access methods. Logical higher level methods provides the requested behavior to the user.   </para>
+				<para>
+					<mediaobject>
+						<imageobject>
+							<imagedata fileref="images/010-RoomIntroduction01.png"/>
+						</imageobject>
+					</mediaobject>
+				</para>
+				<para>As the figure illustrates, the classic object paradigm does not care about concurrency issues. The threads of control will be provided from the underlying operating system.</para>
+				<para>
+					<mediaobject>
+						<imageobject>
+							<imagedata fileref="images/010-RoomIntroduction02.png"/>
+						</imageobject>
+					</mediaobject>
+				</para>
+				<para>ROOM provides the concept of a logical machine (called actor) with it´s own thread of control. It provides some kind of cooperative communication infrastructure with &#8222;run to completion” semantic. That makes developing of business logic easy and save (see basic concepts).  </para>
+				<para>
+					<mediaobject>
+						<imageobject>
+							<imagedata fileref="images/010-RoomIntroduction03.png"/>
+						</imageobject>
+					</mediaobject>
+				</para>
+				<para>This thinking of an object is much more general than the classic one.  </para>
+			</section>
+			<section id="WhatarethebenefitsofROOM">
+				<title>What are the benefits of ROOM?</title>
+				<para>The main benefits are:
+					- ROOM provides model execution, which makes it easy to find defects early enough, to reduce expensive debugging during the testing phase or even in the costumer environment.
+					- ROOM promotes component building which is essential to make SW reusable
+					- Graphical modeling makes it easy to understand, maintain and share code with other developers
+					- higher abstraction in combination with automated code generation provides very efficient mechanisms to the developer. </para>
+			</section>
+			<section id="Whichconsequencesmustbetakenintoaccount">
+				<title>Which consequences must be taken into account?</title>
+				<para>Generating code from models will introduce some overhead in terms of footprint as well as performance. For most systems the overhead will be negligible. However, the decision using ROOM should be made explicitly and it is always a tread of between development costs, time to market and costs in terms of a little bit more of memory and performance. As mentioned, in most cases the decision will be very clear. Especially in case of product lines or products which requires maintenance or feature updates, the ROOM methodology has big advantages.  </para>
+				<para>Care must be taken during introduction of the new methodology. Due to the fact that ROOM provides a shift of the object paradigm, developers often needs a phase of adaption. Even some of them will never adapt.</para>
+			</section>
 		</section>
 		<section id="BasicConcepts">
 			<title>Basic Concepts</title>
+			<para>port, protocol, actor, interface, asynchronous communication
+				hierarchical FSM, hierarchical structure</para>
 		</section>
 		<section id="Benefits">
 			<title>Benefits</title>
@@ -652,161 +761,8 @@ carLights.setState(TrafficLight3.OFF);
 			<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 -&gt; off {
-					action {
-						"carLights = light.getCarLights();"
-						"pedLights = light.getPedLights();"
-						"carLights.setState(TrafficLight3.OFF);"
-						"pedLights.setState(TrafficLight2.OFF);"
-					}
-				}
-				Transition tr0: off -&gt; tp0 of blinking {
-					triggers {
-						&lt;start: ControlPort&gt;
-					}
-				}
-				Transition tr1: blinking -&gt; off {
-					triggers {
-						&lt;stop: ControlPort&gt;
-					}
-					action {
-						"timer.Kill();"
-						"carLights.setState(TrafficLight3.OFF);"
-					}
-				}
-				State off
-				State blinking {
-					subgraph {
-						Transition tr0: my tp0 -&gt; on
-						Transition tr1: on -&gt; off {
-							triggers {
-								&lt;timeoutTick: timer&gt;
-							}
-						}
-						Transition tr2: off -&gt; on {
-							triggers {
-								&lt;timeoutTick: timer&gt;
-							}
-						}
-						Transition init: initial -&gt; 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 -&gt; on {
-					action {
-						"timer.Start(5000);"
-						"ControlPort.start();"
-					}
-				}
-				Transition goOff: on -&gt; off {
-					triggers {
-						&lt;timeoutTick: timer&gt;
-					}
-					action {
-						"ControlPort.stop();"
-						"timer.Start(5000);"
-					}
-				}
-				Transition goOn: off -&gt; on {
-					triggers {
-						&lt;timeoutTick: timer|timeoutTick: timer&gt;
-					}
-					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>
+			<para>The complete model can be found in /org.eclipse.etrice.tutorials/model/Blinky.</para>
 		</section>
 		<section id="Summary2">
 			<title>Summary</title>
@@ -1120,148 +1076,7 @@ carLights.setState(TrafficLight3.OFF);
 					</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&lt;d.int8Array.length; i++) {"
-						"System.out.printf(\"%d \",d.int8Array[i]);}"
-						"System.out.printf(\"\\nd.stringVal: %s\\n\",d.stringVal);"
-					}
-					
-			StateMachine {
-				Transition wait2: waitForPong -&gt; waitForPong {
-					triggers {
-						&lt;pong: PingPongPort&gt;
-					}
-					action {
-						"printData(data);"
-					}
-				}
-				Transition wait1: waitForPongSimple -&gt; waitForPongSimple {
-					triggers {
-						&lt;pongSimple: PingPongPort guard {
-							"data &lt; 10"
-						}&gt;
-					}
-					action {
-						"// keep in mind that MrPong increments"
-						"PingPongPort.pingSimple(data);"
-						"System.out.printf(\"data: %d\\n\",data);"
-					}
-				}
-				Transition next: waitForPongSimple -&gt; waitForPong {
-					triggers {
-						&lt;pongSimple: PingPongPort&gt;
-					}
-					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&lt;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 -&gt; waitForPongSimple {
-					action {
-						"PingPongPort.pingSimple(0);"
-					}
-				}
-				State waitForPong
-				State waitForPongSimple
-			}
-		}
-	}
-
-	ActorClass MrPong {
-		Interface {
-			Port PingPongPort: PingPongProtocol
-		}
-		Structure {
-			external Port PingPongPort
-		}
-		Behavior {
-			StateMachine {
-				Transition init: initial -&gt; looping { }
-				Transition tr0: looping -&gt; looping {
-					triggers {
-						&lt;ping: PingPongPort&gt;
-					}
-					action {
-						"PingPongPort.pong(data);"
-					}
-				}
-				Transition tr1: looping -&gt; looping {
-					triggers {
-						&lt;pingSimple: PingPongPort&gt;
-					}
-					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>
+			<para>The model is finished now and can be found in /org.eclipse.etrice.tutorials/model/SendingData.</para>
 		</section>
 		<section id="Generateandrunthemodel">
 			<title>Generate and run the model</title>
@@ -1393,181 +1208,10 @@ carLights.setState(TrafficLight3.OFF);
 					<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>
+					<para>Copy the model from /org.eclipse.etrice.tutorials/model/PedLightsController to your model file, or run the model directly in the tutorial directory:</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 -&gt; running {
-					action {
-						"carLights=lights.getCarLights();"
-						"pedLights=lights.getPedLights();"
-						"carLights.setState(TrafficLight3.OFF);"
-						"pedLights.setState(TrafficLight2.OFF);"
-						"lights.setPort(ControlPort);"
-					}
-				}
-				Transition tr0: running -&gt; running {
-					triggers {
-						&lt;setCarLights: ControlPort&gt;
-					}
-					action {
-						"carLights.setState(state);"
-					}
-				}
-				Transition tr1: running -&gt; running {
-					triggers {
-						&lt;setPedLights: ControlPort&gt;
-					}
-					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 -&gt; off { }
-				Transition tr0: off -&gt; carsGreen {
-					triggers {
-						&lt;start: ControlPort&gt;
-					}
-					action {
-						"timer.Start(700);"
-						"ControlPort.setCarLights(TrafficLight3.GREEN);"
-						"ControlPort.setPedLights(TrafficLight2.RED);"
-					}
-				}
-				Transition tr1: carsGreen -&gt; carsYellow {
-					triggers {
-						&lt;timeoutTick: timer&gt;
-					}
-					action {
-						"timer.Start(700);"
-						"ControlPort.setCarLights(TrafficLight3.YELLOW);"
-						"ControlPort.setPedLights(TrafficLight2.RED);"
-					}
-				}
-				Transition tr2: carsYellow -&gt; carsRed {
-					triggers {
-						&lt;timeoutTick: timer&gt;
-					}
-					action {
-						"timer.Start(1500);"
-						"ControlPort.setCarLights(TrafficLight3.RED);"
-						"ControlPort.setPedLights(TrafficLight2.GREEN);"
-					}
-				}
-				Transition tr3: carsRed -&gt; carsYellowRed {
-					triggers {
-						&lt;timeoutTick: timer&gt;
-					}
-					action {
-						"timer.Start(700);"
-						"ControlPort.setCarLights(TrafficLight3.YELLOW_RED);"
-						"ControlPort.setPedLights(TrafficLight2.RED);"
-					}
-				}
-				Transition tr4: carsYellowRed -&gt; carsGreen2 {
-					triggers {
-						&lt;timeoutTick: timer&gt;
-					}
-					action {
-						"timer.Start(700);"
-						"ControlPort.setCarLights(TrafficLight3.GREEN);"
-						"ControlPort.setPedLights(TrafficLight2.RED);"
-					}
-				}
-				Transition tr5: carsGreen2 -&gt; off {
-					triggers {
-						&lt;timeoutTick: timer&gt;
-					}
-					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>
+					<para>Arrange the Structure and the Statemachines to understand the model</para>
 				</listitem>
 			</itemizedlist>
 			<para>