The Ekdahl FAR - Command language: Difference between revisions

(6 intermediate revisions by the same user not shown)

Line 99:

</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>

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 first ''parameter'' sets 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~~ ==

== MIDI mapping ==

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

Line 128:

Now lets look at a more complex example, the default ''Note On MIDI message''. On a stock Ekdahl FAR, executing<pre>

rqi:mev:noteon

</pre>Will return something like<pre>[irq]mev:noteon:'m:0,b:0,bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'</pre>As can be seen, there's a lot of stuff going on here! ~~Let~~'s break down what happens when this ''MIDI message'' is received, i.e. when a ''MIDI'' key is pressed down:

</pre>Will return something like<pre>[irq]mev:noteon:'m:0,b:0,bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'</pre>As can be seen, there's a lot of stuff going on here! First of all, notice that everything after ''mev:noteon:'' is situated in between single quotes (') - this is absolutely crucial for the Ekdahl FAR to know that everything within those last two quotes is part of the last ''parameter'' of the ''mev''-command.

Now let's break down what happens when this ''MIDI message'' is received, i.e. when a ''MIDI'' key is pressed down:

# ''m:0'' - Sets ''module'' to 0

Line 137:

Line 139:

# ''bpe:1'' - Sets the ''bowpressureengage'' to '1' which moves the ''bowing jack'' to the ''engage position''

# ''se:(velocity*512)*(1-notecount)'' - Executes the ''solenoidengage''-command with the value ''(velocity*512)*(1-notecount)''

# ''bcsm:0'' - Sets the ''bowcontrolspeedmode'' to '1' which enables automatic shut down of the ''bowing motor''

The first two ''commands'' are the ''module''- and ''bow-''command. These ''commands'' are is intended for future versions of the Ekdahl FAR that may contain more than one string or more than one bow per string. For now ''0'' is the only valid ''parameter'' value that will be accepted for either ''command''.''<nowiki/>''

Line 145:

Line 148:

The ''bowing jack'' is raised to the ''engage position'', any added ''pressure modifiers'' will also be taken into account - once the ''bowing jack'' has reached its intended position the ''bowing wheel'' should (hopefully) make contact with the string and the Ekdahl FAR will start to produce sounds.

~~Lastly~~ we have the ''solenoidengage''-command ''command'' that engages the ''hammer'' and uses the first and only ''parameter'' as the force used. Like with most ''commands'' the ''se''-command is 16-bit (0 - 65535) but the ''MIDI velocity variable'' is 7-bit (0 - 127), so to get the ''velocity'' variable to cover the entire range it needs to be multiplied with 512.

After this we have the ''solenoidengage''-command ''command'' that engages the ''hammer'' and uses the first and only ''parameter'' as the force used. Like with most ''commands'' the ''se''-command is 16-bit (0 - 65535) but the ''MIDI velocity variable'' is 7-bit (0 - 127), so to get the ''velocity'' variable to cover the entire range it needs to be multiplied with 512.

The ''<nowiki/>'*(1-notecount)'''-part is a way of making sure that we are using ''legato'' mode, i.e. that the ''hammer'' is not triggered if a key is already held down when a new key is pressed. The ''notecount''-variable contains the number of ''MIDI'' notes currently held down.

Let's postulate that the Ekdahl FAR is tuned to a 'C' at 65.4Hz and has its ''base'' set to middle 'C' (''MIDI key'' no 36). We are using the equal-temperament 12-tone scale and the Ekdahl FAR is set to respond to all ''MIDI channels'' (omni). Without having previously held any keys we press the middle 'C' (''note'' value 36) as hard as possible (''velocity'' value ''127'') on ''MIDI channel'' number 1 (''channel'' value of 0). The Ekdahl FAR will get a ''note on MIDI message'' sent to it and from our mapping it will create the following ''command ~~sequence~~''<pre>

