Back to main page...

MIDIbox NG

User Manual --- .NGR Script

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.

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 .NGC file 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!

On a MBHP_CORE_STM32F4, 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! :-)
The MBHP_CORE_LPC17 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!).

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).

Usecases

Here a list of intended usecases:

  • set values of control elements (LEDs, Buttons, LED Rings, Encoders, etc...) during startup with optional delays (for having some "blink" ;-).
    E.g. a nice sequence of patterns for LEDs and LED Rings by pushing a button to surprise your friends.
  • send an informative message to the MIOS Studio terminal.
    E.g. to debug your .NGC setup (or the .NGR execution flow).
  • set a control element value depending on conditions, which are derived from other control elements.
    E.g. to implement complex selections (if BUTTON:1 and BUTTON:2 is pressed the same time, do something special...)
  • send a fully customizable MIDI messages, even multiple ones triggered by the same event.
    E.g. to select different patches on synthesizers which are connected to different MIDI ports and listen to different MIDI channels.
  • MBHP_CORE_STM32F4 only (direct execution from RAM): advanced event processing in realtime

If you know other interesting usecases which are not listed here, please let me know! :-)

Calling the .NGR script

The .NGR script can be called with following methods:

  • it's started automatically with ^section == 0 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:
    if ^section == 0
      exit
    endif
    
  • it can be started from a Meta event which is defined in the .NGC file, e.g.:
    # start script with ^section == 1
    EVENT_BUTTON id=1  type=Meta  meta=RunSection:1  button_mode=OnOnly
    
    Some configuration examples can be found under runscr1.ngc (which calls runscr1.ngr) and runscr2.ngc (which calls runscr2.ngr)
  • it can be started from the MIOS Terminal with run <section> <value>
    The ^section variable will contain the value of <section>
    And the ^value variable will contain <value>
    Example:
    run 1 127
    

Commands

Here a list of available commands:
Command Description
LCD <string> Prints an immediate message on screen while it's executed.
All string control formats and directives are supported (see description of EVENT_* label parameter), which especially means that it's possible to clear the screen, and to jump to different cursor positions at different displays.
Examples:
# clear screen
LCD "%C"

# print message on first line of first LCD
LCD "@(1:1:1)Hello World!"

# print message on second line of first LCD
LCD "@(1:1:2)Second Line"

# print message on first line of second LCD
LCD "@(2:1:1)Second Display"
LOG <string> Sends a message to the MIOS Terminal.
Currently formatted messages are not supported, only static string (could change in future). Example:
LOG "Hello World!"
SEND <midi-event> Sends a MIDI event. The event definition typically contains:
  • the MIDI event type (NoteOff, NoteOn, PolyPressure, CC, ProgramChange, Aftertouch, Pitchbend, NRPN, SysEx)
  • the MIDI port (USB1..USB4, OUT1..OUT4, OSC1..OSC4)
  • the MIDI channel (1..16)
  • one or more values depending on the event type
Examples:
#    type   port chn key  value
send NoteOn USB1   1  36  ^value
send NoteOn USB1   1  36  0

#    type         port chn key value
send Polypressure USB1   1  36 ^value

#    type port chn key  value
send CC   USB1   1  16  ^value

#    type          port chn value
send ProgramChange USB1   1 ^value

#    type       port chn value
send Aftertouch USB1   1 ^value

#    type      port chn value
send PitchBend USB1   1 ^value

#    type port chn number value
send NRPN USB1   1 0x0123 ^value

#    type  port stream
send SysEx USB1 0xf0 0x11 0x22 0x33 0x44 ^value 0xf7
EXEC_META <meta-event> [<value>] Executes a meta event with an optional value.
A list of available meta events can be found in the .NGC chapter. Examples:
if ^section == 0
  # wait until all values have been scanned (consider 2 seconds startup delay + a little bit margin)
  delay_ms 2500
  
  # now capture the AINSER values
  exec_meta RetrieveAinserValues

  # and dump out values
  exec_meta DumpSnapshot
endif
or
if ^section == 1
  exec_meta SetSnapshot 1
  exec_meta DumpSnapshot
