The Ekdahl FAR - Command language: Difference between revisions

Since version 1.1 of the Ekdahl FAR Firmware, all commands are grouped in a hierarchical fashion according to their ''modules'' and each ladder in the hierarchy is separated by a period ("."), this works very much like folders or directories in a regular computer. Every ''module'' can contain both ''commands'' and other ''modules''.  

bw.dcm.ru:1, bw.pid.tf:82.5</pre>Both ''bowmotorrun'' / ''bowingwheel.dcmotor.run'' and ''bowcontrolfrequency / bowingwheel.pid.targetfrequency'' takes one ''parameter'' each, ''bowmotorrun / bowingwheel.dcmotor.run'' is ''conditional'' and unless the first ''parameter'' is equal to '1' the motor will not start. The first ''parameter'' of ''bowcontrolfrequency / bowingwheel.pid.targetfrequency'' sets the frequency of the ''bowing wheel'', the instrument may not execute a ''command'' if it decides that the given ''parameters'' are outside of the working range or they are missing.

The addition of the hierarchy in the FAR 1.1 firmware isn't just to be able to group commands, but it's also to make the FAR not limited to a single set of ''modules'' (and is the first stepping stone to a ''modular'' Ekdahl FAR). In fact, you could have 12 different bowing wheel ''modules'' for 12 different strings, these would then be addressed as ''bowingwheel[0].command, bowingwheel[1].command'' etc. Anyone familiar with C programming notices that this is the standard way of ''indexing'' an array; using brackets ("[ ]"). When addressing a module without ''indexing'' as above, the FAR will do one or two things; either use the first object ("[0]") or, if the object is ''selectable'' it will use the previously selected object. To make things smoother a command can be executed on several objects at once by using ranges ("[0-4]") and comma separation ("[0, 3, 5-6]").

''Global variables'' are variables that are always available and will exist in any context. The ''global variables'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

These variables will contain whatever data is relevant to the <u>last midi message sent</u> and will not stay relevant beyond the reception of the last message.

Note that the first ''parameter'' for ''bowcontrolfrequency / bowingwheel.pid.targetfrequency'' is put in between double quotes ("). This is because the ''pow''-function requires the use of a comma (",") in order to separate in between its two required inputs; ''x'' and ''y''. In order for the Ekdahl FAR to know that this comma does not signal the beginning of a new ''command,'' we use quotes. Single (') and double (") quotes can be used and nested in all ''parameters'' and are <u>required</u> in a lot of circumstances, improper nesting or not using quotes can lead to the instrument not understanding the ''command string'' correctly.

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>

</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' / ''bw.pid.tf'' 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. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

Most commands do not require any ''parameters'' when using the ''rqi''-command. The ''adcread'' / ''datareturn''-command is an example of a ''command'' that <u>does</u> require a ''parameter'' when used with ''rqi''. The ''adcread / datareturn-''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>

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 strings'' 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

  The ''commands'' responsible for mapping ''command strings'' to different ''MIDI messages'' are as follows

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

rqi:mcf.mc.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'').