Let's postulate that the Ekdahl FAR is tuned to a 'C' at 65.4Hz and has its ''base'' set to middle 'C' (''MIDI key'' no 36). We are using the equal-temperament 12-tone scale and the Ekdahl FAR is set to respond to all ''MIDI channels'' (omni). Without having previously held any keys we press the middle 'C' (''note'' value 36) as hard as possible (''velocity'' value ''127'') on ''MIDI channel'' number 1 (''channel'' value of 0). The Ekdahl FAR will get a ''note on MIDI message'' sent to it and from our mapping it will create the following ''command string''<pre>[irq]mev:noteon:'m:0,b:0,bchb:36,bmr:1,bpid:1,bpe:1,se:(127*512)*(1-0),bcsm:0'</pre>What has happened here is that all ''variables'' have been replaced with the values sent by the ''MIDI message''. Since those ''commands'' that doesn't have any ''variables'' with them will execute just as previously, only those ''commands'' whos ''parameters'' have changed will be explained:

[irq]mev:noteon:'m:0,b:0,bchb:36,bmr:1,bpid:1,bpe:1,se:(127*512)*(1-0),bcsm:0'

</pre>What has happened here is that all ''variables'' have been replaced with the values sent by the ''MIDI message''. Since those ''commands'' that doesn't have any ''variables'' with them will execute just as previously, only those ''commands'' whos ''parameters'' have changed will be explained:

# ''bchb: 36'' - The ''bowcontrolharmonicbase'' gets a value of ''36'' (middle 'C'), because ''harmonic number 0'' is mapped to this key it will set the ''bowing wheel'' frequency to the ''fundamental''; ''65.4'' Hertz

# ''se: (127*512)*(1-0)'' - the value of ''127'' comes from the ''velocity''-variable, 127 * 512 = ~~whic~~

# ''se: (127*512)*(1-0)'' - the value of ''127'' comes from the ''velocity''-variable, ''127 * 512 = 65024'' which is awfully close to a maximum hammer force of 65535. Since no previous notes were held down ''notecount'' is equal to ''0'' and thus ''65024 * 1 = 65024''. The hammer is engaged with near maximum force.

So the result is that we have set the speed of the ''bowing motor'' and we have engaged the ''hammer''.

Now imagine that without releasing this key, we press another 'C' one octave above but at half the velocity. The Ekdahl FAR creates the following ''command string''<pre>

[irq]mev:noteon:'m:0,b:0,bchb:48,bmr:1,bpid:1,bpe:1,se:(63*512)*(1-1),bcsm:0'

</pre>Now we can see that the ''note'' variable is ''48'' because the 'C' one octave up is exactly 12 keys above the first, the ''velocity'' variable has changed to ''63'' since we hit it with a lighter touch - and because we are still holding the first key down ''notecount'' is equal to ''1''. Here's what happens

# ''bchb: 48'' - Due to the ''base'' being set to ''36'' the ''harmonic number'' is set to ''48 - 36 = 12''. Because we are using a 12-tone scale ''harmonic number 12'' is exactly one octave above the ''fundamental'' thus the speed of the ''bowing wheel'' is set to ''65.4 * 2 = 130.8'' Hertz.

# ''se: (63*512)*(1-1)'' - So ''63 * 512 = 32256'' and ''1 - 1 = 0'' thus ''32256 * 0 = 0''. When the ''solenoidengage''-command gets a ''parameter'' of ''0'' it will not engage the ''hammer'' - so the ''hammer'' doesn't strike

So it can be seen that with quite rudimentary math we can accomplish a whole lot of things here. Note also that even though the ''note on MIDI message'' also sets the ''channel''-variable we never use it in this example - plenty of opportunity to make something weird happen depending on the ''MIDI channel''!

== CV Mapping ==

''CV Mapping'' works exactly like the ''MIDI mapping'' with the difference that the command for setting the ''CV mapping'' is different and that all events pertaining to this only change the ''value''-variable. The ''command'' for changing the ''CV mapping'' is ''adccommandmap'' or ''acm'', it take two ''parameters''; ''channel'' and ''command string''. We retrieve the ''command string'' for channel ''0'' which reads the sum of the ''harm. v/oct''-jack and the ''harmonic''-knob by sending a command of<pre>

rqi:acm:0

</pre>The default response will be something like

<pre>[irq]acm:0:'bcha:value/1327.716667-20'</pre>

{{docnav

|[[The Ekdahl FAR - Service|Service]]

|[[The Ekdahl FAR - Command reference|Command reference]]

}}

@@ Line 99: / Line 99: @@
 </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>