endif
TRIGGER <id> Triggers a control element with the given <id>, so that it sends out it's MIDI event and prints it's label on LCD.
Example:
# send the MIDI event of the first three pots connected to the AINSER module
trigger AINSER:1
trigger AINSER:2
trigger AINSER:3
SET <id> <value>
SET ^<variable> <value>
Similar to TRIGGER, but it also changes the value of the control element.
Example:
# turn on the first 3 LEDs connected to the DOUT module:
set LED:1 127
set LED:2 127
set LED:3 127
The SET 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.
Examples:
# turn on the first 3 LEDs connected to the DOUT module:
set ^section 1
set ^value 2
set ^bank 3
set ^pat ENC:1
CHANGE <id> <1|0> Similar to SET, but won't trigger a MIDI event.
Example:
set BUTTON:1 42
will change the button value to 42, but the MIDI event which has been specified for this button won't be generated.
SET_RGB <id> <red>:<green><blue> Similar to the rgb 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.
Example:
# it's assumed, that a DOUT_MATRIX is configured for all three layers,
# and that led_emu_id_offset is set to 1001, so that the LEDs are
# individually accessible via LED:1001, LED:1002, ...

# set the RGB levels for multicolour LEDs connected to a DOUT_MATRIX

# Red
set_rgb LED:1001 15:0:0

# Green
set_rgb LED:1002 0:15:0

# Blue
set_rgb LED:1003 0:0:15

# Yellow
set_rgb LED:1004 15:15:0

# Cyan
set_rgb LED:1005 0:15:15

# Magenta
set_rgb LED:1006 15:0:15

# Orange
set_rgb LED:1007 15:8:0

# White
set_rgb LED:1008 15:15:15

# now turn on the LEDs by setting the maximum value
set LED:1001 127
set LED:1002 127
set LED:1003 127
set LED:1004 127
set LED:1005 127
set LED:1006 127
set LED:1007 127
set LED:1008 127
SET_HSV <id> <h>:<s><v> 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)
Example:
# red
set_hsv RGBLED:1 0:100:25

# green
set_hsv RGBLED:2 120:100:25

# blue
set_hsv RGBLED:3 240:100:25
SET_LOCK <id> <1|0> Allows to lock/unlock the MIDI receiver of an EVENT.
Examples: with
      set_lock ENC:1 1
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).
With:
      set_lock ENC:1 0
the encoder will be unlocked, so that it will change the value on a matching incoming MIDI event again (default).
SET_ACTIVE <id> <1|0> 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:
SET_NO_DUMP <id> <1|0> Allows to change the "no_dump" flag which specifies if an EVENT_xxx should be sent during a DumpSnapshot. This feature can be used to handle different snapshot setups.
SET_MIN <id> <1|0>
SET_MAX <id> <1|0>
Sets the minimal/maximal value of an event (in the .NGR file specified with range=<min>:<max>.
Example:
# let the button toggle between 63 and 65
set_min BUTTON:1 63
set_max BUTTON:1 65
DELAY_MS <ms> Delays the execution of the script for the given number of milliseconds.
Example:
set LED:1 127
delay_ms 100
set LED:1 0

set LED:2 127
delay_ms 100
set LED:2 0

set LED:3 127
delay_ms 100
set LED:3 0
LOAD <setup> Switch to another setup (.NGC, .NGS, .NGR, ... files)
IF
ELSIF
ELSE
ENDIF
See special flow control chapter below.
EXIT Stops the execution of the .NGR script. Example:
# don't do anything during startup
if ^section == 0
  exit
endif

Expressions

All values specified with the SET/SEND/IF/etc... command are handled as expressions which can be:

  • a constant decimal value from -16384..16384
  • a constant hexadecimal value from 0x0..0x3fff
  • a constant octal value from 0..037777
  • a control element hw_id, e.g. BUTTON:1, ENC:1, AINSER:1, etc... (see next section about IDs)
  • a control element id, e.g. (id)BUTTON:1, (id)ENC:1, (id)AINSER:1, etc... (see next section about IDs)
  • ^section: this variable can be passed from the Meta event or "run" terminal command. It's 0 when a .NGC file.
  • ^value: the item value when the script is called from a Meta event.
  • ^bank: the current bank

More ^ variables can be implemented on request.

IDs

Whenever a control element is addressed with it's id (e.g. BUTTON:1, LED:1, AINSER:1, ENC:1 (see also .NGC chapter), the parser will search for a matching hardware id (hw_id) by default.

This means for example, that a

set LED:1 127
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 emu_led_id_offset is used in the DOUT_MATRIX configuration).

If no EVENT_LED has been defined in the .NGC file, the hardware will be directly accessed via a virtual event like known from fwd_id.

