The Ekdahl FAR - Command language: Difference between revisions

Line 13:

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>

bowmotorrun:1, bowcontrolfrequecy:82.5

</pre>We could also use the ''short names'' for the commands<pre>bmr:1,bcf:82.5</pre>Both ''bowmotorrun'' and ''bowcontrolfrequency'' takes one ''parameter'' each, ''bowmotorrun''s is ''conditional'' and unless the first ''parameter'' is equal to '1' the motor will not start. The first ''parameter'' of ''bowcontrolfrequency'' 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.

</pre>We could also use the ''short names'' for the commands<pre>bmr:1,bcf:82.5</pre>Both ''bowmotorrun'' and ''bowcontrolfrequency'' takes one ''parameter'' each, ''bowmotorrun'' is ''conditional'' and unless the first ''parameter'' is equal to '1' the motor will not start. The first ''parameter'' of ''bowcontrolfrequency'' 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.

To test out a ''command'' you can send it directly to the Ekdahl FAR using the ''Console'' in the ''Configuration utility''.

Line 70:

* deadband(x,y) - Returns ''x + y '' if ''x < y'' or ''x - y'' if ''x > y''. If neither of these statements is true it returns ''0'' - used to create a [[wikipedia:Deadband|deadband]] of ''x'' with the threshold of ''y''

''Functions'' can be readily used in a ''command string''

''Functions'' can be readily used in a ''command string''<pre>

bmr:1,bcf:"8.17579875 * pow(2, (1/12 * note))"

</pre>The previous statements starts the ''bowing wheel'' and sets the frequency of the wheel to ''8.17579875 * 2^(1/12 * note)''. A middle 'C' according to ''MIDI'' has a ''note value'' of 36, meaning if we substitute ''note'' with 36 we get the equation ''8.17579875 * 2^(1/12 * 36)'' which comes out to ''~65.4'' Hertz.

Note that the first ''parameter'' for ''bcf'' 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 require inputs ''x'' and ''y'' and we need to make sure that the Ekdahl FAR doesn't mistake that comma for meaning that a new ''command'' is being sent. 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 parsing the ''command string'' correctly.

== Return messages ==

The Ekdahl FAR when connected via ''USB-Serial'' doesn't only accept ''commands'' but will also send various ''return messages''. These are prefixed by their ''category'' denoted in brackets ("[]"), the existing categories as of this writing (2025-01-22) are:

* command / cmd - Acknowledges the reception of a command in ''plain text''

* usb - Acknowledges the reception of a ''MIDI message'' over ''USB'' in ''plain text''

* hardware / hw - Signals that a change has been sent to the Ekdahl FAR hardware, sent in ''plain text''

* undefined / un - The message sent is in the ''undefined'' category, sent in ''plain text''

* priority / pri - The message sent is in the ''priority'' category, sent in ''plain text''

* error / err - Signals that an ''error'' has occured, sent in ''plain text''

* expressionparser / ep - The message contains debugging information regarding the internal ''expression parser''

*

* inforequest / irq - Signals that an ''info request'' has been returned. This is a very specialized type of message

@@ Line 13: / Line 13: @@
 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>
 bowmotorrun:1, bowcontrolfrequecy:82.5
-</pre>We could also use the ''short names'' for the commands<pre>bmr:1,bcf:82.5</pre>Both ''bowmotorrun'' and ''bowcontrolfrequency'' takes one ''parameter'' each, ''bowmotorrun''s is ''conditional'' and unless the first ''parameter'' is equal to '1' the motor will not start. The first ''parameter'' of ''bowcontrolfrequency'' 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.
+</pre>We could also use the ''short names'' for the commands<pre>bmr:1,bcf:82.5</pre>Both ''bowmotorrun'' and ''bowcontrolfrequency'' takes one ''parameter'' each, ''bowmotorrun'' is ''conditional'' and unless the first ''parameter'' is equal to '1' the motor will not start. The first ''parameter'' of ''bowcontrolfrequency'' 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.
 To test out a ''command'' you can send it directly to the Ekdahl FAR using the ''Console'' in the ''Configuration utility''.
@@ Line 70: / Line 70: @@
 * deadband(x,y) - Returns ''x + y '' if ''x < y'' or ''x - y'' if ''x > y''. If neither of these statements is true it returns ''0'' - used to create a [[wikipedia:Deadband|deadband]] of ''x'' with the threshold of ''y''
-''Functions'' can be readily used in a ''command string''
+''Functions'' can be readily used in a ''command string''<pre>
+bmr:1,bcf:"8.17579875 * pow(2, (1/12 * note))"
+</pre>The previous statements starts the ''bowing wheel'' and sets the frequency of the wheel to ''8.17579875 * 2^(1/12 * note)''. A middle 'C' according to ''MIDI'' has a ''note value'' of 36, meaning if we substitute ''note'' with 36 we get the equation ''8.17579875 * 2^(1/12 * 36)'' which comes out to ''~65.4'' Hertz.
+Note that the first ''parameter'' for ''bcf'' 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 require inputs ''x'' and ''y'' and we need to make sure that the Ekdahl FAR doesn't mistake that comma for meaning that a new ''command'' is being sent. 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 parsing the ''command string'' correctly.
+== Return messages ==
+The Ekdahl FAR when connected via ''USB-Serial'' doesn't only accept ''commands'' but will also send various ''return messages''. These are prefixed by their ''category'' denoted in brackets ("[]"), the existing categories as of this writing (2025-01-22) are:
+* command / cmd - Acknowledges the reception of a command in ''plain text''
+* usb - Acknowledges the reception of a ''MIDI message'' over ''USB'' in ''plain text''
+* hardware / hw - Signals that a change has been sent to the Ekdahl FAR hardware, sent in ''plain text''
+* undefined / un - The message sent is in the ''undefined'' category, sent in ''plain text''
+* priority / pri - The message sent is in the ''priority'' category, sent in ''plain text''
+* error / err - Signals that an ''error'' has occured, sent in ''plain text''
+* expressionparser / ep - The message contains debugging information regarding the internal ''expression parser''
+*
+* inforequest / irq - Signals that an ''info request'' has been returned. This is a very specialized type of message