The Ekdahl FAR - Command language: Difference between revisions

Line 2:

The Ekdahl FAR is entirely controlled by ''commands'', these ''commands'' decide everything that the instrument is doing, whether it is playing a melody or changing an internal parameter.

When a MIDI ~~event occurs~~ or a new CV / knob value is read, the ''commands'' associated with it will be internally sent. This can be things like "engage hammer" or "set the fundamental frequency" etc.

When a ''MIDI message'' is received or a new CV / knob value is read, the ''commands'' associated with it will be internally sent. This can be things like "engage hammer" or "set the fundamental frequency" etc.

Some of the available ''commands'' are mainly used for calibrating and setting up the instrument and are usually saved into the instruments memory, these will be executed whenever the instrument is turned on.

Line 9:

== Syntax ==

The ''commands'' are invoked using a ''plain text approach'', most commands have both a ''long name'' and a ''short name'' which are interchangeable. A ''command'' may have one or more ''parameters'' associated with it, these ''parameters'' can be of different types; 16-bit numbers (values 0 - 65535), floating point numbers (values with decimals), booleans (0 for 'false', 1 for 'true') and strings (text). Some commands are ''conditional'', meaning they will only execute if a parameter equates to '1' ('true').

The ''commands'' are invoked using a ''plain text approach'', most commands have both a ''long name'' and a ''short name'' which are interchangeable. A ''command'' may have one or more ''parameters'' associated with it, these ''parameters'' can be of different types; 16-bit numbers (values 0 - 65535 or -32767 - 32767), floating point numbers (values with decimals), booleans (0 for 'false', 1 for 'true') and strings (text). Some commands are ''conditional'', meaning they will only execute if a parameter equates to '1' ('true').

The way ''commands'' are written in order to be executed is ''commandname:parameter1:parameter2:parameter3 [etc]'', several commands be executed in sequence by separating them with a comma (','), a bunch of commands strung together is called a ''command string''. If for instance we would like to start the ''bowing wheel'' and set its frequency to 82.5 Hertz we could send the Ekdahl FAR the following ''command string''<pre>

Line 89:

*help / hlp - Signals that the message is a response to a ''help''-command being sent to the Ekdahl FAR. These messages are structured so that a receiver, like the ''Configuration utility'', can parse information about available ''commands'' in the current ''firmware'' and relay it to a user in a structured way.

* inforequest / irq - Signals that an ''info request'' has been returned. This is a specialized message that is either sent as a response to an ''rqi''-command or as a ''interrupt''-message telling the user or receiving software about different parameters in the Ekdahl FAR. These messages follows the same structure as regular ''command message''s of ''[irq]commandname:parameter1 [etc]'' so that it can be used by a receiving software to keep track of parameter changes

===== Explicitly requesting information =====

By using the special command ''requestinfo / rqi'' one can request the information stored by a certain ''command'' or a state of the Ekdahl FAR. The ''rqi''-command is executed in the convention ''rqi:commandname[:optional parameters]''.

To go back to our example of setting the bowing frequency using the ''bowcontrolfrequency''-command we can ask the Ekdahl FAR what the bowing frequency is set to by writing<pre>

rqi:bowcontrolfrequency

</pre>The return value would be something like<pre>

[irq]bcf:82.5

</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' and has the value ''82.5''. Note that the returned ''command'' sent by an ''rqi''-command always uses the ''short name'' in order to preserve bandwidth.

Most commands do not require any ''parameters'' when using the ''rqi''-command. The ''adcread''-command is an example of a ''command'' that does require a ''parameter'' when used with ''rqi''. The ''adcread'' command returns the last value read by the ''analog-to-digital converter'' in the ''Control box'', because there are 8 different channels the ''parameter'' used is which channel to return the data for, hence executing the ''command''<pre>

rqi:adcr:3

</pre>will return the last data read on ''analog-to-digital convert'' channel 3.

== MIDI and CV mapping of command ==

To change how a certain ''MIDI message'' interacts with the Ekdahl FAR we need to change the ''commands'' or ''parameters'' sent when the message is received. The ''command'' responsible for mapping ''command strimgs'' to different ''MIDI messages'' is ''midieventhandler'' or ''mev'' for short. The first ''parameter'' of ''mev'' is the type of ''MIDI message'' that we want to remap

* ''noteon'' - Note on

* ''noteoff -'' Note off

* ''pat -'' Poly after touch

* ''cat'' - Channel after touch

* ''pb'' - Pitch bend

* ''pc'' - Program change

* ''cc'' - Continuous controller