+Most commands do not require any ''parameters'' when using the ''rqi''-command. The ''adcread''-command is an example of a ''command'' that <u>does</u> 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 first ''parameter'' sets 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 ==
+== MIDI mapping ==
 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
@@ Line 128: / Line 128: @@
 Now lets look at a more complex example, the <u>default</u> ''Note On MIDI message''. On a stock Ekdahl FAR, executing<pre>
 rqi:mev:noteon
-</pre>Will return something like<pre>[irq]mev:noteon:'m:0,b:0,bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'</pre>As can be seen, there's a lot of stuff going on here! Let's break down what happens when this ''MIDI message'' is received, i.e. when a ''MIDI'' key is pressed down:
+</pre>Will return something like<pre>[irq]mev:noteon:'m:0,b:0,bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'</pre>As can be seen, there's a lot of stuff going on here! First of all, notice that everything after ''mev:noteon:'' is situated in between single quotes (') - this is <u>absolutely crucial</u> for the Ekdahl FAR to know that everything within those last two quotes is part of the last ''parameter'' of the ''mev''-command.
+Now let's break down what happens when this ''MIDI message'' is received, i.e. when a ''MIDI'' key is pressed down:
 # ''m:0'' - Sets ''module'' to 0
@@ Line 137: / Line 139: @@
 # ''bpe:1'' - Sets the ''bowpressureengage'' to '1' which moves the ''bowing jack'' to the ''engage position''
 # ''se:(velocity*512)*(1-notecount)'' - Executes the ''solenoidengage''-command with the value ''(velocity*512)*(1-notecount)''
+# ''bcsm:0'' - Sets the ''bowcontrolspeedmode'' to '1' which enables automatic shut down of the ''bowing motor''
 The first two ''commands'' are the ''module''- and ''bow-''command. These ''commands'' are is intended for future versions of the Ekdahl FAR that may contain more than one string or more than one bow per string. For now ''0'' is the only valid ''parameter'' value that will be accepted for either ''command''.''<nowiki/>''
@@ Line 145: / Line 148: @@
 The ''bowing jack'' is raised to the ''engage position'', any added ''pressure modifiers'' will also be taken into account - once the ''bowing jack'' has reached its intended position the ''bowing wheel'' should (hopefully) make contact with the string and the Ekdahl FAR will start to produce sounds.
-Lastly we have the ''solenoidengage''-command ''command'' that engages the ''hammer'' and uses the first and only ''parameter'' as the force used. Like with most ''commands'' the ''se''-command is 16-bit (0 - 65535) but the ''MIDI velocity variable'' is 7-bit (0 - 127), so to get the ''velocity'' variable to cover the entire range it needs to be multiplied with 512.
+After this we have the ''solenoidengage''-command ''command'' that engages the ''hammer'' and uses the first and only ''parameter'' as the force used. Like with most ''commands'' the ''se''-command is 16-bit (0 - 65535) but the ''MIDI velocity variable'' is 7-bit (0 - 127), so to get the ''velocity'' variable to cover the entire range it needs to be multiplied with 512.
 The ''<nowiki/>'*(1-notecount)'''-part is a way of making sure that we are using ''legato'' mode, i.e. that the ''hammer'' is not triggered if a key is already held down when a new key is pressed. The ''notecount''-variable contains the number of ''MIDI'' notes currently held down.
