Subversion Repositories svn.mios

Rev

Rev 1162 | Rev 1200 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
1119 tk 1
HEADER 3 MIDIbox NG User Manual --- .NGR Script
2
 
3
<P CLASS=INFO><B><A HREF="midibox_ng_manual.html">Back to main page...</A></B></P>
4
 
5
<H1>MIDIbox NG</H1>
6
<H1>User Manual --- .NGR Script</H1>
7
 
8
<P CLASS=INFO>MIDIbox NG provides a (primitive) script language which allows to change values of control elements, to send free definable MIDI events, to output special text strings on LCD and to send debug messages to the MIOS Terminal. It even supports (limited) flowcontrol with if/elsif/else statements.</P>
9
 
10
<P CLASS=DESC>The idea for this script feature came up with the request to run a sequence of value changes (with delays in between) during power-on, resp. after a <A HREF="midibox_ng_manual_ngc.html">.NGC file</A> has been loaded. Over the time it has been enhanced by additional commands to cover other usecases, and meanwhile we even have some kind of flow control!</P>
11
 
12
<P CLASS=DESC>However, the capabilities are still very limited, mainly caused by RAM size limitations of the <A HREF="mbhp_core_lpc17.html">MBHP_CORE_LPC17</A>. See also the "Limitations" chapter at the end of this page.<BR>
13
E.g. the script has to be directly parsed from SD Card whenever it is called, which means that the execution consumes some time (typically 5..50 mS). Call requests are not queued, therefore it can happen that requests get lost if they are triggered while the .NGR file is already processed.</P>
14
 
15
<P CLASS=DESC>Therefore this script language is <B>no replacement</B> for EVENT definitions defined in the <A HREF="midibox_ng_manual_ngc.html">.NGC file</A>! If MIDIbox NG should react on concurrent actions in realtime without the danger that an action gets lost, please define them as EVENTs!<BR>
16
But it's viable solution for events which are processed very rarely, such as special button functions.
17
 
18
<P CLASS=DESC>The .NGR file has the same name like the .NGC file. After power-on MIDIbox NG will load DEFAULT.NGC, and therefore also DEFAULT.NGR (if available).</P>
19
 
20
 
21
<H2> <IMG SRC="images/bullet.gif" ALT=""> Usecases </H2>
22
 
23
<P CLASS=DESC>Here a list of intended usecases:
24
<UL CLASS=CL>
25
  <LI>set values of control elements (LEDs, Buttons, LED Rings, Encoders, etc...) during startup with optional delays (for having some "blink" ;-).<BR>
26
      E.g. a nice sequence of patterns for LEDs and LED Rings by pushing a button to surprise your friends.
27
  <LI>send an informative message to the MIOS Studio terminal.<BR>
28
      E.g. to debug your .NGC setup (or the .NGR execution flow).
29
  <LI>set a control element value depending on conditions, which are derived from other control elements.<BR>
30
      E.g. to implement complex selections (if BUTTON:1 and BUTTON:2 is pressed the same time, do something special...)
31
  <LI>send a fully customizable MIDI messages, even multiple ones triggered by the same event.<BR>
32
      E.g. to select different patches on synthesizers which are connected to different MIDI ports and listen to different MIDI channels.
33
</UL>
34
 
35
<P CLASS=DESC>If you know other interesting usecases which are not listed here, please let me know! :-)
36
 
37
 
38
<H2> <IMG SRC="images/bullet.gif" ALT=""> Calling the .NGR script </H2>
39
 
40
<P CLASS=DESC>The .NGR script can be called with following methods:
41
<UL CLASS=CL>
42
  <LI>it's started automatically with <I>^section == 0</I> after the corresponding .NGC file has been loaded. If you want to prevent the execution, please write following lines at the beginning of the .NGR file:
43
<TT><PRE style="margin-left:10px; font-size:8pt">
44
if ^section == 0
45
  exit
46
endif
47
</PRE></TT>
48
  <LI>it can be started from a Meta event which is defined in the <A HREF="midibox_ng_manual_ngc.html">.NGC file</A>, e.g.:
49
<TT><PRE style="margin-left:10px; font-size:8pt">
50
# start script with ^section == 1
51
EVENT_BUTTON id=1  type=Meta  meta=RunSection:1  button_mode=OnOnly
52
</PRE></TT>
53
 