If multiple EVENT_LED are assigned to the same hw_id, but to different banks, only the EVENT item of the currently selected bank will be accessed.

Sometimes you want to access an element based on it's id independent from the current bank selection. Or the specified id doesn't match with the assigned hw_id. For such cases, it's possible to cast this type with the (id):

# set EVENT_LED id=1 directly without considering the current bank selection
set (id)LED:1 127

For completeness reasons, it's also possible to cast (hw_id), although this type is used by default:

# set EVENT_LED id=??? hw_id=1
set (hw_id)LED:1 127

# is doing the same like:
set LED:1 127

The casting method is also useful if you want to read a value of a control element independent from the bank selection, such as:

if (id)BUTTON:20 != 0
  log "BUTTON:20 is pressed"
endif

Operations

Some basic mathematical operations are supported. They have to be surrounded with square-brackets ([...]).

Syntax: [<left-operand><operator><right-operand>]

Examples:

  • set LED:2000 [LED:2000 + 1]
    will increment the value stored in LED:2000
  • set LED:2000 [LED:2000 - 1]
    will decrement the value stored in LED:2000

Note that nested operations are supported as well, such as:

  • send CC USB1 1 [LED:2000 + [LED:2001 + [LED:2002 + LED:2003]]]

More examples can be found in runscr5.ngc and runscr5.ngr

Support operators:

  • +: addition
  • -: substraction
  • *: multiplication
  • /: divide
  • %: modulo
  • &: logical AND
  • |: logical OR
  • ^: logical XOR

Flow Control

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!

A condition consists of a left and right value + a condition in the middle:

  • <left expression> <condition <right expression>

    Examples:

    if ^section == 1
    
      log "Section is 1"
    endif
    
    or:
    if ^section == 1
      # initial patches for my synths:
      send CC OUT1 1 0 0
      send ProgramChange OUT1 1 0
    
      send CC OUT1 2 0 0
      send ProgramChange OUT1 2 0
    
      send CC OUT1 3 0 0
      send ProgramChange OUT1 3 0
    
      send CC OUT2 1 0 0
      send ProgramChange OUT2 1 0
    
      exit
    endif
    
    
    if ^section == 2
      # alternative patches for my synths:
      send CC OUT1 1 0 0
      send ProgramChange OUT1 1 21
    
      send CC OUT1 2 0 0
      send ProgramChange OUT1 2 1
    
      send CC OUT1 3 0 0
      send ProgramChange OUT1 3 75
    
      send CC OUT2 1 0 0
      send ProgramChange OUT2 1 0x10
    
      exit
    endif
    
    or:
    if ^section == 1
      if BUTTON:1 > 0
        if BUTTON:2 > 0
          log "BUTTON:1 and BUTTON:2 are pressed"
        endif
      endif
    endif
    

    Supported conditions are: ==, !=, <, <=, >, >=.
    Logical combinations are not supported.

    Loops (resp. restarting)

    Loops are not directly supported. There is neither a "goto"/"jump" command, nor a "do" or "while" loop, to keep the parser algorithm simple.

    But with following trick it's possible to restart the .NGR script with the RunSection:<section> meta event. As you can see, this even allows to start the .NGR file with a different ^section value. Usage example:

    # don't do anything during startup & patch load
    if ^section == 0
      exit
    endif
    
    # loop this section as long as BUTTON:2000 is active
    # Note that this button has been configured for toggle mode!
    if ^section == 1
      log "Section 1 called"
    
      # do this
    
      # and that
    
      # maybe with some delays:
      delay_ms 100
    
      # and finally:
      if (id)BUTTON:2000 != 0
        LCD "@(1:1:2)loop running "
        log "Retriggering section 1"
        exec_meta RunSection:1
      else
        LCD "@(1:1:2)loop finished"
        log "Finished."
      endif
      exit
    endif
    

    The files can be found under runscr3.ngc and runscr3.ngr.

    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 RunStop meta event with a dedicated button.

    Limitations

    The capabilities are still limited, mainly caused by RAM size limitations of the MBHP_CORE_LPC17. Following limitations have to be considered:

    • please don't expect a script language which is so powerful like for example eLua! 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!
    • It's currently not possible to declare and set customized variables. Limited capabilities could be available in future, but they will consume some RAM!
    • 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.


    Last update: 2017-04-09

    Copyright 1998-2017, Thorsten Klose. All rights reserved.