MIDIbox NG

User Manual --- .NGL Configuration File

This chapter lists the configuration commands of a .NGL file. If this format is new to you, please read the First Steps chapter first to get a basic understanding.

LABEL

The LABEL command specifies global label definitions which can be referenced by using the Caret (^) specifier in label or LCD output definitions of the .NGC file.

A basic usage example can already be found in the DEFAULT.NGL file which has been generated whenever a "virgin" SD Card has been connected to the core module:

# Standard label for buttons:
LABEL std_btn  "Button #%3i %3d%b"

# Standard label for LEDs:
LABEL std_led  "LED #%3i       %b"

# Standard label for rotary encoders:
LABEL std_enc  "ENC #%3i    %3d%B"

# Standard label for pots connected to AIN pins:
LABEL std_ain  "AIN #%3i    %3d%B"

# Standard label for pots connected to AINSER module:
LABEL std_aser "AINSER #%3i %3d%B"

# Standard label for motorfaders:
LABEL std_mf   "MF #%3i     %3d%B"

These standard labels are displayed whenever an EVENT_* in the .NGC file refers to the appr. label, such as: # this command is part of a .NGC file: EVENT_BUTTON id=1 type=NoteOn key=36 lcd_pos=1:1:1 label="^std_btn"

It's allowed that one label follows another in the same string:

# this command is part of a .NGC file:
EVENT_BUTTON id=1  type=NoteOn key=36  lcd_pos=1:1:1 label="^clr^btn^value"

will print the ^clr, the ^btn and the ^value label (which have been defined by yourself).

And for the case, that text follows a label, terminate it with ^#

# this command is part of a .NGC file:
EVENT_BUTTON id=1  type=NoteOn key=36  lcd_pos=1:1:1 label="^clr^#MyText"

will print the ^clr label (which has been defined by yourself), followed by "MyText".

The size of a label is limited to 8 characters to avoid unnecessary compute overhead while searching for matching strings.

COND

CONDitional labels are the most powerful purpose of global label definitions - they allow to output different strings based on the EVENT value!

Following example demonstrates the purpose pretty nicely:

COND_LABEL fil_type
COND =0    "Bypass   "
COND =1    "LP 24dB  "
COND =2    "LP 12dB  "
COND =3    "BP 24dB  "
COND =4    "BP 12dB  "
COND =5    "HP 24dB  "
COND =6    "HP 12dB  "
COND =7    "Notch24dB"
COND =8    "Notch12dB"
COND =9    "Comb+    "
COND =10   "Comb-    "
COND =11   "PPG LP   "
COND_ELSE  "Type %3d "

An EVENT_* command can use it this way:

# this command is part of a .NGC file:
EVENT_ENC id=1  type=CC cc=16  lcd_pos=1:1:1 label="Filter Type: ^fil_type"

So: each value can be named, but it's also possible to define value ranges at which a string should be taken, such as:

COND_LABEL test1
COND =0   "Val is 000   %3d"
COND =1   "Val is 001   %3d"
COND =2   "Val is 002   %3d"
COND =3   "Val is 003   %3d"
COND <20  "Val is <20   %3d"
COND <=40 "Val is <=40  %3d"
COND_ELSE "else cond.   %3d"

Here a list of supported commands:

COND Statement Description

COND_LABEL "<name>" Starts a conditional label. The size of a label name is limited to 8 characters!

COND = or == String will be taken if the EVENT value is equal to the specified constant

COND < String will be taken if the EVENT value is less than the specified constant

COND <= String will be taken if the EVENT value is less or equal the specified constant

COND > String will be taken if the EVENT value is greater than the specified constant

COND >= String will be taken if the EVENT value is greater or equal the specified constant

COND_ELSE This finishes a conditional label and returns a string if the previous statements haven't hit.
It's strongly recommended to use this condition regardless if your definitions cover all possible values or not - it's at least a debugging help: COND_ELSE "I made an error!"

Note that > and >= actually don't make much sense, since the conditions are processed top-down. Once the EVENT value is greater(-equal) the constant, the matching label will be taken, and the remaining conditions won't be processed anymore. These statements are only provided for completeness purposes... ;-) (and sometimes it's useful to express conditions this way)

Format Specifiers

Following format specifiers are available:

%d: will output the value (minus specified offset) in decimal format
%u: same like %d, but value always in unsigned format
%x: will output the value (minus specified offset) in hexadecimal format
%X: same like %x, but with capital letters
%c: will output the value as character
%s: will output an empty string. In conjunction with padding values it could save some memory, e.g. "%20s" will output 20 spaces
%i: the ID of the EVENT
%p: for EVENT_BUTTON_MATRIX only: the pin number of the matrix
%e: the MIDI event of the EVENT (up to 3 hexadecimal values, always 6 characters)
%m: the minimum value of the EVENT which has been specified with range
%M: the maximum value of the EVENT which has been specified with range
%b: a binary digit: * if value >= (range/2), o if value < (range/2)
%B: a vertical bar which works like a meter.
In conjunction with various fonts (selected with &<font>) alternative icons will be output instead.
%q: current selected bank (q is a rotated b - do you see it? ;-)
%C: clear all LCDs
%%: outputs the % character

It's possible to format the output by adding following specifiers after the percent (%) character. In following example the %d (decimal value) is used, but this works with any format type:

%3d: the value will be padded with spaces to 3 characters, and it will be output right-aligned, e.g. " 1", " 10", "100"
%-3d: the value will be padded with spaces to 3 characters, and it will be output left-aligned, e.g. "1 ", "10 ", "100"
%03d: the value will be padded with zeroes to 3 characters, and it will be output right-aligned, e.g. "001", "010", "100"

Technical Background

Actually the RAM memory size of a MBHP_CORE_STM32 or MBHP_CORE_LPC17 core is too low to provide instant access to huge conditional string lists. Therefore the definitions of a .NGL file will be automatically compiled into a .BIN file whenever the .NGL file has been modified. The .BIN file is structured in a way so that MIDIbox NG can quickly access the strings directly from SD Card. By using a clever registration mechanism this mostly allows access within less than 1 mS, which is totally acceptable for a thread which is running in background, and which doesn't delay the MIDI processing.

Therefore you are welcome to use conditional labels as often as you like - they won't affect the performance, and they are a very useful extension to improve the readability of parameter value selections! :-)

Last update: 2024-05-08