54
Some configuration examples can be found under <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Frunscr1.ngc" TARGET="_blank">runscr1.ngc</A> (which calls <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Frunscr1.ngr" TARGET="_blank">runscr1.ngr</A>) and <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Frunscr2.ngc" TARGET="_blank">runscr2.ngc</A> (which calls <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Frunscr2.ngr" TARGET="_blank">runscr2.ngr</A>)
55
 
56
  <LI>it can be started from the MIOS Terminal with <I>run &lt;section&gt; &lt;value&gt;</I><BR>
57
The ^section variable will contain the value of <I>&lt;section&gt;</I><BR>
58
And the ^value variable will contain &lt;value&gt;</I><BR>
59
Example:
60
<TT><PRE style="margin-left:10px; font-size:8pt">
61
run 1 127
62
</PRE></TT>
63
</UL>
64
 
65
 
66
<H2> <IMG SRC="images/bullet.gif" ALT=""> Commands </H2>
67
 
68
<P CLASS=DESC>Here a list of available commands:
69
 
70
<TABLE WIDTH="100%" BORDER=0 CELLSPACING=5 CELLPADDING=0>
71
  <TR>
72
    <TH WIDTH=150>Command</TD>
73
    <TH>Description</TD>
74
  </TR>
75
  <TR>
1130 tk 76
    <TD CLASS=TABCOLOR2><I>LCD &lt;string&gt;</I></TD>
1119 tk 77
    <TD CLASS=TABCOLOR2>Prints an immediate message on screen while it's executed.<BR>
78
      All string control formats and directives are supported (see description of <A HREF="midibox_ng_manual_ngc.html">EVENT_* label parameter)</A>, which especially means that it's possible to clear the screen, and to jump to different cursor positions at different displays.<BR>
79
Examples:
80
<TT><PRE style="margin-left:10px; font-size:8pt">
81
# clear screen
82
LCD "%C"
83
 
84
# print message on first line of first LCD
85
LCD "@(1:1:1)Hello World!"
86
 
87
# print message on second line of first LCD
88
LCD "@(1:1:2)Second Line"
89
 
90
# print message on first line of second LCD
91
LCD "@(2:1:1)Second Display"
92
</PRE></TT>
93
    </TD>
94
  </TR>
95
 
96
  <TR>
1130 tk 97
    <TD CLASS=TABCOLOR2><I>LOG &lt;string&gt;</I></TD>
1119 tk 98
    <TD CLASS=TABCOLOR2>Sends a message to the MIOS Terminal.<BR>
99
                        Currently formatted messages are not supported, only static string (could change in future).
100
Example:
101
<TT><PRE style="margin-left:10px; font-size:8pt">
102
LOG "Hello World!"
103
</PRE></TT>
104
    </TD>
105
  </TR>
106
 
107
  <TR>
1130 tk 108
    <TD CLASS=TABCOLOR2><I>SEND &lt;midi-event&gt;</I></TD>
1119 tk 109
    <TD CLASS=TABCOLOR2>Sends a MIDI event. The event definition typically contains:
110
      <UL CLASS=CL>
111
        <LI>the MIDI event type (NoteOff, NoteOn, PolyPressure, CC, ProgramChange, Aftertouch, Pitchbend, NRPN, SysEx)
112
        <LI>the MIDI port (USB1..USB4, OUT1..OUT4, OSC1..OSC4)
113
        <LI>the MIDI channel (1..16)
114
        <LI>one or more values depending on the event type
115
      </UL>
116
Examples:
117
<TT><PRE style="margin-left:10px; font-size:8pt">
118
#    type   port chn key  value
119
send NoteOn USB1   1  36  ^value
120
send NoteOn USB1   1  36  0
121
 
122
#    type         port chn key value
123
send Polypressure USB1   1  36 ^value
124
 
125
#    type port chn key  value
126
send CC   USB1   1  16  ^value
127
 
128
#    type          port chn value
129
send ProgramChange USB1   1 ^value
130
 
131
#    type       port chn value
132
send Aftertouch USB1   1 ^value
133
 
