Wiki source code of ThinKCharts User Guide

Last modified by cmot on 2023/09/11 16:17
Show last authors
1 = ThinKCharts User Guide =
2
3 == Thin Kieler SyncCharts Editor ==
4
5 Authors:
6
7 * Matthias Schmeling <schm at informatik.uni-kiel.de>
8 * Hauke Fuhrmann <haf at informatik.uni-kiel.de>
9
10 == Create a new Diagram ==
11
12 * To create a new SyncCharts diagram first create a new project. (New->General->Project)
13 * Then create a new syncChart. (New->SyncChart Diagram)
14 * The wizard asks you for the name of the diagram file and its corresponding model file. These should be the same for both files.[[~[~[image:url:http://trac.rtsys.informatik.uni-kiel.de/trac/kieler/browser/plugins/de.cau.cs.kieler.synccharts/images/thinkcharts-mainmenu.png?format=raw~]~]>>url:http://trac.rtsys.informatik.uni-kiel.de/trac/kieler/browser/plugins/de.cau.cs.kieler.synccharts/images/thinkcharts-mainmenu.png||shape="rect"]]
15 * Use the KIELER main menu to add some default initial syncChart to your canvas to start from. Now you have a new syncChart with a top level state that contains a region. Note that there should only be one top level state in a syncChart.
16
17 == Editing the diagram ==
18
19 === Context Menu ===
20
21 [[image:attach:thinkcharts-contextmenu.png]]
22
23 [[~[~[image:url:http://trac.rtsys.informatik.uni-kiel.de/trac/kieler/browser/plugins/de.cau.cs.kieler.synccharts/images/thinkcharts-contextmenu.png?format=raw~]~]>>url:http://trac.rtsys.informatik.uni-kiel.de/trac/kieler/browser/plugins/de.cau.cs.kieler.synccharts/images/thinkcharts-contextmenu.png||shape="rect"]]
24
25 * Use the //context menu//(right-click) to add most of the items
26 ** **Add Successor State**: Add a state with a transition following the currently selected state.
27 ** **Add Predecessor State**: Add a state with a transition with a transition to the currently selected state.
28 ** **Upgrade State**: Add a Region into a State and an initial State into that Region. Can be called either on Simple States or on Macro States.
29 ** **Downgrade State**: Remove a Region from a State.
30 ** **Add Choice**: Add a Conditional Pseudo States with two target States.
31 ** **Add Signal**: Add a Signal declaration to a State.
32 ** **Add Action/Suspension(% style="color: rgb(0,51,102);" %) (%%)**: Add a State Action (OnEntry, OnInside (will be executed every tick), OnExit) or a Suspension Trigger. The first three may also contain a Trigger (hence a pure effect needs to start with a slash "/"), the latter is only a Trigger and may not contain an effect.
33 ** **Connect States**: Add a Transition between the two selected States.
34 ** **Flip Transition**: Change source and target of selected Transition.
35 ** **Set Transition Target/Set Transition Source**: Change either the target or the source of the currently selected transition to the currently selected State. Requires tp select exactly one Transition and one State.
36
37 === Palette ===
38
39 The Palette is only there for old-style drag-and-drop editing. It is discouraged to use the palette to insert states and transitions. Better use the context menu as described above to edit the diagram with Structure-Based Editing operations. It will also automatically use auto-layout to get a nice graphical layout of the diagram.
40
41 === Properties ===
42
43 * Use the properties view to change internal attributes of graphical objects
44 * Open by
45 ** Window->Show view->Properties or
46 ** Right-click in the graphical editor -> Show Properties View
47 * Example attributes to change
48 ** Labels and IDs of States
49 ** Types and flags of States (Conditional, normal, reference, initial, final...)
50 ** Types and flags of Transitions (weak or strong abortion, normal termination, immediate, delay, history...)
51
52 === Labels ===
53
54 * Main label properties like IDs or names can be changed by selecting the graphical object and just start typing on the keyboard. E.g. select a Region and start typing; this will edit the Region ID.
55 * Click a textual label multiple times for direct in-place editing of names, e.g.
56 ** State labels
57 ** Signal names
58 ** Transition labels
59 ** Action labels
60 ** Region IDs
61
62 ----
63
64 == Graphical Elements in a ThinKCharts SyncChart ==
65
66 [[image:attach:thinkcharts-overview-2.png]]
67
68 == Interface Declaration Parser ==
69
70 * Signals and Variables can be declared in a textual representation for a specific state and this state's subregions.
71 * If you are familiar with Xtext grammars or ENBF see following links for the complete syntax
72 ** (% class="source" %)Xtext: (% class="source source source" %)InterfaceDecl.xtext in (% class="source source" %)de.cau.cs.kieler.synccharts.interfacedeclparser(% class="source" %)
73
74 ** ENBF: InterfaceDecl.html in de.cau.cs.kieler.synccharts.interfacedeclparser
75
76 === Short Sample ===
77
78 * signals can be added using the //signal//keyword finished by a semicolon.
79 ** there can be an arbitrary number of comma separated signals
80 ** inputs are declared by using the keyword //input// (same for //output// and //input output//)
81 * variables are added in a similar way like signals by using the //var//keyword finished by a semicolon.
82 ** there can be an arbitrary number of comma separated variables just like for the signals
83 * an initial value is defined by //:=//following directly after the signal's name (care: use quotation marks for the value, as the underlying type is EString)
84 ** the value type can be declared directly afterwards with a preceding colon
85 * the combine operator and value type are declared by the keywords //combine// ... //with//
86 ** possible combine operators : NONE, +, *, max, min, or, and, host
87 ** possible value types : PURE, BOOL, UNSIGNED, INT, FLOAT,HOST
88 * signals and variables for a state's //subregions// are declared starting with region's identifier followed by a colon (//R0: signal...// for region R0)
89 * you can use single line comments //and multi line comments /* */// as you like
90
91 {{{signal A, B, C; // three signals
92 input in1 := "5" : INT; // a signal with initial value
93 output out1 := "10" combine INT with +;
94 input output inout1 combine "uint8_t" with "combine_signals_fancy(x, y)"; // host combine operators can be fancy
95 output sig1, sig2 := "3" combine FLOAT with *;
96 R0: signal reg1, reg2, var var1, var2;
97 R0: var var3, var4;
98 R0: signal reg3, reg4;
99 }}}
100
101 == Action Label Parser ==
102
103 * Action and Transition labels get automatically parsed and checked for correctness by a complex parser.
104 * The label language mainly follows Esterel and E-Studio label Syntax.
105 * For details, see\\
106 ** (% class="source" %)full label syntax grammar in Xtext notation(%%): de.cau.cs.kieler.synccharts.labelparser/src/de/cau/cs/kieler/synccharts/labelparser/ActionLabel.xtext
107 ** (% class="export" %)full label syntax grammar in EBNF notation(%%): de.cau.cs.kieler.xtext.docgenerator/src-gen/de.cau.cs.kieler.synccharts.labelparser.ActionLabel.html
108
109 ==== General Form ====
110
111 {{{Action:
112 (isImmediate?='#')? (delay=INT)? (trigger=BooleanExpression)? ("/" (effects+=Effect (',')? )*)?;
113 }}}
114
115 * Example: # A or B / C, varD:=5 , or more complex:
116
117 {{{A and B and C or D and not E or (43&#x3c;?F) or (varA = 103) and not (B and (C or D)) / G, H(23) I, varB:=104
118 }}}
119 * isImmediate: flag that indicates that the transition has to be tested immediately after the state has been entered. Especially in the same tick. By default, a transition is only tested beginning from the next tick.
120 * delay: counter that specifies the number of times that the trigger has to be evaluated to true before the transiton is taken. Example: 10 SECOND / ALARM.
121 ** Note: immediate and delay are mutual exclusive.
122 * Trigger: A boolean expression that is the guard of the transition (details below)
123 * Effects: A comma- or whitespace-separated list of effects that get executed when the transition is taken (details below).
124
125 ==== Trigger ====
126
127 >Trigger are boolean expressions over Signals and value comparisons that guard actions and transitions. They can comprise the following elements:
128
129 * Simple Signal references:
130
131 {{{A
132 }}}
133 * Boolean expressions of Signals with usual precedence rules (not, and, or), e.g. these are equal
134
135 {{{A and B or not C and D
136 }}}
137
138 {{{(A and B) or ((not C) and D)
139 }}}
140 * Valued Signals and Variables can be used in conditions in these boolean expressions
141 ** Valid comparison operators: = , < , <= , > , >=
142 ** Value operator for valued signals: VAL="?", example: ?A
143 ** Examples:
144
145 {{{variableX &#x3c; 5
146 }}}
147
148 {{{?B = 3
149 }}}
150 * Comparisons may contain arithmetic expressions with usual precedence rules with the operators +,-,*,/,mod
151
152 {{{?B &#x3c; (variableX + (2 * ?C))
153 }}}
154 * Comparisons can be mixed into the boolean trigger expressions arbitrarily
155
156 {{{A and (3 &#x3e; ?B) or ((var5 + 2) = 6)
157 }}}
158 * The **pre**operator will give the value of a signal of the instance of one tick behind, both in value or presence domain
159
160 {{{A and pre(B)
161 }}}
162
163 {{{3 &#x3c; pre(?A)
164 }}}
165
166 ==== Effects ====
167
168 * Effects get executed when a transition is taken (i.e. when its guard evaluates to true).
169 * They get separated from the trigger by a '/' symbol.
170 * Possible effects are Signal Emissions and Variable Assignments:
171 * Emission of a simple signal:
172
173 {{{/ A
174 }}}
175 * Emission of value of a valued Signal:
176
177 {{{/ A(3)
178 }}}
179 * Assignment of a variable:
180
181 {{{/ varA := 42
182 }}}
183 * Multiple effects get comma- or whitespace separated:
184
185 {{{/ A, B, C(25), varA := 2
186 }}}
187 * New values may use value expressions as explained above:
188
189 {{{/ A(3 + pre(?B)), varC := (varD + 1)
190 }}}
191
192 ==== Host Code ====
193
194 >If the action label syntax is not expressive enough, you can escape to any host-language, e.g. C, Java or whatever syntax.
195
196 * Use quotes to indicate host code
197
198 {{{'This is host code in the trigger' / 'this in an effect'
199 }}}
200 * It can be mixed with other expressions
201
202 {{{A and 'HostCode' / B, C(23), D('yet another Host Code'), 'EvenMore'
203 }}}
204 * In parantheses the type of host code (e.g. the used language) may be given (optional)
205
206 {{{B or 'MyCConstant'(C) / 'object.execute(xyz)'(Java)
207 }}}
208
209 == Naming ==
210
211 * Regions and States have IDs, that should be unique in their context (e.g. state IDs have to be unique within the same Region but not globally)
212 * States also have visible labels which in general is the name of the state. However, this label may be blank. In order to address all states correctly, IDs should not be blank.
213 * An automatic mechanism sets IDs automatically
214 ** the ID gets the label of the state where all whitespace is replaced by underscores '_'
215 ** an empty label results in an auto-generated ID like "S0", "S1", "S2", ...
216
217 == Validation ==
218
219 * Finally, you should regularly test if your syncChart is correct. To do this, click on Diagram->Validate. Inconsistencies in your diagram are indicated by little red icons and also an entry in the problems view. Note that the validation may still be incomplete and not be able to point out all errors.
220 * Your diagram gets validated automatically whenever it is saved.
221 * For details on the checks performed see the (% class="source" %)Checkfile in Xtend Check language syntax(%%): de.cau.cs.kieler.synccharts/model/SyncchartsChecks.chk
222
223 == Differences to the original SyncCharts ==
224
225 * There is no initial connector, instead a state itself can be initial, by setting the isInitial property to true.
226 * There is no history connector, instead this is a transition property (isHistory).
227
228 == Copy & Paste ==
229
230 [[~[~[image:url:http://trac.rtsys.informatik.uni-kiel.de/trac/kieler/browser/models/synccharts/copy_paste.png?format=raw~]~]>>url:http://trac.rtsys.informatik.uni-kiel.de/trac/kieler/browser/models/synccharts/copy_paste.png||shape="rect"]]
231
232 Copy & Paste gives some extra functionality, as it allows to copy many graphical objects into many target objects. See the image as an example. In the image, nodes, edges or regions denoted with "S" are selected elements (sources) for the copy operation and "T" are selected elements for the paste operation (targets). Elements without label are just dummy elements.
233
234 |(((
235 Source/Target?
236 )))|(((
237 State
238 )))|(((
239 Region
240 )))|(((
241 Transition
242 )))
243 |(((
244 State
245 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
246 (((
247 replace, keep all transitions
248 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
249 (((
250 add State to Region
251 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
252 (((
253 insert, old Transition stick with source
254 )))
255 |(((
256 Region
257 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
258 (((
259 insert
260 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
261 (((
262 replace, if root: create state and insert
263 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
264 (((
265 insert, old Transition stick with source
266 )))
267 |(((
268 Transition
269 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
270 (((
271 add as selfloop
272 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
273 (((
274 create dummy States and connect
275 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
276 (((
277 replace
278 )))
279 |(((
280 States
281 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
282 (((
283 replace, discard transitions
284 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
285 (((
286 add States to Region
287 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
288 (((
289 insert, old Transition stick with source
290 )))
291 |(((
292 Regions
293 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
294 (((
295 insert
296 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
297 (((
298 replace, if root: create state and insert
299 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
300 (((
301 insert, old Transition stick with source
302 )))
303 |(((
304 Transitions
305 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
306 (((
307 add as selfloops
308 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
309 (((
310 create dummy States and connect
311 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
312 (((
313 replace with all
314 )))
315
316 |(((
317 Source/Target?
318 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
319 (((
320 States
321 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
322 (((
323 Regions
324 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
325 (((
326 Transitions
327 )))
328 |(((
329 State
330 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
331 (((
332 replace each
333 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
334 (((
335 insert into each
336 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
337 (((
338 insert into each
339 )))
340 |(((
341 Region
342 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
343 (((
344 insert into each
345 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
346 (((
347 replace each, if root: do nothing
348 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
349 (((
350 insert into each
351 )))
352 |(((
353 Transition
354 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
355 (((
356 Connect 2 states
357 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
358 (((
359 add two dummy states with transition in each
360 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
361 (((
362 replace each
363 )))
364 |(((
365 States
366 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
367 (((
368 replace each with all
369 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
370 (((
371 insert all into each
372 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
373 (((
374 insert into each
375 )))
376 |(((
377 Regions
378 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
379 (((
380 insert all into each
381 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
382 (((
383 replace each with all
384 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
385 (((
386 insert into each
387 )))
388 |(((
389 Transitions
390 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
391 (((
392 Connect 2 states with all
393 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
394 (((
395 add two dummy states with all transition in each
396 )))|(% style="text-align: right;" %)(% style="text-align: right;" %)
397 (((
398 replace each with all
399 )))
400
401

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage