Subversion Repositories svn.mios

Rev

Rev 1200 | 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>
1231 tk 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. %d etc. will print the current ^value<BR>
1119 tk 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>
1231 tk 145
    <TD CLASS=TABCOLOR2><I>SEND_SEQ &lt;delay&gt; &lt;length&gt; &lt;type&gt; &lt;port&gt; &lt;chn&gt; &lt;key|cc&gt; &lt;velocity|value&gt;</I></TD>
146
    <TD CLASS=TABCOLOR2>A very powerful command which allows to sequence MIDI events, e.g. to play tunes or even to create a simple step sequencer!<BR>
147
      Please find examples under:
148
      <UL CLASS=CL>
149
        <LI><A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fseq1.ngr" TARGET="_blank">seq1.ngr</A>/<A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fseq1.ngc" TARGET="_blank">seq1.ngc</A>: a 16 step note sequencer controlled from 16 rotary encoders
150
        <LI><A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fseq2.ngr" TARGET="_blank">seq2.ngr</A>/<A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fseq1.ngc" TARGET="_blank">seq1.ngc</A>: a 8 step note sequencer controlled from 16 rotary encoders (upper row: notes, lower row: velocity
151
        <LI><A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fseq3.ngr" TARGET="_blank">seq3.ngr</A>/<A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fseq1.ngc" TARGET="_blank">seq1.ngc</A>: a 16 step CC sequencer controlled from 16 rotary encoders
152
      </UL>
153
    </TD>
154
  </TR>
155
 
156
  <TR>
1130 tk 157
    <TD CLASS=TABCOLOR2><I>EXEC_META &lt;meta-event&gt; [&lt;value&gt;]</I></TD>
1120 tk 158
    <TD CLASS=TABCOLOR2>Executes a meta event with an optional value.<BR>
159
      A list of available meta events can be found in the <A HREF="midibox_ng_manual_ngc.html">.NGC chapter</A>.
160
Examples:
161
<TT><PRE style="margin-left:10px; font-size:8pt">
162
if ^section == 0
1200 tk 163
  # wait until all values have been scanned (consider 2 seconds startup delay + a little bit margin)
164
  delay_ms 2500
165
 
166
  # now capture the AINSER values
1120 tk 167
  exec_meta RetrieveAinserValues
1200 tk 168
 
169
  # and dump out values
1120 tk 170
  exec_meta DumpSnapshot
171
endif
172
</PRE></TT>
173
 
174
or
175
 
176
<TT><PRE style="margin-left:10px; font-size:8pt">
177
if ^section == 1
178
  exec_meta SetSnapshot 1
179
  exec_meta DumpSnapshot
180
endif
181
</PRE></TT>
182
    </TD>
183
  </TR>
184
 
185
  <TR>
1130 tk 186
    <TD CLASS=TABCOLOR2><I>TRIGGER &lt;id&gt;</I></TD>
1119 tk 187
    <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>
188
Example:
189
<TT><PRE style="margin-left:10px; font-size:8pt">
190
# send the MIDI event of the first three pots connected to the AINSER module
191
trigger AINSER:1
192
trigger AINSER:2
193
trigger AINSER:3
194
</PRE></TT>
195
    </TD>
196
  </TR>
197
 
198
  <TR>
1130 tk 199
    <TD CLASS=TABCOLOR2><I>SET &lt;id&gt; &lt;value&gt;</I><BR>
200
                                  <I>SET ^&lt;variable&gt; &lt;value&gt;</I></TD>
1119 tk 201
    <TD CLASS=TABCOLOR2>Similar to TRIGGER, but it also changes the value of the control element.<BR>
202
Example:
203
<TT><PRE style="margin-left:10px; font-size:8pt">
204
# turn on the first 3 LEDs connected to the DOUT module:
205
set LED:1 127
206
set LED:2 127
207
set LED:3 127
208
</PRE></TT>
1130 tk 209
 
210
    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>
211
    Examples:
212
<TT><PRE style="margin-left:10px; font-size:8pt">
213
# turn on the first 3 LEDs connected to the DOUT module:
214
set ^section 1
215
set ^value 2
216
set ^bank 3
217
set ^pat ENC:1
218
</PRE></TT>
1119 tk 219
    </TD>
220
  </TR>
221
 
222
  <TR>
1162 tk 223
    <TD CLASS=TABCOLOR2><I>CHANGE &lt;id&gt; &lt;1|0&gt;</I></TD>
224
    <TD CLASS=TABCOLOR2>Similar to <I>SET</I>, but won't trigger a MIDI event.<BR>
225
Example:
226
<TT><PRE style="margin-left:10px; font-size:8pt">
227
set BUTTON:1 42
228
</PRE></TT>
229
will change the button value to 42, but the MIDI event which has been specified for this button won't be generated.
230
  </TR>
231
 
232
  <TR>
1130 tk 233
    <TD CLASS=TABCOLOR2><I>SET_RGB &lt;id&gt; &lt;red&gt;:&lt;green&gt;&lt;blue&gt;</I></TD>
1120 tk 234
    <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>
235
Example:
236
<TT><PRE style="margin-left:10px; font-size:8pt">
237
# it's assumed, that a DOUT_MATRIX is configured for all three layers,
238
# and that led_emu_id_offset is set to 1001, so that the LEDs are
239
# individually accessible via LED:1001, LED:1002, ...
240
 
241
# set the RGB levels for multicolour LEDs connected to a DOUT_MATRIX
242
 
243
# Red
244
set_rgb LED:1001 15:0:0
245
 
246
# Green
247
set_rgb LED:1002 0:15:0
248
 
249
# Blue
250
set_rgb LED:1003 0:0:15
251
 
252
# Yellow
253
set_rgb LED:1004 15:15:0
254
 
255
# Cyan
256
set_rgb LED:1005 0:15:15
257
 
258
# Magenta
259
set_rgb LED:1006 15:0:15
260
 
261
# Orange
262
set_rgb LED:1007 15:8:0
263
 
264
# White
265
set_rgb LED:1008 15:15:15
266
 
267
# now turn on the LEDs by setting the maximum value
268
set LED:1001 127
269
set LED:1002 127
270
set LED:1003 127
271
set LED:1004 127
272
set LED:1005 127
273
set LED:1006 127
274
set LED:1007 127
275
set LED:1008 127
276
</PRE></TT>
277
    </TD>
278
  </TR>
279
 
280
  <TR>
1200 tk 281
    <TD CLASS=TABCOLOR2><I>SET_HSV &lt;id&gt; &lt;h&gt;:&lt;s&gt;&lt;v&gt;</I></TD>
282
    <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>
283
Example:
284
<TT><PRE style="margin-left:10px; font-size:8pt">
285
# red
286
set_hsv RGBLED:1 0:100:25
287
 
288
# green
289
set_hsv RGBLED:2 120:100:25
290
 
291
# blue
292
set_hsv RGBLED:3 240:100:25
293
</PRE></TT>
294
    </TD>
295
  </TR>
296
 
297
  <TR>
1130 tk 298
    <TD CLASS=TABCOLOR2><I>SET_LOCK &lt;id&gt; &lt;1|0&gt;</I></TD>
299
    <TD CLASS=TABCOLOR2>Allows to lock/unlock the MIDI receiver of an EVENT.<BR>
300
    Examples: with
301
<TT><PRE style="margin-left:10px; font-size:8pt">
302
      set_lock ENC:1 1
303
</PRE></TT>
304
    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>
305
    With:
306
<TT><PRE style="margin-left:10px; font-size:8pt">
307
      set_lock ENC:1 0
308
</PRE></TT>
309
    the encoder will be unlocked, so that it will change the value on a matching incoming MIDI event again (default).
310
    </TD>
311
  </TR>
312
 
313
  <TR>
1148 tk 314
    <TD CLASS=TABCOLOR2><I>SET_ACTIVE &lt;id&gt; &lt;1|0&gt;</I></TD>
315
    <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:
316
     <UL CLASS=CL>
317
       <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>
318
       <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>
319
     </UL>
320
    </TD>
321
  </TR>
322
 
323
  <TR>
1186 tk 324
    <TD CLASS=TABCOLOR2><I>SET_NO_DUMP &lt;id&gt; &lt;1|0&gt;</I></TD>
325
    <TD CLASS=TABCOLOR2>Allows to change the "no_dump" flag which specifies if an EVENT_xxx should be sent during a DumpSnapshot.
326
     This feature can be used to handle different snapshot setups.</TD>
327
  </TR>
328
 
329
  <TR>
1162 tk 330
    <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>
331
    <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>
332
       Example:
333
<TT><PRE style="margin-left:10px; font-size:8pt">
334
# let the button toggle between 63 and 65
335
set_min BUTTON:1 63
336
set_max BUTTON:1 65
337
</PRE></TT>
338
    </TD>
339
  </TR>
340
 
341
 
342
  <TR>
1130 tk 343
    <TD CLASS=TABCOLOR2><I>DELAY_MS &lt;ms&gt;</I></TD>
1119 tk 344
    <TD CLASS=TABCOLOR2>Delays the execution of the script for the given number of milliseconds.<BR>
345
Example:
346
<TT><PRE style="margin-left:10px; font-size:8pt">
347
set LED:1 127
348
delay_ms 100
349
set LED:1 0
350
 
351
set LED:2 127
352
delay_ms 100
353
set LED:2 0
354
 
355
set LED:3 127
356
delay_ms 100
357
set LED:3 0
358
</PRE></TT>
359
    </TD>
360
  </TR>
361
 
362
  <TR>
1231 tk 363
    <TD CLASS=TABCOLOR2><I>SET_KB_TRANSPOSE &lt;KB:1|2&gt; &lt;transpose-value&gt;</I></TD>
364
    <TD CLASS=TABCOLOR2>Sets the keyboard transpose value.
365
Example:
366
<TT><PRE style="margin-left:10px; font-size:8pt">
367
set_kb_transpose KB:1 ^value
368
</PRE></TT>
369
will change the transpose according to a given ^value, e.g. from an rotary encoder. See also <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fkb_6.ngr" TARGET="_blank">kb_6.ngr</A>/<A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fkb_6.ngc" TARGET="_blank">kb_6.ngc</A>
370
  </TR>
371
 
372
  <TR>
373
    <TD CLASS=TABCOLOR2><I>SET_KB_VELOCITY_MAP &lt;KB:1|2&gt; &lt;velocity-map&gt;</I></TD>
374
    <TD CLASS=TABCOLOR2>Sets the keyboard transpose value.
375
Example:
376
<TT><PRE style="margin-left:10px; font-size:8pt">
377
set_kb_velocity_map KB:1 3
378
</PRE></TT>
379
will change the velocity map according to a given value (here: 3), e.g. triggered by a button. See also <A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fkb_6.ngr" TARGET="_blank">kb_6.ngr</A>/<A HREF="http://svnmios.midibox.org/filedetails.php?repname=svn.mios32&path=%2Ftrunk%2Fapps%2Fcontrollers%2Fmidibox_ng_v1%2Fcfg%2Ftests%2Fkb_6.ngc" TARGET="_blank">kb_6.ngc</A>
380
  </TR>
381
 
382
  <TR>
1200 tk 383
    <TD CLASS=TABCOLOR2><I>LOAD &lt;setup&gt;</I></TD>
384
    <TD CLASS=TABCOLOR2>Switch to another setup (.NGC, .NGS, .NGR, ... files)
385
    </TD>
386
  </TR>
387
 
388
  <TR>
1130 tk 389
    <TD CLASS=TABCOLOR2><I>IF</I><BR><I>ELSIF</I><BR><I>ELSE</I><BR><I>ENDIF</I></TD>
1119 tk 390
    <TD CLASS=TABCOLOR2>See special flow control chapter below.
391
    </TD>
392
 
393
  <TR>
1130 tk 394
    <TD CLASS=TABCOLOR2><I>EXIT</I></TD>
1119 tk 395
    <TD CLASS=TABCOLOR2>Stops the execution of the .NGR script.
396
Example:
397
<TT><PRE style="margin-left:10px; font-size:8pt">
398
# don't do anything during startup
399
if ^section == 0
400
  exit
401
endif
402
</PRE></TT>
403
    </TD>
404
  </TR>
405
</TABLE>
406
 
407
 
408
<H2> <IMG SRC="images/bullet.gif" ALT=""> Expressions </H2>
409
 
410
<P CLASS=DESC>All values specified with the SET/SEND/IF/etc... command are handled as expressions which can be:
411
<UL CLASS=CL>
412
  <LI>a constant decimal value from -16384..16384
413
  <LI>a constant hexadecimal value from 0x0..0x3fff
414
  <LI>a constant octal value from 0..037777
1120 tk 415
  <LI>a control element <I>hw_id</I>, e.g. BUTTON:1, ENC:1, AINSER:1, etc... (see next section about IDs)
416
  <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 417
  <LI><I>^section</I>: this variable can be passed from the Meta event or "run" terminal command. It's 0 when a .NGC file.
418
  <LI><I>^value</I>: the item value when the script is called from a Meta event.
419
  <LI><I>^bank</I>: the current bank
420
</UL>
421
 
422
<P CLASS=DESC>More ^ variables can be implemented on request.
423
 
424
 
1120 tk 425
<H2> <IMG SRC="images/bullet.gif" ALT=""> IDs </H2>
426
 
427
<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>
428
 
429
<P CLASS=DESC>This means for example, that a
430
<TT><PRE style="margin-left:50px; font-size:8pt">
431
set LED:1 127
432
</PRE></TT>
433
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>
434
 
435
<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>.
436
 
437
<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.
438
 
439
<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>:
440
<TT><PRE style="margin-left:50px; font-size:8pt">
441
# set EVENT_LED id=1 directly without considering the current bank selection
442
set (id)LED:1 127
443
</PRE></TT>
444
 
445
<P CLASS=DESC>For completeness reasons, it's also possible to cast <I>(hw_id)</I>, although this type is used by default:
446
<TT><PRE style="margin-left:50px; font-size:8pt">
447
# set EVENT_LED id=??? hw_id=1
448
set (hw_id)LED:1 127
449
 
450
# is doing the same like:
451
set LED:1 127
452
</PRE></TT>
453
 
454
 
455
<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:
456
<TT><PRE style="margin-left:50px; font-size:8pt">
457
if (id)BUTTON:20 != 0
458
  log "BUTTON:20 is pressed"
459
endif
460
</PRE></TT>
461
 
462
 
1186 tk 463
<H2> <IMG SRC="images/bullet.gif" ALT=""> Operations </H2>
1120 tk 464
 
1186 tk 465
<P CLASS=DESC>Some basic mathematical operations are supported. They have to be surrounded with square-brackets ([...]).</P>
466
 
467
<P CLASS=DESC>Syntax: <I>[&lt;left-operand&gt;&lt;operator&gt;&lt;right-operand&gt;]</I></P>
468
 
469
<P CLASS=DESC>Examples:
470
<UL CLASS=CL>
471
  <LI><I>set LED:2000 [LED:2000 + 1]</I><BR>
472
      will increment the value stored in LED:2000
473
  <LI><I>set LED:2000 [LED:2000 - 1]</I><BR>
474
      will decrement the value stored in LED:2000
475
</UL>
476
</P>
477
 
478
<P CLASS=DESC>Note that nested operations are supported as well, such as:
479
<UL CLASS=CL>
480
  <LI><I>send CC USB1 1 [LED:2000 + [LED:2001 + [LED:2002 + LED:2003]]]</I>
481
</UL>
482
</P>
483
 
484
<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>
485
 
486
<P CLASS=DESC>Support operators:
487
<UL CLASS=CL>
488
  <LI><I>+</I>: addition
489
  <LI><I>-</I>: substraction
490
  <LI><I>*</I>: multiplication
491
  <LI><I>/</I>: divide
492
  <LI><I>%</I>: modulo
493
  <LI><I>&amp;</I>: logical AND
494
  <LI><I>|</I>: logical OR
495
  <LI><I>^</I>: logical XOR
496
</UL>
497
</P>
498
 
499
 
500
 
1119 tk 501
<H2> <IMG SRC="images/bullet.gif" ALT=""> Flow Control </H2>
502
 
503
<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>
504
 
505
<P CLASS=DESC>A condition consists of a left and right value + a condition in the middle:
506
<LI><I>&lt;left expression&gt; &lt;condition &lt;right expression&gt;</I></P>
507
 
508
<P CLASS=DESC>Examples:
509
<TT><PRE style="margin-left:50px; font-size:8pt">
510
if ^section == 1
511
 
512
  log "Section is 1"
513
endif
514
</PRE></TT>
515
 
516
or:
517
 
518
<TT><PRE style="margin-left:50px; font-size:8pt">
519
if ^section == 1
520
  # initial patches for my synths:
521
  send CC OUT1 1 0 0
522
  send ProgramChange OUT1 1 0
523
 
524
  send CC OUT1 2 0 0
525
  send ProgramChange OUT1 2 0
526
 
527
  send CC OUT1 3 0 0
528
  send ProgramChange OUT1 3 0
529
 
530
  send CC OUT2 1 0 0
531
  send ProgramChange OUT2 1 0
532
 
533
  exit
534
endif
535
 
536
 
537
if ^section == 2
538
  # alternative patches for my synths:
539
  send CC OUT1 1 0 0
540
  send ProgramChange OUT1 1 21
541
 
542
  send CC OUT1 2 0 0
543
  send ProgramChange OUT1 2 1
544
 
545
  send CC OUT1 3 0 0
546
  send ProgramChange OUT1 3 75
547
 
548
  send CC OUT2 1 0 0
549
  send ProgramChange OUT2 1 0x10
550
 
551
  exit
552
endif
553
</PRE></TT>
554
 
555
or:
556
 
557
<TT><PRE style="margin-left:50px; font-size:8pt">
558
if ^section == 1
559
  if BUTTON:1 > 0
560
    if BUTTON:2 > 0
561
      log "BUTTON:1 and BUTTON:2 are pressed"
562
    endif
563
  endif
564
endif
565
</PRE></TT>
566
 
567
<P CLASS=DESC>Supported conditions are: <I>==, !=, &lt;, &lt;=, &gt;, &gt;=</I>.<BR>
568
Logical combinations are not supported.</P>
569
 
570
 
1120 tk 571
<H2> <IMG SRC="images/bullet.gif" ALT=""> Loops (resp. restarting)</H2>
572
 
573
<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.
574
 
575
<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.
576
 
577
Usage example:
578
<TT><PRE style="margin-left:50px; font-size:8pt">
579
# don't do anything during startup & patch load
580
if ^section == 0
581
  exit
582
endif
583
 
584
# loop this section as long as BUTTON:2000 is active
585
# Note that this button has been configured for toggle mode!
586
if ^section == 1
587
  log "Section 1 called"
588
 
589
  # do this
590
 
591
  # and that
592
 
593
  # maybe with some delays:
594
  delay_ms 100
595
 
596
  # and finally:
597
  if (id)BUTTON:2000 != 0
598
    LCD "@(1:1:2)loop running "
599
    log "Retriggering section 1"
600
    exec_meta RunSection:1
601
  else
602
    LCD "@(1:1:2)loop finished"
603
    log "Finished."
604
  endif
605
  exit
606
endif
607
</PRE></TT>
608
 
609
<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>.
610
 
611
<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.
612
 
613
 
1119 tk 614
<H2> <IMG SRC="images/bullet.gif" ALT=""> Limitations </H2>
615
 
616
<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:
617
<UL CLASS=CL>
618
  <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!
619
  <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!
620
  <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.
621
</UL>
622
 
623
FOOTER