-Let's postulate that the Ekdahl FAR is tuned to a 'C' at 65.4Hz and has its ''base'' set to middle 'C' (''MIDI key'' no 36). We are using the equal-temperament 12-tone scale and the Ekdahl FAR is set to respond to <u>all</u> ''MIDI channels'' (omni). Without having previously held any keys we press the middle 'C' (''note'' value 36) as hard as possible (''velocity'' value ''127'') on ''MIDI channel'' number 1 (''channel'' value of 0). The Ekdahl FAR will get a ''note on MIDI message'' sent to it and from our mapping it will create the following ''command sequence''<pre>
+Let's postulate that the Ekdahl FAR is tuned to a 'C' at 65.4Hz and has its ''base'' set to middle 'C' (''MIDI key'' no 36). We are using the equal-temperament 12-tone scale and the Ekdahl FAR is set to respond to <u>all</u> ''MIDI channels'' (omni). Without having previously held any keys we press the middle 'C' (''note'' value 36) as hard as possible (''velocity'' value ''127'') on ''MIDI channel'' number 1 (''channel'' value of 0). The Ekdahl FAR will get a ''note on MIDI message'' sent to it and from our mapping it will create the following ''command string''<pre>[irq]mev:noteon:'m:0,b:0,bchb:36,bmr:1,bpid:1,bpe:1,se:(127*512)*(1-0),bcsm:0'</pre>What has happened here is that all ''variables'' have been replaced with the values sent by the ''MIDI message''. Since those ''commands'' that doesn't have any ''variables'' with them will execute just as previously, only those ''commands'' whos ''parameters'' have changed will be explained:
-[irq]mev:noteon:'m:0,b:0,bchb:36,bmr:1,bpid:1,bpe:1,se:(127*512)*(1-0),bcsm:0'
-</pre>What has happened here is that all ''variables'' have been replaced with the values sent by the ''MIDI message''. Since those ''commands'' that doesn't have any ''variables'' with them will execute just as previously, only those ''commands'' whos ''parameters'' have changed will be explained:
 # ''bchb: 36'' - The ''bowcontrolharmonicbase'' gets a value of ''36'' (middle 'C'), because ''harmonic number 0'' is mapped to this key it will set the ''bowing wheel'' frequency to the ''fundamental''; ''65.4'' Hertz
-# ''se: (127*512)*(1-0)'' - the value of ''127'' comes from the ''velocity''-variable, 127 * 512 = whic
+# ''se: (127*512)*(1-0)'' - the value of ''127'' comes from the ''velocity''-variable, ''127 * 512 = 65024'' which is awfully close to a maximum hammer force of 65535. Since no previous notes were held down ''notecount''  is equal to ''0'' and thus ''65024 * 1 = 65024''. The hammer is engaged with near maximum force.
+So the result is that we have set the speed of the ''bowing motor'' and we have engaged the ''hammer''.
+Now imagine that without releasing this key, we press another 'C' one octave above but at half the velocity. The Ekdahl FAR creates the following ''command string''<pre>
+[irq]mev:noteon:'m:0,b:0,bchb:48,bmr:1,bpid:1,bpe:1,se:(63*512)*(1-1),bcsm:0'
+</pre>Now we can see that the ''note'' variable is ''48'' because the 'C' one octave up is exactly 12 keys above the first, the ''velocity'' variable has changed to ''63'' since we hit it with a lighter touch - and because we are <u>still holding the first key down</u> ''notecount'' is equal to ''1''. Here's what happens
+# ''bchb: 48'' - Due to the ''base'' being set to ''36'' the ''harmonic number'' is set to ''48 - 36 = 12''. Because we are using a 12-tone scale ''harmonic number 12'' is exactly one octave above the ''fundamental'' thus the speed of the ''bowing wheel'' is set to ''65.4 * 2 = 130.8'' Hertz.
+# ''se: (63*512)*(1-1)'' - So ''63 * 512 = 32256'' and ''1 - 1 = 0'' thus ''32256 * 0 = 0''. When the ''solenoidengage''-command gets a ''parameter'' of ''0'' it will not engage the ''hammer'' - so the ''hammer'' doesn't strike
+So it can be seen that with quite rudimentary math we can accomplish a whole lot of things here. Note also that even though the ''note on MIDI message'' also sets the ''channel''-variable we never use it in this example - plenty of opportunity to make something weird happen depending on the ''MIDI channel''!
+== CV Mapping ==
+''CV Mapping'' works exactly like the ''MIDI mapping'' with the difference that the command for setting the ''CV mapping'' is different and that <u>all</u> events pertaining to this <u>only</u> change the ''value''-variable. The ''command'' for changing the ''CV mapping'' is ''adccommandmap'' or ''acm'', it take two ''parameters''; ''channel'' and ''command string''. We retrieve the ''command string'' for channel ''0'' which reads the sum of the ''harm. v/oct''-jack and the ''harmonic''-knob by sending a command of<pre>
+rqi:acm:0
+</pre>The <u>default</u> response will be something like
+<pre>[irq]acm:0:'bcha:value/1327.716667-20'</pre>
+{{docnav
+|[[The Ekdahl FAR - Service|Service]]
+|[[The Ekdahl FAR - Command reference|Command reference]]
+}}