Project

General

Profile

Genom3tutorialdemo-genom3 » History » Version 5

Aurélie Clodic, 2014-04-10 16:00

1 1 Aurélie Clodic
h1. Genom3tutorialdemo-genom3
2
3
{{toc}}
4
5
6 5 Aurélie Clodic
This section will illustrate genom3 concepts through a concrete example. The demo module will control a virtual mobile that can move in a 1D world. Some of the services the module offers are:
7 1 Aurélie Clodic
* read and set the current speed at any moment
8
* move the mobile to a given position
9
* move the mobile of a given distance (from its current position)
10
* monitor when the mobile passes a given position
11
* stop the motion 
12
13
Moreover, the demo module export a port with the current state of the mobile (position and speed).
14
15
To implement this, we first create a directory named demo-genom3. 
16
17
<pre>
18
mkdir demo-genom3
19
cd demo-genom3
20
</pre>
21
22
h3. Write .gen file
23
24
In that directory, we will write the description file demo.gen. The file demo.gen is made up of several parts, each of them being identified with a keyword
25
* @component@
26
* @ids@
27
* @port@
28
* @exception@
29
* @task@
30
* @attribute@
31
* @function@
32
* @activity@
33
34 5 Aurélie Clodic
This .gen reflects the fact that a component need to define an interface made of a set of services and data ports. A component must provide a service invocation facility as well as unidirectional (input and output) data ports. It must be able to send and receive events. It has to define an internal data structure, named the @ids@, that is used by codels to store global and permanent objects.
35
Each codel has access to the @ids@ objects and use them to communicate with other codels within the component.
36
Finally, a component has to define one or more @execution tasks@ that represent the execution context (e.g. thread) in which services are run. Those tasks may be periodic or aperiodic.
37 1 Aurélie Clodic
38 5 Aurélie Clodic
The easiest way is to see how all of this is defined is to start from an existing file, so you can download ".gen" file. We will now explain step by step each part of this file.
39
40
41 1 Aurélie Clodic
h4. @component@
42
43 5 Aurélie Clodic
The component declaration describes the instance of the GenoM3 component. It is defined by a unique name (an identifier) that also defines an IDL scope for any embedded types. See the "component declaration documentation":http://homepages.laas.fr/mallet/share/doc/genom3/genom3.html/Component-declaration.html#Component-declaration for details.
44 1 Aurélie Clodic
45
<pre>
46
component demo {
47
  version	"1.1";
48
  email		"openrobots@laas.fr";
49
  lang		"c";
50
  require	"genom3 >= 2.99.20";
51
</pre>
52
53
54
* version : The component version number, as a string
55
* lang : The programming language of the codels interface
56
* email : A string containing the e-mail address of the author of the component.
57 5 Aurélie Clodic
* requires : A list of dependencies of the component. It indicates an external dependency on a software package that is required. It assumes that the package is using the pkg-config utility. Each string should contain a package name in pkg-config format. 
58 1 Aurélie Clodic
59
NB: component declaration is not over, the final } is left for the end @.gen@ file.
60
61
h4. @ids@
62
63 5 Aurélie Clodic
@ids@ stands for internal data structure, it is used by codels to store global and permanent objects.
64
Each codel has access to the @ids@ objects and use them to communicate with other codels within the component.
65
66
For our example, we considerto store the state, the speed reference and the position of the mobile: 
67 1 Aurélie Clodic
<pre>
68
ids {
69
  demo::state state;          /* Current state */
70
  demo::speed speedRef;       /* Speed reference */
71
  double      posRef;
72
};
73
</pre>
74
75 5 Aurélie Clodic
@demo::state@ and @demo::speed@ are types derived from ...
76
77 1 Aurélie Clodic
h4. @port@
78
79 5 Aurélie Clodic
A component define input and output data ports, used to implement data flow connections in parallel to services.
80
Ports implement the data flow between components as a publish/subscribe model. Ports have a name and a type and can be either out (for publishing data) or in (for subscribing to a sibling out port). Data ports Data ports are defined via the in or out keyword, followed by an IDL type and the name of the port e.g.: 
81 4 Aurélie Clodic
<pre>
82
port in data<type> name;
83
port out data<type> name;
84
</pre>
85
86 5 Aurélie Clodic
In our example, we choose to export the state of the mobile to let this information accessible for example to another port from another component:
87 1 Aurélie Clodic
<pre>
88
/* ---- Port declaration ---- */
89
  port out demo::state Mobile;
90
</pre>
91
92
h4. @exception@
93
94
It is possible to 
95
<pre>
96
/* ---- exception declaration ---- */
97
  exception TOO_FAR_AWAY {double overshoot;};
98
  exception INVALID_SPEED;