The second ''parameter'' is the ''command string'' that is to be associated with the ''MIDI Message'' - with the exception of the ''cc''-type, here the second ''parameter'' is the ''controller number'' (0 - 127) and the <u>third</u> ''parameter'' is the ''command string''.

We can of course use the ''rqi''-command to check the current mapping, below we are asking what the current ''command string'' associated with the ''pitch bend'' ''MIDI message'' is<pre>

rqi:mev:pb

</pre>This may return something like<pre>

[irq]bchsh:pitch*4

</pre>The return message tells us that the ''pitch bend MIDI message'' is executing a ''bchsh''-command with the parameter ''pitch*4''. Looking in the ''command reference'' we can see that ''bchsh'' is the ''short name'' of the ''bowcontrolharmonicshift''-command which shifts the frequency of the ''bowing wheel'' from the current frequency, the first (and only) parameter sets how much we want to shift it (depends on the ''bowcontrolharmonicshiftrange command'').

If we look in the list of ''[[The Ekdahl FAR - Command langue#Variables|variables]]'' above we can see that the ''pitch bend MIDI message'' will set the ''pitch variable'' which is indeed used. Now what is the '''*4''<nowiki/>' all about? Well the ''bchsh''-command expects a ''16-bit signed'' value, meaning that a full ''harmonic shift'' downwards is equal to -32767, a full ''harmonic shift'' upwards is 32767 and no ''harmonic shift'' is 0. The ''pitch bend MIDI message'' however is only 14-bits, meaning its range is -8192 to 8192, so in order to be able to use the entire range we have to multiply ''pitch'' by 4.

This whole thing about number of bits can seem confusing but in the end it's all about how fine control you have over things; the more possible values, the more detailed control. In fact, most ''MIDI'' values are only 7-bit (!) meaning a range of 0 - 127. While this may sound like a lot of detail for something like a volume control, it is not even close to enough resolution to for instance set the ''bowing speed''. Imagine that our lowest possible note frequency is 50 Hz, that means that with a 0-127 range we can only go from 50 Hz to 127 + 50 = 177 Hz - and with no decimals! This meager range and the very coarse steps of only 1 Hz would mean the instrument would never be able to sound in tune and wouldn't even have two octaves of range.

@@ Line 2: / Line 2: @@
 The Ekdahl FAR is entirely controlled by ''commands'', these ''commands'' decide everything that the instrument is doing, whether it is playing a melody or changing an internal parameter.
-When a MIDI event occurs or a new CV / knob value is read, the ''commands'' associated with it will be internally sent. This can be things like "engage hammer" or "set the fundamental frequency" etc.
+When a ''MIDI message'' is received or a new CV / knob value is read, the ''commands'' associated with it will be internally sent. This can be things like "engage hammer" or "set the fundamental frequency" etc.
 Some of the available ''commands'' are mainly used for calibrating and setting up the instrument and are usually saved into the instruments memory, these will be executed whenever the instrument is turned on.
@@ Line 9: / Line 9: @@
 == Syntax ==
-The ''commands'' are invoked using a ''plain text approach'', most commands have both a ''long name'' and a ''short name'' which are interchangeable. A ''command'' may have one or more ''parameters'' associated with it, these ''parameters'' can be of different types; 16-bit numbers (values 0 - 65535), floating point numbers (values with decimals), booleans (0 for 'false', 1 for 'true') and strings (text). Some commands are ''conditional'', meaning they will only execute if a parameter equates to '1' ('true').
+The ''commands'' are invoked using a ''plain text approach'', most commands have both a ''long name'' and a ''short name'' which are interchangeable. A ''command'' may have one or more ''parameters'' associated with it, these ''parameters'' can be of different types; 16-bit numbers (values 0 - 65535 or -32767 - 32767), floating point numbers (values with decimals), booleans (0 for 'false', 1 for 'true') and strings (text). Some commands are ''conditional'', meaning they will only execute if a parameter equates to '1' ('true').
 The way ''commands'' are written in order to be executed is ''commandname:parameter1:parameter2:parameter3 [etc]'', several commands be executed in sequence by separating them with a comma (','), a bunch of commands strung together is called a ''command string''. If for instance we would like to start the ''bowing wheel'' and set its frequency to 82.5 Hertz we could send the Ekdahl FAR the following ''command string''<pre>
@@ Line 89: / Line 89: @@
 *help / hlp - Signals that the message is a response to a ''help''-command being sent to the Ekdahl FAR. These messages are structured so that a receiver, like the ''Configuration utility'', can parse information about available ''commands'' in the current ''firmware'' and relay it to a user in a structured way.
 * inforequest / irq - Signals that an ''info request'' has been returned. This is a specialized message that is either sent as a response to an ''rqi''-command or as a ''interrupt''-message telling the user or receiving software about different parameters in the Ekdahl FAR. These messages follows the same structure as regular ''command message''s of ''[irq]commandname:parameter1 [etc]'' so that it can be used by a receiving software to keep track of parameter changes
+===== Explicitly requesting information =====
+By using the special command ''requestinfo / rqi'' one can request the information stored by a certain ''command'' or a state of the Ekdahl FAR. The ''rqi''-command is executed in the convention ''rqi:commandname[:optional parameters]''.
+To go back to our example of setting the bowing frequency using the ''bowcontrolfrequency''-command we can ask the Ekdahl FAR what the bowing frequency is set to by writing<pre>
+rqi:bowcontrolfrequency
+</pre>The return value would be something like<pre>
+[irq]bcf:82.5
+</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' and has the value ''82.5''. Note that the returned ''command'' sent by an ''rqi''-command always uses the ''short name'' in order to preserve bandwidth.
+Most commands do not require any ''parameters'' when using the ''rqi''-command. The ''adcread''-command is an example of a ''command'' that does require a ''parameter'' when used with ''rqi''. The ''adcread'' command returns the last value read by the ''analog-to-digital converter'' in the ''Control box'', because there are 8 different channels the ''parameter'' used is which channel to return the data for, hence executing the ''command''<pre>
+rqi:adcr:3
+</pre>will return the last data read on ''analog-to-digital convert'' channel 3.
+== MIDI and CV mapping of command ==
+To change how a certain ''MIDI message'' interacts with the Ekdahl FAR we need to change the ''commands'' or ''parameters'' sent when the message is received. The ''command'' responsible for mapping ''command strimgs'' to different ''MIDI messages'' is ''midieventhandler'' or ''mev'' for short. The first ''parameter'' of ''mev'' is the type of ''MIDI message'' that we want to remap
+* ''noteon'' - Note on
+* ''noteoff -'' Note off
+* ''pat -'' Poly after touch
+* ''cat'' - Channel after touch
+* ''pb'' - Pitch bend
+* ''pc'' - Program change
+* ''cc'' - Continuous controller
+The second ''parameter'' is the ''command string'' that is to be associated with the ''MIDI Message'' - with the exception of the ''cc''-type, here the second ''parameter'' is the ''controller number'' (0 - 127) and the <u>third</u> ''parameter'' is the ''command string''.
+We can of course use the ''rqi''-command to check the current mapping, below we are asking what the current ''command string'' associated with the ''pitch bend'' ''MIDI message'' is<pre>
+rqi:mev:pb
+</pre>This may return something like<pre>
+[irq]bchsh:pitch*4
+</pre>The return message tells us that the ''pitch bend MIDI message'' is executing a ''bchsh''-command with the parameter ''pitch*4''. Looking in the ''command reference'' we can see that ''bchsh'' is the ''short name'' of the ''bowcontrolharmonicshift''-command which shifts the frequency of the ''bowing wheel'' from the current frequency, the first (and only) parameter sets how much we want to shift it (depends on the ''bowcontrolharmonicshiftrange command'').
+If we look in the list of ''[[The Ekdahl FAR - Command langue#Variables|variables]]'' above we can see that the ''pitch bend MIDI message'' will set the ''pitch variable'' which is indeed used. Now what is the '''*4''<nowiki/>' all about? Well the ''bchsh''-command expects a ''16-bit signed'' value, meaning that a full ''harmonic shift'' downwards is equal to -32767, a full ''harmonic shift'' upwards is 32767 and no ''harmonic shift'' is 0. The ''pitch bend MIDI message'' however is only 14-bits, meaning its range is -8192 to 8192, so in order to be able to use the entire range we have to multiply ''pitch'' by 4.
+This whole thing about number of bits can seem confusing but in the end it's all about how fine control you have over things; the more possible values, the more detailed control. In fact, most ''MIDI'' values are only 7-bit (!) meaning a range of 0 - 127. While this may sound like a lot of detail for something like a volume control, it is not even close to enough resolution to for instance set the ''bowing speed''. Imagine that our lowest possible note frequency is 50 Hz, that means that with a 0-127 range we can only go from 50 Hz to 127 + 50 = 177 Hz - and with no decimals! This meager range and the very coarse steps of only 1 Hz would mean the instrument would never be able to sound in tune and wouldn't even have two octaves of range.