Subversion Repositories svn.mios

Rev

Rev 1186 | 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
 
1200 tk 12
<P CLASS=DESC>On a <A HREF="mbhp_core_stm32f4.html">MBHP_CORE_STM32F4</A>, the .NGR script will loaded from SD Card and then compiled into RAM to allow realtime execution of the commands within less than 1 mS! :-)<BR>
13
The <A HREF="mbhp_core_lpc17.html">MBHP_CORE_LPC17</A> module only allows direct execution from SD Card, which is much slower and therefore only allows sporadic interactive operations like special button functions (typically it will take 5..50 mS on this core!).</P>
1119 tk 14
 
15
<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>
16
 
17
 
18
<H2> <IMG SRC="images/bullet.gif" ALT=""> Usecases </H2>
19
 
20
<P CLASS=DESC>Here a list of intended usecases:
21
<UL CLASS=CL>
22
  <LI>set values of control elements (LEDs, Buttons, LED Rings, Encoders, etc...) during startup with optional delays (for having some "blink" ;-).<BR>
23
      E.g. a nice sequence of patterns for LEDs and LED Rings by pushing a button to surprise your friends.
24
  <LI>send an informative message to the MIOS Studio terminal.<BR>
25
      E.g. to debug your .NGC setup (or the .NGR execution flow).
26
  <LI>set a control element value depending on conditions, which are derived from other control elements.<BR>
27
      E.g. to implement complex selections (if BUTTON:1 and BUTTON:2 is pressed the same time, do something special...)
28
  <LI>send a fully customizable MIDI messages, even multiple ones triggered by the same event.<BR>
29
      E.g. to select different patches on synthesizers which are connected to different MIDI ports and listen to different MIDI channels.
1200 tk 30
  <LI><B>MBHP_CORE_STM32F4 only (direct execution from RAM):</B> advanced event processing in realtime
1119 tk 31
</UL>
32
 
33
<P CLASS=DESC>If you know other interesting usecases which are not listed here, please let me know! :-)
34
 
35
 
36
<H2> <IMG SRC="images/bullet.gif" ALT=""> Calling the .NGR script </H2>
37
 
38
<P CLASS=DESC>The .NGR script can be called with following methods:
39
<UL CLASS=CL>
40
  <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:
41
<TT><PRE style="margin-left:10px; font-size:8pt">
42
if ^section == 0
43
  exit
44
endif
45
</PRE></TT>
46
  <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.:
47
<TT><PRE style="margin-left:10px; font-size:8pt">
48
# start script with ^section == 1
49
EVENT_BUTTON id=1  type=Meta  meta=RunSection:1  button_mode=OnOnly
50
</PRE></TT>
51
 
52
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>)
53
 
54
  <LI>it can be started from the MIOS Terminal with <I>run &lt;section&gt; &lt;value&gt;</I><BR>
55
The ^section variable will contain the value of <I>&lt;section&gt;</I><BR>
56
And the ^value variable will contain &lt;value&gt;</I><BR>
57
Example:
58
<TT><PRE style="margin-left:10px; font-size:8pt">
59
run 1 127
60
</PRE></TT>
61
</UL>
62
 
63
 
64
<H2> <IMG SRC="images/bullet.gif" ALT=""> Commands </H2>
65
 
66
<P CLASS=DESC>Here a list of available commands:
67
 
68
<TABLE WIDTH="100%" BORDER=0 CELLSPACING=5 CELLPADDING=0>
69
  <TR>
70
    <TH WIDTH=150>Command</TD>
71
    <TH>Description</TD>
72
  </TR>
73
  <TR>
1130 tk 74
    <TD CLASS=TABCOLOR2><I>LCD &lt;string&gt;</I></TD>
1119 tk 75
    <TD CLASS=TABCOLOR2>Prints an immediate message on screen while it's executed.<BR>
76
      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>
77
Examples:
78
<TT><PRE style="margin-left:10px; font-size:8pt">
79
# clear screen
80
LCD "%C"
81
 