134
#    type      port chn value
135
send PitchBend USB1   1 ^value
136
 
137
#    type port chn number value
138
send NRPN USB1   1 0x0123 ^value
139
 
140
#    type  port stream
141
send SysEx USB1 0xf0 0x11 0x22 0x33 0x44 ^value 0xf7
142
</PRE></TT>
143
    </TD>
144
  </TR>
145
 
146
  <TR>
1130 tk 147
    <TD CLASS=TABCOLOR2><I>EXEC_META &lt;meta-event&gt; [&lt;value&gt;]</I></TD>
1120 tk 148
    <TD CLASS=TABCOLOR2>Executes a meta event with an optional value.<BR>
149
      A list of available meta events can be found in the <A HREF="midibox_ng_manual_ngc.html">.NGC chapter</A>.
150
Examples:
151
<TT><PRE style="margin-left:10px; font-size:8pt">
152
if ^section == 0
153
  exec_meta RetrieveAinserValues
154
  exec_meta DumpSnapshot
155
endif
156
</PRE></TT>
157
 
158
or
159
 
160
<TT><PRE style="margin-left:10px; font-size:8pt">
161
if ^section == 1
162
  exec_meta SetSnapshot 1
163
  exec_meta DumpSnapshot
164
endif
165
</PRE></TT>
166
    </TD>
167
  </TR>
168
 
169
  <TR>
1130 tk 170
    <TD CLASS=TABCOLOR2><I>TRIGGER &lt;id&gt;</I></TD>
1119 tk 171
    <TD CLASS=TABCOLOR2>Triggers a control element with the given <I>&lt;id&gt;</I>, so that it sends out it's MIDI event and prints it's label on LCD.<BR>
172
Example:
173
<TT><PRE style="margin-left:10px; font-size:8pt">
174
# send the MIDI event of the first three pots connected to the AINSER module
175
trigger AINSER:1
176
trigger AINSER:2
177
trigger AINSER:3
178
</PRE></TT>
179
    </TD>
180
  </TR>
181
 
182
  <TR>
1130 tk 183
    <TD CLASS=TABCOLOR2><I>SET &lt;id&gt; &lt;value&gt;</I><BR>
184
                                  <I>SET ^&lt;variable&gt; &lt;value&gt;</I></TD>
1119 tk 185
    <TD CLASS=TABCOLOR2>Similar to TRIGGER, but it also changes the value of the control element.<BR>
186
Example:
187
<TT><PRE style="margin-left:10px; font-size:8pt">
188
# turn on the first 3 LEDs connected to the DOUT module:
189
set LED:1 127
190
set LED:2 127
191
set LED:3 127
192
</PRE></TT>
1130 tk 193
 
194
    The <I>SET</I> command also allows to change the variables: ^section, ^value, ^bank (will change the EVENT banks). And it allows to change the global variables ^dev, ^pat, ^bnk, ^ins, ^chn.<BR>
195
    Examples:
196
<TT><PRE style="margin-left:10px; font-size:8pt">
197
# turn on the first 3 LEDs connected to the DOUT module:
198
set ^section 1
199
set ^value 2
200
set ^bank 3
201
set ^pat ENC:1
202
</PRE></TT>
1119 tk 203
    </TD>
204
  </TR>
205
 
206
  <TR>
1162 tk 207
    <TD CLASS=TABCOLOR2><I>CHANGE &lt;id&gt; &lt;1|0&gt;</I></TD>
208
    <TD CLASS=TABCOLOR2>Similar to <I>SET</I>, but won't trigger a MIDI event.<BR>
209
Example:
210
<TT><PRE style="margin-left:10px; font-size:8pt">
211
set BUTTON:1 42
212
</PRE></TT>
213
will change the button value to 42, but the MIDI event which has been specified for this button won't be generated.
214
  </TR>
215
 
216
  <TR>
1130 tk 217
    <TD CLASS=TABCOLOR2><I>SET_RGB &lt;id&gt; &lt;red&gt;:&lt;green&gt;&lt;blue&gt;</I></TD>
1120 tk 218
    <TD CLASS=TABCOLOR2>Similar to the <I>rgb</I> parameter in the .NGC file, this command allows to change the brightness levels for the three LED layers of a LED matrix. All three values range from 0..15.<BR>