99
</pre>
100
101
h4. @execution task@
102
103
Tasks define an execution context suitable for running activities. A task may define a state machine and associated codels. 
104
The state machine starts in the start state when the task is created during component initialization.
105
Tasks can define the following properties:
106
* @period@ The granularity of the codel scheduler. Periodic task will sequence the codels they manage at that frequency.
107
* @delay@ The delay from the beginning of each period after which codels are run. This can be used to delay two tasks running at the same period in the same component.
108
* @priority@ Can be used to prioritize different tasks whithin the same component.
109
* @scheduling real-time@ This indicates that the task requires real-time scheduling. This may not be supported by all templates.
110
* @stack@ Defines the required stack size for this task. The stack size should be big enough to run all codels that the task manages.
111
112
113
In our example, we choose to get the task_period from ...
114
<pre>
115
/* ---- Execution task declaration ---- */
116
117
  task motion {
118
    period	demo::task_period ms;
119
    priority	100;
120
    stack	4000;
121
    codel <start>	InitDemoSDI(out ::ids, port out Mobile) yield ether;
122
  };
123
</pre>
124
125
h4. services declations
126
127 2 Aurélie Clodic
A service is an interface for running codels. It can be invoked via a request on the component service port.
128
Services have optional input and output data and a list of failure reports. Input data is stored in the IDS (and output read from there), so that codels can access it.
129
A service might be incompatible with other services of the same component or can be started multiple time, provided it is compatible with itself. It always interrupts other incompatible services when starting.
130
A service invocation triggers an activity that manages codel execution. An activity is described by a Petri net in which places correspond to codels execution and transitions are events generated either externally or implicitely by the return value of codels.
131
132
Service description follow this scheme:
133
<pre>
134
service name(inout s) {
135
doc "Service description";
136
task taskname;
137
validate svalidate();
138
throws ERROR_1, ERROR_2, ...;
139
interrupts name;
140
codel <start> sstart() yield step1;
141
codel <step1> sstep1() yield step1, step2;
142
codel <step2> sstep2() yield ether;
143
codel <stop> sstop() yield ether;
144
};
145
</pre>
146
where:
147
* @name@ corresponds to the name of the service
148
* @s@ corresponds to the parameter of the service. Parameter could be in/inout/out depending of its type. It is possible to have several parameters.
149
* @task@ corresponds to the task that handle the service
150
* @validate@ corresponds to a function that would be called once at the beginning of the service execution and that aims to check service parameter(s) consistency
151
* @throws@ corresponds to the list of failure report(s)
152
* @interrupts@ corresponds to the service(s) that would be automatically interrupted when the this service is called
153
154
When an activity starts, the start event is generated and the corresponding codel executed. Similarly, the activity is interrupted whenever the stop event is generated.
155
Asynchronous events trigger the execution of the corresponding codel (if any). A special sleep transition is defined so that an activity can be put in a sleeping state, waiting for external events or a stop to trigger a new transition. The activity stops when all active places in the Petri net have returned the special ether event. If the execution task of a service is periodic, transitions are executed at each period. They are otherwise executed as soon as all the codels corresponding to active places have returned. The codel execution order is undefined.
156
157
It should be noted that no direct remote procedure call (RPC) for service invocation between components is allowed. RPC should be performed by external applications that take care of setting up the architecture of com-
158
ponents. While this differs from traditional approaches, this guarantees that components can be controlled and will not interfere with the system. This also grants an increased reusability since no component explicitely depends on a particular set of services implemented by other components.
159
160 3 Aurélie Clodic
3 types of services are available through GenoM3: attribute, function and activity. Each follow the same service pattern.
161 2 Aurélie Clodic
162 1 Aurélie Clodic
163
h5. @attribute@
164 3 Aurélie Clodic
165
@attribute@ service type should be used to 
166
167 1 Aurélie Clodic
<pre>
168
 attribute SetSpeed(in speedRef = demo::SLOW	:"Mobile speed")
169
  {
170
    doc		"To change speed";
171
    validate	controlSpeed (local in speedRef);
172
    throw	INVALID_SPEED;
173
  };
174
175
  attribute GetSpeed(out speedRef =	:"Mobile speed")
176
  {
177
    doc		"To get current speed value";
178
  };
179
</pre>
180
181
h5. @function@
182
<pre>
183
 function Stop()
184
  {
185
    doc		"Stops motion and interrupts all motion requests";
186
    interrupts	MoveDistance, GotoPosition;
187
  };
188
</pre>
189
190
h5. @activity@
191
<pre>
192
activity MoveDistance(in double distRef = 0	:"Distance in m")
193
  {
194
    doc		"Move of the given distance";
195
    validate	controlDistance(in distRef, in state.position);
196
197
    codel <start>	mdStartEngine(in distRef, in state.position,
198
                              out posRef) yield exec, ether;
199
    codel <exec>	mdGotoPosition(in speedRef, in posRef, inout state,
200
                               port out Mobile) yield exec, end;
201
    codel <end, stop>	mdStopEngine() yield ether;
202
    interrupts	MoveDistance, GotoPosition;
203
    task	motion;
204
    throw	TOO_FAR_AWAY;
205
  };
206
</pre>