82
# print message on first line of first LCD
83
LCD "@(1:1:1)Hello World!"
84
 
85
# print message on second line of first LCD
86
LCD "@(1:1:2)Second Line"
87
 
88
# print message on first line of second LCD
89
LCD "@(2:1:1)Second Display"
90
</PRE></TT>
91
    </TD>
92
  </TR>
93
 
94
  <TR>
1130 tk 95
    <TD CLASS=TABCOLOR2><I>LOG &lt;string&gt;</I></TD>
1119 tk 96
    <TD CLASS=TABCOLOR2>Sends a message to the MIOS Terminal.<BR>
97
                        Currently formatted messages are not supported, only static string (could change in future).
98
Example:
99
<TT><PRE style="margin-left:10px; font-size:8pt">
100
LOG "Hello World!"
101
</PRE></TT>
102
    </TD>
103
  </TR>
104
 
105
  <TR>
1130 tk 106
    <TD CLASS=TABCOLOR2><I>SEND &lt;midi-event&gt;</I></TD>
1119 tk 107
    <TD CLASS=TABCOLOR2>Sends a MIDI event. The event definition typically contains:
108
      <UL CLASS=CL>
109
        <LI>the MIDI event type (NoteOff, NoteOn, PolyPressure, CC, ProgramChange, Aftertouch, Pitchbend, NRPN, SysEx)
110
        <LI>the MIDI port (USB1..USB4, OUT1..OUT4, OSC1..OSC4)
111
        <LI>the MIDI channel (1..16)
112
        <LI>one or more values depending on the event type
113
      </UL>
114
Examples:
115
<TT><PRE style="margin-left:10px; font-size:8pt">
116
#    type   port chn key  value
117
send NoteOn USB1   1  36  ^value
118
send NoteOn USB1   1  36  0
119
 
120
#    type         port chn key value
121
send Polypressure USB1   1  36 ^value
122
 
123
#    type port chn key  value
124
send CC   USB1   1  16  ^value
125
 
126
#    type          port chn value
127
send ProgramChange USB1   1 ^value
128
 
129
#    type       port chn value
130
send Aftertouch USB1   1 ^value
131
 
132
#    type      port chn value
133
send PitchBend USB1   1 ^value
134
 
135
#    type port chn number value
136
send NRPN USB1   1 0x0123 ^value
137
 
138
#    type  port stream
139
send SysEx USB1 0xf0 0x11 0x22 0x33 0x44 ^value 0xf7
140
</PRE></TT>
141
    </TD>
142
  </TR>
143
 
144
  <TR>
1130 tk 145
    <TD CLASS=TABCOLOR2><I>EXEC_META &lt;meta-event&gt; [&lt;value&gt;]</I></TD>
1120 tk 146
    <TD CLASS=TABCOLOR2>Executes a meta event with an optional value.<BR>
147
      A list of available meta events can be found in the <A HREF="midibox_ng_manual_ngc.html">.NGC chapter</A>.
148
Examples:
149
<TT><PRE style="margin-left:10px; font-size:8pt">
150
if ^section == 0
1200 tk 151
  # wait until all values have been scanned (consider 2 seconds startup delay + a little bit margin)
152
  delay_ms 2500
153
 
154
  # now capture the AINSER values
1120 tk 155
  exec_meta RetrieveAinserValues
1200 tk 156
 
157
  # and dump out values
1120 tk 158
  exec_meta DumpSnapshot
159
endif
160
</PRE></TT>
161
 
162
or
163
 
164
<TT><PRE style="margin-left:10px; font-size:8pt">
165
if ^section == 1
166
  exec_meta SetSnapshot 1
167
  exec_meta DumpSnapshot
168
endif
169
</PRE></TT>
170
    </TD>
171
  </TR>
172
 
173
  <TR>
1130 tk 174
    <TD CLASS=TABCOLOR2><I>TRIGGER &lt;id&gt;</I></TD>