219
Example:
220
<TT><PRE style="margin-left:10px; font-size:8pt">
221
# it's assumed, that a DOUT_MATRIX is configured for all three layers,
222
# and that led_emu_id_offset is set to 1001, so that the LEDs are
223
# individually accessible via LED:1001, LED:1002, ...
224
 
225
# set the RGB levels for multicolour LEDs connected to a DOUT_MATRIX
226
 
227
# Red
228
set_rgb LED:1001 15:0:0
229
 
230
# Green
231
set_rgb LED:1002 0:15:0
232
 
233
# Blue
234
set_rgb LED:1003 0:0:15
235
 
236
# Yellow
237
set_rgb LED:1004 15:15:0
238
 
239
# Cyan
240
set_rgb LED:1005 0:15:15
241
 
242
# Magenta
243
set_rgb LED:1006 15:0:15
244
 
245
# Orange
246
set_rgb LED:1007 15:8:0
247
 
248
# White
249
set_rgb LED:1008 15:15:15
250
 
251
# now turn on the LEDs by setting the maximum value
252
set LED:1001 127
253
set LED:1002 127
254
set LED:1003 127
255
set LED:1004 127
256
set LED:1005 127
257
set LED:1006 127
258
set LED:1007 127
259
set LED:1008 127
260
</PRE></TT>
261
    </TD>
262
  </TR>
263
 
264
  <TR>
1130 tk 265
    <TD CLASS=TABCOLOR2><I>SET_LOCK &lt;id&gt; &lt;1|0&gt;</I></TD>
266
    <TD CLASS=TABCOLOR2>Allows to lock/unlock the MIDI receiver of an EVENT.<BR>
267
    Examples: with
268
<TT><PRE style="margin-left:10px; font-size:8pt">
269
      set_lock ENC:1 1
270
</PRE></TT>
271
    the encoder with hw_id=1 won't change its value on incoming MIDI events anymore (it still can be changed manually when it's moved).<BR>
272
    With:
273
<TT><PRE style="margin-left:10px; font-size:8pt">
274
      set_lock ENC:1 0
275
</PRE></TT>
276
    the encoder will be unlocked, so that it will change the value on a matching incoming MIDI event again (default).
277
    </TD>
278
  </TR>
279
 
280
  <TR>
1148 tk 281
    <TD CLASS=TABCOLOR2><I>SET_ACTIVE &lt;id&gt; &lt;1|0&gt;</I></TD>
282
    <TD CLASS=TABCOLOR2>Can be alternatively used instead of the bank mechanism to activate/deactivate events, e.g. if the same events should be activated in multiple banks under certain conditions. A usage example can be found under:
283
     <UL CLASS=CL>
284
       <LI><A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fmultibnk.ngc" TARGET="_blank">multibnk.ngc</A>
285
       <LI><A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fmultibnk.ngr" TARGET="_blank">multibnk.ngr</A>
286
     </UL>
287
    </TD>
288
  </TR>
289
 
290
  <TR>
1186 tk 291
    <TD CLASS=TABCOLOR2><I>SET_NO_DUMP &lt;id&gt; &lt;1|0&gt;</I></TD>
292
    <TD CLASS=TABCOLOR2>Allows to change the "no_dump" flag which specifies if an EVENT_xxx should be sent during a DumpSnapshot.
293
     This feature can be used to handle different snapshot setups.</TD>
294
  </TR>
295
 
296
  <TR>
1162 tk 297
    <TD CLASS=TABCOLOR2><I>SET_MIN &lt;id&gt; &lt;1|0&gt;</I><BR><I>SET_MAX &lt;id&gt; &lt;1|0&gt;</I></TD>
