The Real Time Object Oriented Modeling (ROOM)
eTrice comprises several models:
In the following diagram the models and their relations are depicted. The meaning of the arrows is: uses/references.
The ConfigModel describes the Attribute configuration of ActorInstances and PortInstances.
The scope of this model is the configuration of Attributes of the LogicalModel. Thus it provides enhanced capabilities for assigning default values to Attributes, which are:
Values defined for class attributes are used for all instances unless there is an instance value configured for the same attribute. The configuration is available for actors and ports, thus ActorClasses/ActorRefs and ProtocolClasses/Ports.
ConfigModel ExampleConfig { import Example.* from "Example.room" ActorClassConfig ActorClass1 { Attr attribute1 = 4 } ActorInstanceConfig LogSys/subsysRef/actor1 { Attr attribute1 = 7 } }
The LogicalModel describes the logical structure and behavior of a ROOM application
The ROOM model defines DataTypes, ProtocolClasses, ActorClasses, SubSystemClasses and LogicalSystems. Thereby the three latter form a hierarchy. The LogicalSystem is the top level element of the structure. It contains references to SubSystemClass elements. The SubSystemClass in turn contains references to ActorClass elements which again contain (recursively) references to ActorClass elements. The complete structural hierarchy implies a tree which has the LogicalSystem as root and where each reference stands for a new node with possibly further branches.
An actor is the basic structural building block for building systems with ROOM
An ActorClass consists of three main parts:
ActorClass ExampleActorClass { Interface { Port port1: ProtocolClass1 Port port4: ProtocolClass1 } Structure { external Port port1 conjugated Port port2: ProtocolClass1 conjugated Port port3: ProtocolClass1 ActorRef ActorRef_A: ActorClass2 ActorRef ActorRef_B: ActorClass3 Binding port2 and ActorRef_A.port5 // ... } Behavior { // ... } }
Example:
An ActorRef is an instance of an ActorClass
Example:
SubSystemClass SubSystemExample { ActorRef mainActor : ActorClassExample LogicalThread default_thread } ActorClass ActorClassExample { Structure { ActorRef sender : Sender ActorRef receiver : Receiver Binding receiver.port and sender.port } } ActorClass ActorClassExampleReplicated { Structure { ActorRef sender[3]: Sender ActorRef receiver[3] : Receiver Binding receiver.port and sender.port /* Equivalent to: * Binding receiver[1].port and sender[1].port * Binding receiver[2].port and sender[2].port * .... */ } }
Instance hierarchy of ActorRef Example (System(System) not shown in code snippet)
An Annotation can be attached to a ROOM classes to apply the properties of its AnnotationType
It refers to an AnnotationType and may have to pass key value pairs. Its notation is similar to Java:
@AnnotationType1 @AnnotationType2(key1="STRING", key2=3, ...)
See section Annotations for further reading.
Example:
import room.basic.annotations.* from "../../org.eclipse.etrice.modellib.c/model/Annotations.room" ActorClass ComponentAbstraction { Interface { conjugated Port port1: Protocol1 } Structure { external Port port1 } Behavior { // custom/external state machine implementation @BehaviorManual } }
AnnotationTypes can be used to tag ROOM classes for further custom processing
They provide the ability to associate custom properties to ROOM classes, that adjust or toogle features, like generation or the runtime behavior. eTrice has some built-in annotations, which can be found in Annotations.room within the eTrice modellib.
See section Annotations for further reading.
An Attribute is a member variable of a class
An Attribute can be be used to store arbitrary data. There are two common conceptual purpose of use:
Attributes can be defined in several ROOM classes.
Example:
import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room" DataClass SimpleDataClass { Attribute attribute1: int16 Attribute attribute2: uint32 } ActorClass ActorClassWithAttributes { Structure { Attribute attribute1: int32 ["attribute of a PrimitiveType" ] Attribute attribute2: SimpleDataClass [ "attribute of a DataClass" ] } } ActorClass ActorClassWithAttributes2 { Structure { Attribute arrayAttribute[8] : uint32 [ "attribute with multiplicity"] Attribute refAttribue : voidType ref [ "attribute as a reference (void pointer)"] } } ActorClass ActorClassWithAttributeInitialization { Structure { Attribute attribute1: uint32 = "3" Attribute attribute2: SimpleDataClass = "{1, 2}" Attribute arrayAttribute[8] : uint32 = "0" // or {0,0,0, ...} Attribute refAttribue : voidType ref = "NULL" // set reference in constructor or in state machine } }
A Binding connects two Ports with each other
In essence, a binding is a abstraction for an underlying communication channel whose function is to convey messages from one port to the other. The precise semantics of these channels are not defined in the Binding. Instead, they are determined by the ProtocolClasses that are associated with the Ports at the end of the Binding.
ActorClass ExampleActorClass { Structure { conjugated Port sender: ProtocolClass1 ActorRef actorRef: ActorClass2 Binding sender and actorRef.receiver } }
The CommunicationType defines the communication semantics of a ProtocolClass
Since from ROOM models executable code can be generated, it is important to define the way the actors are executed and communicate with each other. The combination of communication and execution is called the execution model. Therefore the ExecutionType of an actor and the CommunicationType of the ports has to be considered.
The CommunicationType of a ProtocolClass (and thus of a Port) specifies in which way the communication should happen:
CommunicationType relates with the ExecutionType of an ActorClass, e.g. a data-driven port needs a cyclic thread, that polls the shared data.
Example:
import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room" ProtocolClass EventdrivenProtocolClass1 [ "default is eventdriven" ] { // explicit: eventdriven ProtocolClass EventdrivenProtocolClass { incoming { Message msg1() ["message without data"] Message msg2(data: int32) ["message with data"] } outgoing { Message msg4() ["eventdriven ProtocolClass can have message into two directions"] } } datadriven ProtocolClass DatadrivenProtocolClass { incoming { Message signal1 (data: int32) ["a datadriven message needs data"] } // datadriven ProtocolClass can only have incoming messages (signals) } // sync is not supported yet // sync ProtocolClass SyncProtcolClass { // // }
A DataClass is a composition of Attributes
Intended to model a type that primarily consists of data, which is usually grouped together in some manner. DataClasses roughly translate to Java classes without interaction or C structs.
DataClass TCPConnectionData { Attribute IPAddr: string Attribute TcpPort: int32 }
Example:
DataClass SimpleDataClass { Attribute attribute1: uint16 Attribute attribute2: uint32 } DataClass DataClassExample { Attribute attribute1: uint32 Attribute attribute2: SimpleDataClass Attribute attribute3: voidType ref Operation operation1(param1: uint32, param2: uint16): boolean { "return true;" } }
A DataType can take 4 forms and types data elements like an Attribute or Operation argument
An EnumerationType declares an enumeration similar to most well-known languages
Example:
Enumeration EOnOff { Off = 0, // explicit value=0 On = 1 // explicit value=1 } Enumeration EDay { SUN, MON, TUE, WED, THU, FRI, SAT // implicit enumeration 0..6 }
Determines the execution type of an actor
Since from ROOM models executable code can be generated, it is important to define the way the actors are executed and communicate with each other. The combination of communication and execution is called the execution model. Therefore the ExecutionType of an actor and the CommunicationType of the ports has to be considered.
The ExecutionType of an ActorClass specifies in which way its instance (ActorRef) should be executed:
Thereby the ExecutionType determines the execution mode of the actor's logical thread:
The actual execution of the underlying physical thread can be specified in the PhysicalModel in conjunction with the MappingModel.
ExecutionType relates to the CommunicationType, e.g. if an actor uses data-driven ports, it should support an polled execution.
Example:
eventdriven ActorClass EventdrivenActor ["default is eventdriven"] { // only event-driven Ports and ActorRefs allowed } datadriven ActorClass DatadrivenActor { // only data-driven Ports and ActorRefs allowed } async ActorClass MixedActor{ // both data/event-driven Ports and ActorRefs allowed }
A ExternalEndPort is an interface Port, that is made accessible to the internal interface of an ActorClass
ActorClass ExternalEndPortExample { Interface { // externalEndPort is connect from 'outside' and thus needs a Binding from containing ActorClass Port externalEndPort : PSimpleProtocol } Structure { external Port externalEndPort } Behavior { // send/receive messages from externalEndPort } }
An ExternalType is used to make an target language type accessible in ROOM
Example:
// Include is needed when used (e.g. in ActorClassWithExternalType) ExternalType someStructType -> "struct FILE_HANDLE" ActorClass ActorClassWithExternalType{ Structure { usercode1 { "// #include <___.h> /* User includes here*/" } Attribute someHandle : someStructType ref // needs include } Behavior { Operation operation1(param1: charPtr) { // external calls or casts may need includes "write(someHandle, param1);" } } }
A class can specify a super class and inherits elements from the super class hierarchy
When a ROOM class specifies a super class, it generally inherits all elements and properties. In several cases, it is possible, to override these inherited elements. Generally, eTrice has two semantics of overriding: refinement and replacement. Refinement is used in most cases (e.g. StateMachine) and realizes an extension of the overridden elements. In this case, if a sub class overrides a piece of logic from a super class, it will always be executed subsequently to the inherited. Contrary to this, replacement is applied to overridden Operations, similar to programming languages C++ and Java.
A formal definition of overriding is given below:
Examples programming languages: c++ virtual function and java override <==> accessible explicit late replacing c++ function redefine <==> accessible implicit early replacing c++ dtor <==> late refinement\
eTrice override of model elements: Operations (C generation) <==> non_accessible explicit late replacing Operations (Java generation) <==> accessible explicit late replacing State and Transitions <==> non-accessible explicit late refinement ctor/dtor <==> non_accessible implicit late refinement StateMachine <==> non-accessible implicit late refinement UserCode <==> non-accessible implicit late refinement
Example:
ActorClass ActorSubClass extends ActorBaseClass { // inherits all elements from super type hierarchy } ActorClass ActorBaseClass { Interface { Port port1 : ProtocolBaseClass } Structure { Attribute attribute1 : uint32 } Behavior { Operation operation1(){ "return;" } } } ProtocolClass ProtocolSubClass extends ProtocolBaseClass { // inherits all elements from super type hierarchy } ProtocolClass ProtocolBaseClass { incoming { Message message1() } } DataClass DataSubClass extends DataBaseClass { // inherits all elements from super type hierarchy } DataClass DataBaseClass { Attribute attribute1 : uint32 }
A InternalEndPort is an local Port, that is declared in the internal interface of an ActorClass
ActorClass InternalEndPortExample { Structure { Port internalEndPort : PSimpleProtocol ActorRef actorRef1 : SimpleActorClass // internalEndPort lives 'local' and // thus needs a Binding to port of a ActorRef Binding internalEndPort and actorRef1.externalPort2 } Behavior { // send/receive messages from internalEndPorts } }
A LayerConnection associates a SPP to an ActorRef, resulting in an connection of all SAPs on its instance hierarchy
The LogicalSystem is the topmost structural class. It assembles a distributed system by means of sub systems
It describes the logical topology of your distributed system and is composed of sub systems (SubSystemRefs). Thus it is the notationally root of every instance path or actor hierarchy.
An Operation is a member function of a class
Operations can be used to define a piece of reusable logic. The definition consists of:
Example:
import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room" DataClass DataClassWithOperation { Attribute attribute1 : uint32 Operation operation1(param1: uint32, param2: int32): boolean { "return attribute1 > (param1 - param2);" } } ActorClass ActorClassWithOperation { Structure { Attribute attribute1 : uint32 } Behavior { Operation operation1(param1: uint32, param2: int32): boolean { "return attribute1 > (param1 - param2);" } } } ActorClass ActorClassWithOperation2 { Structure { usercode1 { "// #include <___.h> /* User includes here*/" } Attribute someHandle : voidType ref } Behavior { Operation operation1(param1: charPtr) { // external calls or casts may need includes "write(someHandle, param1);" } } }
A Port is an instance of a ProtocolClass and the interface for an ActorClass
Once a ProtocolClass has been created, it can be used to define actor interfaces. This is accomplished by means of Ports. A Port is a declaration that the set of messages defined by its ProtocolClass is now part of the actor's interface. It provides strong decoupling of ActorClasses from each other, thus enabling easy testability, reusability and deployment of actors to different threads or nodes.
ActorClass Example { Structure{ Port port0 : ProtocolClass1 } Behavior { // send/receive message from port0 } }
For communication between two actors to take place, a connection must be established between a port on one of the actors and a port on the other. One condition is, that both Ports have compatible ProtocolClasses. In most cases the Ports simply refer to the same protocol. In addition, a ProtocolClass has an imposed directionality - it defines one subset of messages as incoming and the complementary subset as outgoing. Which subset is labeled as incoming and outgoing is arbitrary, it simply depends on the point of view, that was taken when defining. Therefore Ports can be ‘regular’ and ‘conjugated’. When two actors communicate by a connected pair of Ports, one Port has to be regular and the other conjugated. The ProtocolClass' incoming messages are on one side received by the regular Port and on the other sent by the conjugated Port (outgoing message vice versa).
A connection of Ports is denoted by a Binding.
A PrimitiveType is an abstraction of a target language's basic type (e.g. integer or boolean)
Example:
The eTrice built-in types can be found in the org.eclipse.etrice.modellib project. In most cases the Types.room is already included:
// Follow import by Open Declaration (F3) import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room"
A ProtocolClass defines messages and is the interface specification for a Port
A ProtocolClass provides a reusable interface specification for ports. It defines a set of incoming and outgoing Messages that can be exchanged between two ports. The exact semantics of a message is defined by the CommunicationType. Protocol classes have only textual notation.
ProtocolClass SimpleProtocolClass { incoming { Message msg1(data: int32} Message msg2() } outgoing { Message msg3(data: DataClass1} Message msg4() } }
Example:
import room.basic.types.* from "../../../org.eclipse.etrice.modellib.c/model/Types.room" // eventdriven ProtocolClass (asynchronous message passing, bidirectional) eventdriven ProtocolClass ProtocolClassEvt { // ProtocolClass ProtocolClassEvt { // same like above because eventdriven is default incoming { // incoming means incoming for a regular port and outgoing for a conjugated port Message message1() // message without data Message message2(data: int32) // message with simple data Message message3(data: DMessageData) // message with complex data (DataClass) } outgoing { // outgoing means outgoing for a regular port and incoming for a conjugated port Message message1(data: int32) // incoming and outgoing Messages can have the same name to enable symmetric protocols } } // DataClass for sending complex data via message DataClass DMessageData { Attribute SomeData: int16 Attribute SomeMoreData: int32 } // datadriven ProtocolClass (asynchronous data flow, unidirectional) datadriven ProtocolClass ProtocolClassData { incoming { // incoming means incoming for a regular port and outgoing for a conjugated port Message value1(value: int32) // a datadriven message (signal) always needs data Message value2(value: int16) // datadriven message with simple data Message value3(value: DMessageData) // datadriven message with complex data (DataClass) } // no outgoing messages for datadriven ports allowed }
A RelayPort forwards its messages without exposing them to the internal interface of the ActorClass
ActorClass RelayPortExample{ Interface { Port relayPort : PSimpleProtocol } Structure { ActorRef actorRef1 : SimpleActorClass2 // relayPort can be directed to port of an ActorRef Binding relayPort and actorRef1.externalPort } Behavior { // relayPort not available ! } }
Replication is mechanism for multi-instantiation for ActorRefs and Ports
ActorRefs and Ports can be instantiated several times under the same name. The notation is similar to arrays in programming languages.
This possibility provides an elegant way of scaling of your system without redundancy.
ActorRef sensor : Sensor // one instance ActorRef sensor[1] : Sensor // one instance ActorRef sensorArray[5] : Sensor // five instances
Replication can also applied to Ports. One use case is to establish a communication with multiple actors through one port interface.
Port service[5] : TimingService // five instances Port service[*] : TimingService // automatic, as many as needed
A Service Access Point is similar to a Port, but uses a LayerConnection for wiring
A Service Provision Point is the counterpart of a SAP
The implementation of an Service Provision Point (SPP)
A StateMachine describes the state based, event driven behavior of an ActorClass
In ROOM each actor class can implement its behavior using a state machine. Events occurring at the end ports of an actor will be forwarded to and processed by the state machine. Events possibly trigger state transitions.
A SubSystem is the topmost building block of the executable part of an system
It represents a class for an logical node in a distributed system. An instantiation translates to an executable application, that runs on a node or process. A SubSystemClass is the structural starting point of an ROOM application. Thus it declares the topmost actor instances (ActorRefs).
A Sub System Reference is an instance of an SubSystemClass
It represent a logical node in the structural view of a distributed system. An instantiation translates to an executable application, that runs on a node or process.
To be executable, a SubSystemRef has first to be mapped to a physical node, which defines the executional properties. A physical node is denoted by a NodeClass and NodeRef in the PhysicalModel. The mapping is defined in the MappingModel.
The MappingModel describes the mapping of elements of the LogicalModel to elements of the PhysicalModel
It enables the complete decoupling of the LogicalModel and the PhysicalModel, thus providing a maximum flexibility and reuse for the models.
The model starts with an import part, where you can import .room and .etphys models. They must contain at least one LogicalSystem and one PhysicalSystem. A Mapping entry puts both in relation, meaning that all sub systems of the LogicalSystem will be distributed to the nodes of the PhysicalSystem. This is carried out by a SubSystemMapping, that maps a SubSystemRef (logical node) to a NodeRef (physical node). In the next step, ThreadMappings provide the same action for the logical and physical threads.
MappingModel PingPongMapping { import PingPong_Model.* from "PingPong.room" import GenericPhysicalModel.* from "GenericPhysical.etphys" Mapping LogSys -> PhysSys1 { SubSystemMapping subSystemRef -> nodeRef1 { ThreadMapping defaultThread -> PhysicalThread1 } } }
The PhysicalModel defines the setup of your nodes with their attributes like threads and mode of execution
The model describes the physical view of your system:
PhysicalSystem PhysSys1 { NodeRef nodeRef1 : NodeClass1 NodeRef nodeRef2 : NodeClass2 }
The central element is a NodeClass, that models the executional aspects of a device (node). At first, it can be associated with a RuntimeClass, which specifies if your device supports multiple threads. ‘priomin’ and ‘priomax’ define the range of priorities, that can be assigned to threads.
NodeClass NodeClass1 { runtime = RuntimeClass1 priomin = -10 priomax = 10 // Thread definitions ... } RuntimeClass RuntimeClass1 { model = multiThreaded // or singleThreaded }
A thread has to specify the following properties:
execmode: defines the execution type, see more at ExecutionType
msgblocksize: the size in bytes of a message
msgpoolsize: the amount of messages, that the thread's message queue can store
Note: ‘msgblocksize’ and ‘msgpoolsize’ also apply to the polled execution due the internal implementation via message passing. The size of the message queue can be calculated as follows: msgpoolsize * msgblocksize bytes
DefaultThread ThreadMessaging { execmode = polled prio = 0 stacksize = 1024 msgblocksize = 32 msgpoolsize = 10 } Thread ThreadPolled { execmode = polled prio = 0 interval = 100ms stacksize = 1024 msgblocksize = 32 msgpoolsize = 10 }
All aspects of the ROOMLanguage can be edited by full-blown textual editors. In addition, graphical editing is provided for the structural and behavioral part of ActorClasses.
The GraphicalBehaviorEditor allows to edit the ActorClass' StateMachine. It is possible to create (hierarchical) states and transitions to model complex behavior in a convenient way.
The Structure Editor allows to edit the ActorClass' Structure in a convenient way. It is possible to create and arrange actor references and ports and to create bindings and layer connections.
A dialog to edit properties of an ActorRef.
The dialog is used to edit an existing ActorRef of an ActorClass. It is also shown when creating a new one.
A dialog to edit properties of an Port.
The dialog is used to edit an existing Port of an ActorClass. It is also shown when creating a new one.
A dialog to edit properties of a SPP.
The dialog is used to edit an existing SPP of an ActorClass. It is also shown when creating a new one.
The palette creates central structural elements of an ActorClass.
Selecting an entry from the palette and clicking into the diagram, creates the element at the current position.
Textual model editor
Displays an overview of all elements in the textual editor.
Shows the structure of the current opened model in the textual editor. Select the ‘Link with Editor’ option to synchronize the selection of elements between editor and outline view. This enables a convenient navigation.
Runtime logger for data-driven Messages with primitive data.
The DataLogging uses an annotation to configure the generated instrumentation:
@DataLogging(pathlist = "/portInstancePath,/portInstancePath,..")
Where pathlist
is a string specifying a list of port instances which should be instrumented for data logging:
/portInstancePath
= /LogicalSystem/SubSystemRef/ActorRef/Port
,
), but avoid any whitespaceThe logging status can be verified in the generation console. It will output an overview of all accepted ports. In the GenerationOptions is possible to (de)activate the data logging and thus ignoring the presence of the annotation.
At runtime the data values will then be logged
Multi-Threading is not supported, the system must have not more than one polled/async physical thread.
The built-in Gnuplot script generator provides a convenient way to visualize the logged data. It generates a gnuplot script that can be used to create graphs from the logged data values.
C:\Program Files\gnuplot\bin;
)@Gnuplot
and @GnuplotGraph
to configure the script generation (see example)Example:
import room.basic.annotations.* from "../../org.eclipse.etrice.modellib.c/model/Annotations.room" LogicalSystem Logging { SubSystemRef main: MainSubSystem } SubSystemClass MainSubSystem { @DataLogging(pathlist = "/Logging/main/actorRef1/port1") @Gnuplot(format="pngcairo", outputfile="main.data.png", width=1800, height=600, fontsize=10) @GnuplotGraph( paths="/Logging/main/actorRef1/port1", xtics=100, mxtics=4, ymin=-1.2, ymax=1.2 )
Logged data values in .csv format:
, /LogSys/subSystemRef/rootActor/serverInst/output, /LogSys/subSystemRef/rootActor/clientInst/output 0, 0.000000 ,0.000000 1, 0.000000 ,0.100000 2, 0.099833 ,0.200000 3, 0.198669 ,0.300000 4, 0.295520 ,0.400000 5, 0.389418 ,0.500000 [...]
Resulting graph created from generated gnuplot script:
Mechanism to adjust the generation.
Options for generation are configured in the launch configuration or in case of standalone generation via command line. A list of available options:
Runtime logger for event-driven Messages, represented as a Message Sequence Chart.
The MSCLogging is activated by default, but can be set manually in the GenerationOptions. The output file is created upon regular termination of the application. The resulting file can be found in the logging directory and has the name msc.seq, which can be open with the free open source tool Trace2UML.