1119 tk 175
    <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>
176
Example:
177
<TT><PRE style="margin-left:10px; font-size:8pt">
178
# send the MIDI event of the first three pots connected to the AINSER module
179
trigger AINSER:1
180
trigger AINSER:2
181
trigger AINSER:3
182
</PRE></TT>
183
    </TD>
184
  </TR>
185
 
186
  <TR>
1130 tk 187
    <TD CLASS=TABCOLOR2><I>SET &lt;id&gt; &lt;value&gt;</I><BR>
188
                                  <I>SET ^&lt;variable&gt; &lt;value&gt;</I></TD>
1119 tk 189
    <TD CLASS=TABCOLOR2>Similar to TRIGGER, but it also changes the value of the control element.<BR>
190
Example:
191
<TT><PRE style="margin-left:10px; font-size:8pt">
192
# turn on the first 3 LEDs connected to the DOUT module:
193
set LED:1 127
194
set LED:2 127
195
set LED:3 127
196
</PRE></TT>
1130 tk 197
 
198
    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>
199
    Examples:
200
<TT><PRE style="margin-left:10px; font-size:8pt">
201
# turn on the first 3 LEDs connected to the DOUT module:
202
set ^section 1
203
set ^value 2
204
set ^bank 3
205
set ^pat ENC:1
206
</PRE></TT>
1119 tk 207
    </TD>
208
  </TR>
209
 
210
  <TR>
1162 tk 211
    <TD CLASS=TABCOLOR2><I>CHANGE &lt;id&gt; &lt;1|0&gt;</I></TD>
212
    <TD CLASS=TABCOLOR2>Similar to <I>SET</I>, but won't trigger a MIDI event.<BR>
213
Example:
214
<TT><PRE style="margin-left:10px; font-size:8pt">
215
set BUTTON:1 42
216
</PRE></TT>
217
will change the button value to 42, but the MIDI event which has been specified for this button won't be generated.
218
  </TR>
219
 
220
  <TR>
1130 tk 221
    <TD CLASS=TABCOLOR2><I>SET_RGB &lt;id&gt; &lt;red&gt;:&lt;green&gt;&lt;blue&gt;</I></TD>
1120 tk 222
    <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>
223
Example:
224
<TT><PRE style="margin-left:10px; font-size:8pt">
225
# it's assumed, that a DOUT_MATRIX is configured for all three layers,
226
# and that led_emu_id_offset is set to 1001, so that the LEDs are
227
# individually accessible via LED:1001, LED:1002, ...
228
 
229
# set the RGB levels for multicolour LEDs connected to a DOUT_MATRIX
230
 
231
# Red
232
set_rgb LED:1001 15:0:0
233
 
234
# Green
235
set_rgb LED:1002 0:15:0
236
 
237
# Blue
238
set_rgb LED:1003 0:0:15
239
 
240
# Yellow
241
set_rgb LED:1004 15:15:0
242
 
243
# Cyan
244
set_rgb LED:1005 0:15:15
245
 
246
# Magenta
247
set_rgb LED:1006 15:0:15
248
 
249
# Orange
250
set_rgb LED:1007 15:8:0
251
 
252
# White
253
set_rgb LED:1008 15:15:15
254
 
255
# now turn on the LEDs by setting the maximum value
256
set LED:1001 127
257
set LED:1002 127
258
set LED:1003 127
259
set LED:1004 127
260
set LED:1005 127
261
set LED:1006 127
262
set LED:1007 127
263
set LED:1008 127
264
</PRE></TT>
265
    </TD>
266
  </TR>
267
 
268
  <TR>
1200 tk 269
    <TD CLASS=TABCOLOR2><I>SET_HSV &lt;id&gt; &lt;h&gt;:&lt;s&gt;&lt;v&gt;</I></TD>
270
    <TD CLASS=TABCOLOR2>Sets the hue/saturation/value colour code of a WS2812 based RGBLED. H ranges from 0..359 (grad); saturation and value (brightness) range from 0..100 (percentage)<BR>