298
    <TD CLASS=TABCOLOR2>Sets the minimal/maximal value of an event (in the .NGR file specified with range=&lt;min&gt;:&lt;max&gt;.<BR>
299
       Example:
300
<TT><PRE style="margin-left:10px; font-size:8pt">
301
# let the button toggle between 63 and 65
302
set_min BUTTON:1 63
303
set_max BUTTON:1 65
304
</PRE></TT>
305
    </TD>
306
  </TR>
307
 
308
 
309
  <TR>
1130 tk 310
    <TD CLASS=TABCOLOR2><I>DELAY_MS &lt;ms&gt;</I></TD>
1119 tk 311
    <TD CLASS=TABCOLOR2>Delays the execution of the script for the given number of milliseconds.<BR>
312
Example:
313
<TT><PRE style="margin-left:10px; font-size:8pt">
314
set LED:1 127
315
delay_ms 100
316
set LED:1 0
317
 
318
set LED:2 127
319
delay_ms 100
320
set LED:2 0
321
 
322
set LED:3 127
323
delay_ms 100
324
set LED:3 0
325
</PRE></TT>
326
    </TD>
327
  </TR>
328
 
329
  <TR>
1130 tk 330
    <TD CLASS=TABCOLOR2><I>IF</I><BR><I>ELSIF</I><BR><I>ELSE</I><BR><I>ENDIF</I></TD>
1119 tk 331
    <TD CLASS=TABCOLOR2>See special flow control chapter below.
332
    </TD>
333
 
334
  <TR>
1130 tk 335
    <TD CLASS=TABCOLOR2><I>EXIT</I></TD>
1119 tk 336
    <TD CLASS=TABCOLOR2>Stops the execution of the .NGR script.
337
Example:
338
<TT><PRE style="margin-left:10px; font-size:8pt">
339
# don't do anything during startup
340
if ^section == 0
341
  exit
342
endif
343
</PRE></TT>
344
    </TD>
345
  </TR>
346
</TABLE>
347
 
348
 
349
<H2> <IMG SRC="images/bullet.gif" ALT=""> Expressions </H2>
350
 
351
<P CLASS=DESC>All values specified with the SET/SEND/IF/etc... command are handled as expressions which can be:
352
<UL CLASS=CL>
353
  <LI>a constant decimal value from -16384..16384
354
  <LI>a constant hexadecimal value from 0x0..0x3fff
355
  <LI>a constant octal value from 0..037777
1120 tk 356
  <LI>a control element <I>hw_id</I>, e.g. BUTTON:1, ENC:1, AINSER:1, etc... (see next section about IDs)
357
  <LI>a control element <I>id</I>, e.g. (id)BUTTON:1, (id)ENC:1, (id)AINSER:1, etc... (see next section about IDs)
1119 tk 358
  <LI><I>^section</I>: this variable can be passed from the Meta event or "run" terminal command. It's 0 when a .NGC file.
359
  <LI><I>^value</I>: the item value when the script is called from a Meta event.
360
  <LI><I>^bank</I>: the current bank
361
</UL>
362
 
363
<P CLASS=DESC>More ^ variables can be implemented on request.
364
 
365
 
1120 tk 366
<H2> <IMG SRC="images/bullet.gif" ALT=""> IDs </H2>
367
 
368
<P CLASS=DESC>Whenever a control element is addressed with it's id (e.g. BUTTON:1, LED:1, AINSER:1, ENC:1 (see also <A HREF="midibox_ng_manual_ngc.html">.NGC chapter</A>), the parser will search for a matching <B>hardware id</B> (<I>hw_id</I>) by default.</P>
369
 
370
<P CLASS=DESC>This means for example, that a
371
<TT><PRE style="margin-left:50px; font-size:8pt">
372
set LED:1 127
373
</PRE></TT>
374
command will change the value of the first LED connected to the first pin of a DOUT shift register (or emulated LED matrix LED if <I>emu_led_id_offset</I> is used in the DOUT_MATRIX configuration).</P>
375
 
376
<P CLASS=DESC>If no EVENT_LED has been defined in the .NGC file, the hardware will be directly accessed via a virtual event like known from <I>fwd_id</I>.
377
 
378
<P CLASS=DESC>If multiple EVENT_LED are assigned to the same <I>hw_id</I>, but to different <I>bank</I>s, only the EVENT item of the currently selected bank will be accessed.
379
 
380
<P CLASS=DESC>Sometimes you want to access an element based on it's <I>id</I> independent from the current bank selection. Or the specified <I>id</I> doesn't match with the assigned <I>hw_id</I>. For such cases, it's possible to cast this type with the <I>(id)</I>:
381
<TT><PRE style="margin-left:50px; font-size:8pt">
382
# set EVENT_LED id=1 directly without considering the current bank selection
383
set (id)LED:1 127
384
</PRE></TT>
385
 
386
<P CLASS=DESC>For completeness reasons, it's also possible to cast <I>(hw_id)</I>, although this type is used by default:
387
<TT><PRE style="margin-left:50px; font-size:8pt">
388
# set EVENT_LED id=??? hw_id=1
389
set (hw_id)LED:1 127
390
 
391
# is doing the same like:
392
set LED:1 127
393
</PRE></TT>
394
 
395
 
396
<P CLASS=DESC>The casting method is also useful if you want to read a value of a control element independent from the bank selection, such as:
397
<TT><PRE style="margin-left:50px; font-size:8pt">
398
if (id)BUTTON:20 != 0
399
  log "BUTTON:20 is pressed"
400
endif
401
</PRE></TT>
402
 
403
 
1186 tk 404
<H2> <IMG SRC="images/bullet.gif" ALT=""> Operations </H2>
1120 tk 405
 
1186 tk 406
<P CLASS=DESC>Some basic mathematical operations are supported. They have to be surrounded with square-brackets ([...]).</P>
407
 
408
<P CLASS=DESC>Syntax: <I>[&lt;left-operand&gt;&lt;operator&gt;&lt;right-operand&gt;]</I></P>
409
 
410
<P CLASS=DESC>Examples:
411
<UL CLASS=CL>
412
  <LI><I>set LED:2000 [LED:2000 + 1]</I><BR>
413
      will increment the value stored in LED:2000
414
  <LI><I>set LED:2000 [LED:2000 - 1]</I><BR>
415
      will decrement the value stored in LED:2000
416
</UL>
417
</P>
418
 
419
<P CLASS=DESC>Note that nested operations are supported as well, such as:
420
<UL CLASS=CL>
421
  <LI><I>send CC USB1 1 [LED:2000 + [LED:2001 + [LED:2002 + LED:2003]]]</I>
422
</UL>
423
</P>
424
 
425
<P CLASS=DESC>More examples can be found in <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Frunscr5.ngc" TARGET="_blank">runscr5.ngc</A> and <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Frunscr5.ngr" TARGET="_blank">runscr5.ngr</A></P>
426
 
427
<P CLASS=DESC>Support operators:
428
<UL CLASS=CL>
429
  <LI><I>+</I>: addition
430
  <LI><I>-</I>: substraction
431
  <LI><I>*</I>: multiplication
432
  <LI><I>/</I>: divide
433
  <LI><I>%</I>: modulo
434
  <LI><I>&amp;</I>: logical AND
435
  <LI><I>|</I>: logical OR
436
  <LI><I>^</I>: logical XOR
437
</UL>
438
</P>
439
 
440
 
441
 
1119 tk 442
<H2> <IMG SRC="images/bullet.gif" ALT=""> Flow Control </H2>
443
 
444
<P CLASS=DESC>With the IF/ELSIF/ELSE/ENDIF commands it's possible to define condition under which blocks of commands are executed. Nested IF conditions are allowed, the max. depth is 16!</P>
445
 
446
<P CLASS=DESC>A condition consists of a left and right value + a condition in the middle:
447
<LI><I>&lt;left expression&gt; &lt;condition &lt;right expression&gt;</I></P>
448
 
449
<P CLASS=DESC>Examples:
450
<TT><PRE style="margin-left:50px; font-size:8pt">
451
if ^section == 1
452
 
453
  log "Section is 1"
454
endif
455
</PRE></TT>
456
 
457
or:
458
 
459
<TT><PRE style="margin-left:50px; font-size:8pt">
460
if ^section == 1
461
  # initial patches for my synths:
462
  send CC OUT1 1 0 0
463
  send ProgramChange OUT1 1 0
464
 
465
  send CC OUT1 2 0 0
466
  send ProgramChange OUT1 2 0
467
 
468
  send CC OUT1 3 0 0
469
  send ProgramChange OUT1 3 0
470
 
471
  send CC OUT2 1 0 0
472
  send ProgramChange OUT2 1 0
473
 
474
  exit
475
endif
476
 
477
 
478
if ^section == 2
479
  # alternative patches for my synths:
480
  send CC OUT1 1 0 0
481
  send ProgramChange OUT1 1 21
482
 
483
  send CC OUT1 2 0 0
484
  send ProgramChange OUT1 2 1
485
 
486
  send CC OUT1 3 0 0
487
  send ProgramChange OUT1 3 75
488
 
489
  send CC OUT2 1 0 0
490
  send ProgramChange OUT2 1 0x10
491
 
492
  exit
493
endif
494
</PRE></TT>
495
 
496
or:
497
 
498
<TT><PRE style="margin-left:50px; font-size:8pt">
499
if ^section == 1
500
  if BUTTON:1 > 0
501
    if BUTTON:2 > 0
502
      log "BUTTON:1 and BUTTON:2 are pressed"
503
    endif
504
  endif
505
endif
506
</PRE></TT>
507
 
508
<P CLASS=DESC>Supported conditions are: <I>==, !=, &lt;, &lt;=, &gt;, &gt;=</I>.<BR>
509
Logical combinations are not supported.</P>
510
 
511
 
1120 tk 512
<H2> <IMG SRC="images/bullet.gif" ALT=""> Loops (resp. restarting)</H2>
513
 
514
<P CLASS=DESC>Loops are not directly supported. There is neither a "goto"/"jump" command, nor a "do" or "while" loop, to keep the parser algorithm simple.
515
 
516
<P CLASS=DESC>But with following trick it's possible to restart the .NGR script with the <I>RunSection:&lt;section&gt;</I> meta event. As you can see, this even allows to start the .NGR file with a different ^section value.
517
 
518
Usage example:
519
<TT><PRE style="margin-left:50px; font-size:8pt">
520
# don't do anything during startup & patch load
521
if ^section == 0
522
  exit
523
endif
524
 
525
# loop this section as long as BUTTON:2000 is active
526
# Note that this button has been configured for toggle mode!
527
if ^section == 1
528
  log "Section 1 called"
529
 
530
  # do this
531
 
532
  # and that
533
 
534
  # maybe with some delays:
535
  delay_ms 100
536
 
537
  # and finally:
538
  if (id)BUTTON:2000 != 0
539
    LCD "@(1:1:2)loop running "
540
    log "Retriggering section 1"
541
    exec_meta RunSection:1
542
  else
543
    LCD "@(1:1:2)loop finished"
544
    log "Finished."
545
  endif
546
  exit
547
endif
548
</PRE></TT>
549
 
550
<P CLASS=DESC>The files can be found under <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Frunscr3.ngc" TARGET="_blank">runscr3.ngc</A> and <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Frunscr3.ngr" TARGET="_blank">runscr3.ngr</A>.
551
 
552
<P CLASS=DESC>For the case, that you (unintentionally) created an endless loop, it's possible to stop the execution with the "runstop" command in the MIOS Terminal. In addition, it's possible to generate a <I>RunStop</I> meta event with a dedicated button.
553
 
554
 
1119 tk 555
<H2> <IMG SRC="images/bullet.gif" ALT=""> Limitations </H2>
556
 
557
<P CLASS=DESC>The capabilities are still limited, mainly caused by RAM size limitations of the <A HREF="mbhp_core_lpc17.html">MBHP_CORE_LPC17</A>. Following limitations have to be considered:
558
<UL CLASS=CL>
559
  <LI>please don't expect a script language which is so powerful like for example <A HREF="http://www.eluaproject.net" TARGET="_blank">eLua</A>! Although it would be possible to run eLua on a LPC1769, the available RAM isn't sufficient to satisfy the needs for MIDIbox NG in parallel!
560
  <LI>the script has to be directly parsed from SD Card whenever it is called, which means that the execution consumes some time (typically 5..50 mS). Call requests are not queued, therefore it can happen that requests get lost if they are triggered while the .NGR file is already processed.
561
  <LI>It's currently not possible to declare and set customized variables. Limited capabilities could be available in future, but they will consume some RAM!
562
 
563
  <LI>It's not possible to combine conditions in an IF statement (e.g. with && or ||) because this would blow up the parser too much. If this is desired, use nested IF statements on an AND condition, or multiple IF statements on an OR condition.
564
</UL>
565
 
566
FOOTER