271
Example:
272
<TT><PRE style="margin-left:10px; font-size:8pt">
273
# red
274
set_hsv RGBLED:1 0:100:25
275
 
276
# green
277
set_hsv RGBLED:2 120:100:25
278
 
279
# blue
280
set_hsv RGBLED:3 240:100:25
281
</PRE></TT>
282
    </TD>
283
  </TR>
284
 
285
  <TR>
1130 tk 286
    <TD CLASS=TABCOLOR2><I>SET_LOCK &lt;id&gt; &lt;1|0&gt;</I></TD>
287
    <TD CLASS=TABCOLOR2>Allows to lock/unlock the MIDI receiver of an EVENT.<BR>
288
    Examples: with
289
<TT><PRE style="margin-left:10px; font-size:8pt">
290
      set_lock ENC:1 1
291
</PRE></TT>
292
    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>
293
    With:
294
<TT><PRE style="margin-left:10px; font-size:8pt">
295
      set_lock ENC:1 0
296
</PRE></TT>
297
    the encoder will be unlocked, so that it will change the value on a matching incoming MIDI event again (default).
298
    </TD>
299
  </TR>
300
 
301
  <TR>
1148 tk 302
    <TD CLASS=TABCOLOR2><I>SET_ACTIVE &lt;id&gt; &lt;1|0&gt;</I></TD>
303
    <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:
304
     <UL CLASS=CL>
305
       <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>
306
       <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>
307
     </UL>
308
    </TD>
309
  </TR>
310
 
311
  <TR>
1186 tk 312
    <TD CLASS=TABCOLOR2><I>SET_NO_DUMP &lt;id&gt; &lt;1|0&gt;</I></TD>
313
    <TD CLASS=TABCOLOR2>Allows to change the "no_dump" flag which specifies if an EVENT_xxx should be sent during a DumpSnapshot.
314
     This feature can be used to handle different snapshot setups.</TD>
315
  </TR>
316
 
317
  <TR>
1162 tk 318
    <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>
319
    <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>
320
       Example:
321
<TT><PRE style="margin-left:10px; font-size:8pt">
322
# let the button toggle between 63 and 65
323
set_min BUTTON:1 63
324
set_max BUTTON:1 65
325
</PRE></TT>
326
    </TD>
327
  </TR>
328
 
329
 
330
  <TR>
1130 tk 331
    <TD CLASS=TABCOLOR2><I>DELAY_MS &lt;ms&gt;</I></TD>
1119 tk 332
    <TD CLASS=TABCOLOR2>Delays the execution of the script for the given number of milliseconds.<BR>
333
Example:
334
<TT><PRE style="margin-left:10px; font-size:8pt">
335
set LED:1 127
336
delay_ms 100
337
set LED:1 0
338
 
339
set LED:2 127
340
delay_ms 100
341
set LED:2 0
342
 
343
set LED:3 127
344
delay_ms 100
345
set LED:3 0
346
</PRE></TT>
347
    </TD>
348
  </TR>
349
 
350
  <TR>
1200 tk 351
    <TD CLASS=TABCOLOR2><I>LOAD &lt;setup&gt;</I></TD>
352
    <TD CLASS=TABCOLOR2>Switch to another setup (.NGC, .NGS, .NGR, ... files)
353
    </TD>
354
  </TR>
355
 
356
  <TR>
1130 tk 357
    <TD CLASS=TABCOLOR2><I>IF</I><BR><I>ELSIF</I><BR><I>ELSE</I><BR><I>ENDIF</I></TD>
1119 tk 358
    <TD CLASS=TABCOLOR2>See special flow control chapter below.
359
    </TD>
360
 
361
  <TR>
1130 tk 362
    <TD CLASS=TABCOLOR2><I>EXIT</I></TD>
1119 tk 363
    <TD CLASS=TABCOLOR2>Stops the execution of the .NGR script.
364
Example:
365
<TT><PRE style="margin-left:10px; font-size:8pt">
366
# don't do anything during startup
367
if ^section == 0
368
  exit
369
endif
370
</PRE></TT>
371
    </TD>
372
  </TR>
373
</TABLE>
374
 
375
 
376
<H2> <IMG SRC="images/bullet.gif" ALT=""> Expressions </H2>
377
 
378
<P CLASS=DESC>All values specified with the SET/SEND/IF/etc... command are handled as expressions which can be:
379
<UL CLASS=CL>
380
  <LI>a constant decimal value from -16384..16384
381
  <LI>a constant hexadecimal value from 0x0..0x3fff
382
  <LI>a constant octal value from 0..037777
1120 tk 383
  <LI>a control element <I>hw_id</I>, e.g. BUTTON:1, ENC:1, AINSER:1, etc... (see next section about IDs)
384
  <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 385
  <LI><I>^section</I>: this variable can be passed from the Meta event or "run" terminal command. It's 0 when a .NGC file.
386
  <LI><I>^value</I>: the item value when the script is called from a Meta event.
387
  <LI><I>^bank</I>: the current bank
388
</UL>
389
 
390
<P CLASS=DESC>More ^ variables can be implemented on request.
391
 
392
 
1120 tk 393
<H2> <IMG SRC="images/bullet.gif" ALT=""> IDs </H2>
394
 
395
<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>
396
 
397
<P CLASS=DESC>This means for example, that a
398
<TT><PRE style="margin-left:50px; font-size:8pt">
399
set LED:1 127
400
</PRE></TT>
401
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>
402
 
403
<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>.
404
 
405
<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.
406
 
407
<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>:
408
<TT><PRE style="margin-left:50px; font-size:8pt">
409
# set EVENT_LED id=1 directly without considering the current bank selection
410
set (id)LED:1 127
411
</PRE></TT>
412
 
413
<P CLASS=DESC>For completeness reasons, it's also possible to cast <I>(hw_id)</I>, although this type is used by default:
414
<TT><PRE style="margin-left:50px; font-size:8pt">
415
# set EVENT_LED id=??? hw_id=1
416
set (hw_id)LED:1 127
417
 
418
# is doing the same like:
419
set LED:1 127
420
</PRE></TT>
421
 
422
 
423
<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:
424
<TT><PRE style="margin-left:50px; font-size:8pt">
425
if (id)BUTTON:20 != 0
426
  log "BUTTON:20 is pressed"
427
endif
428
</PRE></TT>
429
 
430
 
1186 tk 431
<H2> <IMG SRC="images/bullet.gif" ALT=""> Operations </H2>
1120 tk 432
 
1186 tk 433
<P CLASS=DESC>Some basic mathematical operations are supported. They have to be surrounded with square-brackets ([...]).</P>
434
 
435
<P CLASS=DESC>Syntax: <I>[&lt;left-operand&gt;&lt;operator&gt;&lt;right-operand&gt;]</I></P>
436
 
437
<P CLASS=DESC>Examples:
438
<UL CLASS=CL>
439
  <LI><I>set LED:2000 [LED:2000 + 1]</I><BR>
440
      will increment the value stored in LED:2000
441
  <LI><I>set LED:2000 [LED:2000 - 1]</I><BR>
442
      will decrement the value stored in LED:2000
443
</UL>
444
</P>
445
 
446
<P CLASS=DESC>Note that nested operations are supported as well, such as:
447
<UL CLASS=CL>
448
  <LI><I>send CC USB1 1 [LED:2000 + [LED:2001 + [LED:2002 + LED:2003]]]</I>
449
</UL>
450
</P>
451
 
452
<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>
453
 
454
<P CLASS=DESC>Support operators:
455
<UL CLASS=CL>
456
  <LI><I>+</I>: addition
457
  <LI><I>-</I>: substraction
458
  <LI><I>*</I>: multiplication
459
  <LI><I>/</I>: divide
460
  <LI><I>%</I>: modulo
461
  <LI><I>&amp;</I>: logical AND
462
  <LI><I>|</I>: logical OR
463
  <LI><I>^</I>: logical XOR
464
</UL>
465
</P>
466
 
467
 
468
 
1119 tk 469
<H2> <IMG SRC="images/bullet.gif" ALT=""> Flow Control </H2>
470
 
471
<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>
472
 
473
<P CLASS=DESC>A condition consists of a left and right value + a condition in the middle:
474
<LI><I>&lt;left expression&gt; &lt;condition &lt;right expression&gt;</I></P>
475
 
476
<P CLASS=DESC>Examples:
477
<TT><PRE style="margin-left:50px; font-size:8pt">
478
if ^section == 1
479
 
480
  log "Section is 1"
481
endif
482
</PRE></TT>
483
 
484
or:
485
 
486
<TT><PRE style="margin-left:50px; font-size:8pt">
487
if ^section == 1
488
  # initial patches for my synths:
489
  send CC OUT1 1 0 0
490
  send ProgramChange OUT1 1 0
491
 
492
  send CC OUT1 2 0 0
493
  send ProgramChange OUT1 2 0
494
 
495
  send CC OUT1 3 0 0
496
  send ProgramChange OUT1 3 0
497
 
498
  send CC OUT2 1 0 0
499
  send ProgramChange OUT2 1 0
500
 
501
  exit
502
endif
503
 
504
 
505
if ^section == 2
506
  # alternative patches for my synths:
507
  send CC OUT1 1 0 0
508
  send ProgramChange OUT1 1 21
509
 
510
  send CC OUT1 2 0 0
511
  send ProgramChange OUT1 2 1
512
 
513
  send CC OUT1 3 0 0
514
  send ProgramChange OUT1 3 75
515
 
516
  send CC OUT2 1 0 0
517
  send ProgramChange OUT2 1 0x10
518
 
519
  exit
520
endif
521
</PRE></TT>
522
 
523
or:
524
 
525
<TT><PRE style="margin-left:50px; font-size:8pt">
526
if ^section == 1
527
  if BUTTON:1 > 0
528
    if BUTTON:2 > 0
529
      log "BUTTON:1 and BUTTON:2 are pressed"
530
    endif
531
  endif
532
endif
533
</PRE></TT>
534
 
535
<P CLASS=DESC>Supported conditions are: <I>==, !=, &lt;, &lt;=, &gt;, &gt;=</I>.<BR>
536
Logical combinations are not supported.</P>
537
 
538
 
1120 tk 539
<H2> <IMG SRC="images/bullet.gif" ALT=""> Loops (resp. restarting)</H2>
540
 
541
<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.
542
 
543
<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.
544
 
545
Usage example:
546
<TT><PRE style="margin-left:50px; font-size:8pt">
547
# don't do anything during startup & patch load
548
if ^section == 0
549
  exit
550
endif
551
 
552
# loop this section as long as BUTTON:2000 is active
553
# Note that this button has been configured for toggle mode!
554
if ^section == 1
555
  log "Section 1 called"
556
 
557
  # do this
558
 
559
  # and that
560
 
561
  # maybe with some delays:
562
  delay_ms 100
563
 
564
  # and finally:
565
  if (id)BUTTON:2000 != 0
566
    LCD "@(1:1:2)loop running "
567
    log "Retriggering section 1"
568
    exec_meta RunSection:1
569
  else
570
    LCD "@(1:1:2)loop finished"
571
    log "Finished."
572
  endif
573
  exit
574
endif
575
</PRE></TT>
576
 
577
<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>.
578
 
579
<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.
580
 
581
 
1119 tk 582
<H2> <IMG SRC="images/bullet.gif" ALT=""> Limitations </H2>
583
 
584
<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:
585
<UL CLASS=CL>
586
  <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!
587
  <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!
588
  <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.
589
</UL>
590
 
591
FOOTER