KNAS Wiki - User contributions [en]

The Ekdahl FAR - Service

2025-09-01T01:18:30Z

Knaadmin:

== General service & maintenance ==
The Ekdahl FAR requires periodic maintenance just like any acoustic instrument. One key difference from traditional instruments is that the [[The Ekdahl FAR - Calibrations|firmware can to some degree compensate]] for changes and variability in the hardware, meaning one can sometimes simply change a few software parameters instead of having to physically change things on the instrument.

=== Periodic maintenance ===
Things like [[The Ekdahl FAR - Bowing wheels|changing the bowing wheel]] and [[The Ekdahl FAR - Changing the string|changing strings]] are very commonplace and aren't really considered maintenance. However, changing either of these may necessitate things like [[The Ekdahl FAR - Changing the string#Bridge heights|changing bridge heights]], lowering or raising the [[The Ekdahl FAR - Mute#Adjusting the mute|mutes]] or [[The Ekdahl FAR - Bowing jack#Adjusting the bowing jack|bowing jack]] and changing the [[The Ekdahl FAR - Pickup|pickup height]].

=== Less frequent maintenance and repairs ===
The [https://github.com/Knaster/EkdahlFar firmware] inside the Ekdahl FAR is periodically updated, new versions may include bug fixes or added features therefore it may be recommended to update the firmware at certain times. New features in the instrument may necessitate an updated version of the [[The Ekdahl FAR - Configuration utility - Concept and Installation|Configuration Utility]] in order to take advantage of them.

Because the Ekdahl FAR is electro-mechanical, things will eventually break or get worn out. An effort has been made to find a middle ground in between durability, component availability, and cost. Standard parts have been used as much as possible inside the instrument. All 3D printed parts can be downloaded and printed using a regular SLA printer. Most hardware can easily be bought online and any specialty components can be gotten from Knas.

=== Updating the firmware ===

The easiest way to update the firmware is by installing [https://koromix.dev/tytools TyTools] and upload a [https://github.com/Knaster/EkdahlFar/tree/master/bin/Release binary] of the firmware using Teensy Commander.

Install TyTools as indicated on their website and [https://downgit.github.io/#/home?url=https://github.com/Knaster/EkdahlFar/refs/heads/master/bin/Release/EkdahlFarCB.hex download the latest binary .hex file] and unzip it at your desired location. After installing, start TyCommander, with the Ekdahl FAR plugged into one of the USB ports on your computer you should get a screen similar to this:
[[File:TyCommander main.png|center|thumb|905x905px]]
With the Ekdahl FAR selected, press "upload" and direct the dialog to where you unzipped the .hex-file. Wait a few moments for the upload to complete, the instrument will restart and then you are good to go!

{{docnav
|[[The Ekdahl FAR - Configuration utility - Software tab|The Software tab]]
|[[The Ekdahl FAR - Command language|Command language]]
}}

== Notes ==
<references/>

The Ekdahl FAR - Service

2025-08-31T23:27:32Z

Knaadmin:

== General service & maintenance ==
The Ekdahl FAR requires periodic maintenance just like any acoustic instrument. One key difference from traditional instruments is that the [[The Ekdahl FAR - Calibrations|firmware can to some degree compensate]] for changes and variability in the hardware, meaning one can sometimes simply change a few software parameters instead of having to physically change things on the instrument.

=== Periodic maintenance ===
Things like [[The Ekdahl FAR - Bowing wheels|changing the bowing wheel]] and [[The Ekdahl FAR - Changing the string|changing strings]] are very commonplace and aren't really considered maintenance. However, changing either of these may necessitate things like [[The Ekdahl FAR - Changing the string#Bridge heights|changing bridge heights]], lowering or raising the [[The Ekdahl FAR - Mute#Adjusting the mute|mutes]] or [[The Ekdahl FAR - Bowing jack#Adjusting the bowing jack|bowing jack]] and changing the [[The Ekdahl FAR - Pickup|pickup height]].

=== Less frequent maintenance and repairs ===
The [https://github.com/Knaster/EkdahlFar firmware] inside the Ekdahl FAR is periodically updated, new versions may include bug fixes or added features therefore it may be recommended to update the firmware at certain times. New features in the instrument may necessitate an updated version of the [[The Ekdahl FAR - Configuration utility - Concept and Installation|Configuration Utility]] in order to take advantage of them.

Because the Ekdahl FAR is electro-mechanical, things will eventually break or get worn out. An effort has been made to find a middle ground in between durability, component availability, and cost. Standard parts have been used as much as possible inside the instrument. All 3D printed parts can be downloaded and printed using a regular SLA printer. Most hardware can easily be bought online and any specialty components can be gotten from Knas.

=== Updating the firmware ===

The easiest way to update the firmware is by installing [https://koromix.dev/tytools TyTools] and upload a [https://github.com/Knaster/EkdahlFar/tree/master/bin/Release binary] of the firmware using Teensy Commander.

Install TyTools as indicated on their website and [https://downgit.github.io/#/home?url=https://github.com/Knaster/EkdahlFar/refs/heads/master/bin/Release/EkdahlFarCB.hex download the latest binary .hex file] and unzip it at your desired location. After installing, start TyCommander, with the Ekdahl FAR plugged into one of the USB ports on your computer you should get a screen similar to this:
[[File:TyCommander main.png|center|thumb|905x905px]]
With the Ekdahl FAR selected, press "upload" and direct the dialog to where you unzipped the .hex-file. Wait a few moments for the upload to complete, the instrument will restart and then you are good to go!

{{docnav
|[[The Ekdahl FAR - Configuration utility - Software tab|- The Software tab]]
|[[The Ekdahl FAR - Command language|Command language]]
}}

== Notes ==
<references/>

MediaWiki:Sidebar

2025-08-31T23:22:35Z

Knaadmin:

* navigation
** https://www.knasmusic.com|Knas website
** https://www.knasmusic.com/forum|Forum
* The Ekdahl FAR
** The Ekdahl FAR|- Introduction
** The_Ekdahl_FAR_-_Getting_started|- Getting started
** The Ekdahl FAR - The Control box|- The Control box
** The Ekdahl FAR - Basic MIDI Setup|- Basic MIDI Setup
** The Ekdahl FAR - Tuning|- Tuning
** The Ekdahl FAR - Limits|- Limits
** The Ekdahl FAR - Calibrations|- Calibrations
** The Ekdahl FAR - Changing the string|- Changing the string
** The Ekdahl FAR - Bowing wheels|- Bowing wheels
** The Ekdahl FAR - Bowing jack|- The bowing jack
** The Ekdahl FAR - Mute|- The mute
** The Ekdahl FAR - Hammer|- The hammer
** The Ekdahl FAR - Pickup|- The pickup
** The Ekdahl FAR - Configuration utility - Concept and Installation|Configuration utility
** The Ekdahl FAR - Configuration utility - Overview|- Overview
** The Ekdahl FAR - Configuration utility - Tuning tab|- The Tuning tab
** The Ekdahl FAR - Configuration utility - Midi tab|- The MIDI tab
** The Ekdahl FAR - Configuration utility - CV tab|- The CV tab
** The Ekdahl FAR - Configuration utility - Advanced tab|- The Advanced tab
** The Ekdahl FAR - Configuration utility - Statistics tab|- The Statistics tab
** The Ekdahl FAR - Configuration utility - Software tab|- The Software tab
** The Ekdahl FAR - Service|Service & Maintenance
** The Ekdahl FAR - Command langue|Command language
** The Ekdahl FAR - Command reference|Command reference
** The Ekdahl FAR - Specifications|Specifications
* SEARCH
* TOOLBOX
* LANGUAGES

MediaWiki:Sidebar

2025-08-31T23:22:12Z

Knaadmin:

* navigation
** https://www.knasmusic.com|Knas website
** https://www.knasmusic.com/forum|Forum
* The Ekdahl FAR
** The Ekdahl FAR|- Introduction
** The_Ekdahl_FAR_-_Getting_started|- Getting started
** The Ekdahl FAR - The Control box|- The Control box
** The Ekdahl FAR - Basic MIDI Setup|- Basic MIDI Setup
** The Ekdahl FAR - Tuning|- Tuning
** The Ekdahl FAR - Limits|- Limits
** The Ekdahl FAR - Calibrations|- Calibrations
** The Ekdahl FAR - Changing the string|- Changing the string
** The Ekdahl FAR - Bowing wheels|- Bowing wheels
** The Ekdahl FAR - Bowing jack|- The bowing jack
** The Ekdahl FAR - Mute|- The mute
** The Ekdahl FAR - Hammer|- The hammer
** The Ekdahl FAR - Pickup|- The pickup
** The Ekdahl FAR - Configuration utility - Concept and Installation|Configuration utility
** The Ekdahl FAR - Configuration utility - Overview|- Overview
** The Ekdahl FAR - Configuration utility - Tuning tab|- The Tuning tab
** The Ekdahl FAR - Configuration utility - Midi tab|- The MIDI tab
** The Ekdahl FAR - Configuration utility - CV tab|- The CV tab
** The Ekdahl FAR - Configuration utility - Advanced tab|- The Advanced tab
** The Ekdahl FAR - Configuration utility - Statistics tab|- The Statistics tab
** The Ekdahl FAR - Configuration utility - Software tab|- The Software tab
** The Ekdahl FAR - Service|Service
** The Ekdahl FAR - Command langue|Command language
** The Ekdahl FAR - Command reference|Command reference
** The Ekdahl FAR - Specifications|Specifications
* SEARCH
* TOOLBOX
* LANGUAGES

The Ekdahl FAR

2025-08-31T23:17:51Z

Knaadmin:

[[File:Ekdahl FAR - Overview.jpg|thumb|Ekdahl FAR Overview]]

== Introduction ==
The Ekdahl FAR is a string based electro-acoustic instrument whose main way of generating sound is by utilizing a [[The Ekdahl FAR - Getting started#bowing wheel|bowing wheel]] that rubs against the string and by very precisely controlling the speed of the wheel, emphasizing natural overtones in the string. The [[The Ekdahl FAR - Getting started#bowing wheel|bowing wheel]] is situated on a pivot which pushes the wheel into the string with a controllable [[The Ekdahl FAR - Getting started#pressure|pressure]] in order to affect both volume and harmonic content. To further extend the capabilities of the instrument it also has a [[The Ekdahl FAR - Hammer|hammer]], a variable [[The Ekdahl FAR - Mute|mute]] and a electromagnetic [[The Ekdahl FAR - Pickup|pickup]]. While the audio path on The Ekdahl FAR is entirely analog-acoustic, the internals of the instrument is a highly sophisticated network of sensors, motors and a built-in computer running a complex firmware allowing for precision control and interfacing via USB-MIDI, MIDI, CV and USB-Serial.

Like all Knas instruments, the Ekdahl FAR - while a new and somewhat experimental concept - can be used for any regular musical composition and expression, but also allows for deep explorations of naturally occurring overtones within the realms of digital precision control and repeatability. The instrument is designed to perform excellently whether being in an improvisational setting, or being sequenced. All aspects of The Ekdahl FAR can be mapped to respond to any available ''control mechanisms'' (USB, MIDI, CV etc.) and emphasis has been put on configurability and modification both from a software and a hardware perspective.
 
The hardware
<hr/>

[[The Ekdahl FAR - Getting started|Getting started]]

[[The Ekdahl FAR - The Control box|The Control box]]

[[The Ekdahl FAR - Basic MIDI Setup|Basic MIDI Setup]]

[[The Ekdahl FAR - Tuning|Tuning]]

[[The Ekdahl FAR - Limits|Limits]]

[[The Ekdahl FAR - Calibrations|Automatic calibrations]]

[[The Ekdahl FAR - Changing the string|Changing the string]]

[[The Ekdahl FAR - Bowing wheels|Bowing wheels and changing them]]

[[The Ekdahl FAR - Bowing jack|The bowing jack]]

[[The Ekdahl FAR - Mute|The mute]]

[[The Ekdahl FAR - Hammer|The hammer]]

[[The Ekdahl FAR - Pickup|The pickup]]

The Configuration utility
<hr/>
[[The Ekdahl FAR - Configuration utility - Concept and Installation|Concept and Installation]]

[[The Ekdahl FAR - Configuration utility - Overview|Overview]]

[[The Ekdahl FAR - Configuration utility - Tuning tab|The ''Tuning'' tab]]

[[The Ekdahl FAR - Configuration utility - Midi tab|The ''MIDI'' tab]]

[[The Ekdahl FAR - Configuration utility - CV tab|The ''CV'' tab]]

[[The Ekdahl FAR - Configuration utility - Advanced tab|The ''Advanced'' tab]]

[[The Ekdahl FAR - Configuration utility - Statistics tab|The ''Statistics'' tab]]

[[The Ekdahl FAR - Configuration utility - Software tab|The ''Software'' tab]]

Appendix
<hr/>
[[The Ekdahl FAR - Service|Service]]

[[The Ekdahl FAR - Command langue|Command language]]

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

[[The Ekdahl FAR - Specifications|Specifications]]

{{Docnav
|
|[[The Ekdahl FAR - Getting started|Getting started]]
}}

The Ekdahl FAR - Command language

2025-08-31T23:17:06Z

Knaadmin:

== Command language ==
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 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.

All ''commands'' can be manually invoked via ''USB-Serial'', in conjunction with certain software this presents an unprecedented level of control and sequenceability.

== 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 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>
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'' 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''.

To read up on existing ''commands'', their ''parameters'' and a brief description you can check the ''Command reference'' in the ''Configuration utility''.

== Variables, functions and equations ==
What makes the ''Command language'' truly powerful is the concept of ''variables, functions'' and ''equations''. All ''parameters'' that take numerical values can use any combination of ''variables, functions'' or ''equations.''

For instance, we can use the previous example and instead write our ''command string'' as follows<pre>
bowmotorrun:1,bowcontrolfrequency:82.5+note*20
</pre>This example requires of course that the ''variable'' ''note'' exists in the current context.

===== Variables =====
There are two types of ''variables'' in the Ekdahl FAR; ''global variables'' and ''event variables''.

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

* notecount - Contains the number of ''MIDI'' keys that are being held down, i.e. all ''Note on messages'' received that haven't gotten a paired ''Note off message'' yet
* uv0 - uv9 - These are ''user variables'' and can be set at any point using the ''globaluservariable command'' with the first ''parameter'' being which variable to set (0-9) and the second ''parameter'' being the value (float).
* e - Contains the constant ''[[wikipedia:E_(mathematical_constant)|e]]''
* pi - Contains the constant ''[[wikipedia:Pi|pi]]''

''Event variables'' are variables that are set by certain ''MIDI messages'' or when a new value is read on one of the jacks or knobs on the ''Control box''. The ''Event variables'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

* channel - Set by the ''Note on, Note off, Continuous Controller, Poly after touch, Pitch bend, Channel after touch'' and ''Program change MIDI messages''
* note - Set by the ''Note on, Note off'' and ''Poly after touch MIDI messages''
* velocity - Set by the ''Note on'' and ''Note off MIDI messages''
* pressure - Set by the ''Poly after touch'' and ''Channel after touch MIDI messages''
* value - Set by the ''Continuous Controller MIDI message'' and by the ''Control box''
* pitch - Set by the ''Pitch bend MIDI message''
* program - Set by the ''Program change MIDI message''

===== Functions =====
''Functions'' can be used to change a numerical value or the result of an ''equation'', the Ekdahl FAR contains both general ''arithmetic functions'' (courtesy of Lewis Van Winkle and the TINYEXPR engine) and ''specialized functions''.

The ''arithmetic functions'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

* abs(x) - Returns the ''[[wikipedia:Absolute_value|absolute value]]'' of ''x''
* acos(x), asin(x), atan(x), atan2(x, y) - Returns the [[wikipedia:Inverse_trigonometric_functions|''arc-cos, -sin, -tan'' and ''-tan2'']] of ''x''
* atan2(x,y) - Returns the ''[[wikipedia:Atan2|arctan2]]'' of ''x, y''
* floor(x), ceil(x) - Returns the [[wikipedia:Floor_and_ceiling_functions|''floor'' and ''ceiling'']] of ''x''
* exp(x) - Returns the ''[[wikipedia:Exponential_function|exponent]]'' of ''x''
* fac(x) - Returns the ''[[wikipedia:Factorial|factorial]]'' of x
* ln(x) - Returns the ''[[wikipedia:Natural_logarithm|natural logarithm]]'' of ''x''
* log10(x), log20(x) - Returns the ''[[wikipedia:Logarithm|logarithm]]'' of ''x'' using base 10 and 20 respectively
* ncr(x,y), npr(x,y) - Functions to calculate ''[[wikipedia:Combination|combinations]]'' and ''[[wikipedia:Permutation|permutations]]''
* pow(x,y) - Returns ''x^y''
* sqrt(x) - Returns the ''[[wikipedia:Square_root|square root]]'' of ''x''
* cos(x), sin(x), tan(x) - Returns the [[wikipedia:Trigonometric_functions|''cos, sin'' and ''tan'']] of ''x''
* cosh(x), sinh(x), tanh(x) - Returns the ''[[wikipedia:Hyperbolic_functions|hyperbolic cos, sin and tan]]'' of ''x''
The ''specialized functions'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

* bool(x) - Returns 1 if ''x'' is more than 0
* ibool(x) - Returns 0 if ''x'' is more than 0
* 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''<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 required 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 occurred, sent in ''plain text''
* expressionparser / ep - These messages contains debugging information regarding the internal ''expression parser'' and is used for development
*debug / dbg - These messages contains various debugging information and is used for development
*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 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 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

* ''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 third ''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. The idea of limiting the Ekdahl FAR to what is possible through ''MIDI'' seemed like a poor choice thus it was decided that most parameters will instead be 16-bit.

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! 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
# ''b:0'' - Sets ''bow'' to 0
# ''bchb:note'' - Invokes the ''bowcontrolharmonicbase-''command with the first ''parameter'' set to the ''variable note''.
# ''bmr:1'' - Sets the ''bowmotorrun''-command to '1', starting the ''bow motor''
# ''bpid:1'' - Sets the ''bowpid''-command to '1', making sure the ''PID'' is used
# ''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/>''

The ''bowcontrolharmonicbase''-command sets the speed of the ''bowing wheel'' to its corresponding ''harmonic number'' but also takes into account its ''<nowiki/>'base''' which is the ''MIDI key'' that is mapped to ''harmonic number 0''.

After this the bowing motor is started and the ''PID'' is turned, now the instrument will try and make sure that the ''bowing wheel'' is at the right speed.

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.

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

# ''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 = 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]]
}}

The Ekdahl FAR - Command language

2025-08-31T23:16:47Z

Knaadmin:

== Command language ==
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 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.

All ''commands'' can be manually invoked via ''USB-Serial'', in conjunction with certain software this presents an unprecedented level of control and sequenceability.

== 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 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>
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'' 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''.

To read up on existing ''commands'', their ''parameters'' and a brief description you can check the ''Command reference'' in the ''Configuration utility''.

== Variables, functions and equations ==
What makes the ''Command language'' truly powerful is the concept of ''variables, functions'' and ''equations''. All ''parameters'' that take numerical values can use any combination of ''variables, functions'' or ''equations.''

For instance, we can use the previous example and instead write our ''command string'' as follows<pre>
bowmotorrun:1,bowcontrolfrequency:82.5+note*20
</pre>This example requires of course that the ''variable'' ''note'' exists in the current context.

===== Variables =====
There are two types of ''variables'' in the Ekdahl FAR; ''global variables'' and ''event variables''.

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

* notecount - Contains the number of ''MIDI'' keys that are being held down, i.e. all ''Note on messages'' received that haven't gotten a paired ''Note off message'' yet
* uv0 - uv9 - These are ''user variables'' and can be set at any point using the ''globaluservariable command'' with the first ''parameter'' being which variable to set (0-9) and the second ''parameter'' being the value (float).
* e - Contains the constant ''[[wikipedia:E_(mathematical_constant)|e]]''
* pi - Contains the constant ''[[wikipedia:Pi|pi]]''

''Event variables'' are variables that are set by certain ''MIDI messages'' or when a new value is read on one of the jacks or knobs on the ''Control box''. The ''Event variables'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

* channel - Set by the ''Note on, Note off, Continuous Controller, Poly after touch, Pitch bend, Channel after touch'' and ''Program change MIDI messages''
* note - Set by the ''Note on, Note off'' and ''Poly after touch MIDI messages''
* velocity - Set by the ''Note on'' and ''Note off MIDI messages''
* pressure - Set by the ''Poly after touch'' and ''Channel after touch MIDI messages''
* value - Set by the ''Continuous Controller MIDI message'' and by the ''Control box''
* pitch - Set by the ''Pitch bend MIDI message''
* program - Set by the ''Program change MIDI message''

===== Functions =====
''Functions'' can be used to change a numerical value or the result of an ''equation'', the Ekdahl FAR contains both general ''arithmetic functions'' (courtesy of Lewis Van Winkle and the TINYEXPR engine) and ''specialized functions''.

The ''arithmetic functions'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

* abs(x) - Returns the ''[[wikipedia:Absolute_value|absolute value]]'' of ''x''
* acos(x), asin(x), atan(x), atan2(x, y) - Returns the [[wikipedia:Inverse_trigonometric_functions|''arc-cos, -sin, -tan'' and ''-tan2'']] of ''x''
* atan2(x,y) - Returns the ''[[wikipedia:Atan2|arctan2]]'' of ''x, y''
* floor(x), ceil(x) - Returns the [[wikipedia:Floor_and_ceiling_functions|''floor'' and ''ceiling'']] of ''x''
* exp(x) - Returns the ''[[wikipedia:Exponential_function|exponent]]'' of ''x''
* fac(x) - Returns the ''[[wikipedia:Factorial|factorial]]'' of x
* ln(x) - Returns the ''[[wikipedia:Natural_logarithm|natural logarithm]]'' of ''x''
* log10(x), log20(x) - Returns the ''[[wikipedia:Logarithm|logarithm]]'' of ''x'' using base 10 and 20 respectively
* ncr(x,y), npr(x,y) - Functions to calculate ''[[wikipedia:Combination|combinations]]'' and ''[[wikipedia:Permutation|permutations]]''
* pow(x,y) - Returns ''x^y''
* sqrt(x) - Returns the ''[[wikipedia:Square_root|square root]]'' of ''x''
* cos(x), sin(x), tan(x) - Returns the [[wikipedia:Trigonometric_functions|''cos, sin'' and ''tan'']] of ''x''
* cosh(x), sinh(x), tanh(x) - Returns the ''[[wikipedia:Hyperbolic_functions|hyperbolic cos, sin and tan]]'' of ''x''
The ''specialized functions'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

* bool(x) - Returns 1 if ''x'' is more than 0
* ibool(x) - Returns 0 if ''x'' is more than 0
* 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''<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 required 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 occurred, sent in ''plain text''
* expressionparser / ep - These messages contains debugging information regarding the internal ''expression parser'' and is used for development
*debug / dbg - These messages contains various debugging information and is used for development
*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 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 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

* ''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 third ''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. The idea of limiting the Ekdahl FAR to what is possible through ''MIDI'' seemed like a poor choice thus it was decided that most parameters will instead be 16-bit.

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! 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
# ''b:0'' - Sets ''bow'' to 0
# ''bchb:note'' - Invokes the ''bowcontrolharmonicbase-''command with the first ''parameter'' set to the ''variable note''.
# ''bmr:1'' - Sets the ''bowmotorrun''-command to '1', starting the ''bow motor''
# ''bpid:1'' - Sets the ''bowpid''-command to '1', making sure the ''PID'' is used
# ''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/>''

The ''bowcontrolharmonicbase''-command sets the speed of the ''bowing wheel'' to its corresponding ''harmonic number'' but also takes into account its ''<nowiki/>'base''' which is the ''MIDI key'' that is mapped to ''harmonic number 0''.

After this the bowing motor is started and the ''PID'' is turned, now the instrument will try and make sure that the ''bowing wheel'' is at the right speed.

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.

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

# ''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 = 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 - Configuration utility - Service|Service]]
|[[The Ekdahl FAR - Command reference|Command reference]]
}}

The Ekdahl FAR - Configuration utility - Software tab

2025-08-31T23:16:08Z

Knaadmin:

[[File:Configuration utility software tab.png|Configuration utility - Software tab|thumb]]
The ''software''-tab contains things that are not related to the Ekdahl FAR, but rather to the ''Configuration utility'' itself; how it presents information etc.

== Tuning scheme ==
The ''Tuning scheme'' sets how notes are displayed in the ''Configuration utility'' using different presets.

{{docnav
|[[The Ekdahl FAR - Configuration utility - Statistics tab|The ''Statistics'' tab]]
|[[The Ekdahl FAR - Service|Service]]
}}

The Ekdahl FAR - Command langue

2025-08-31T23:15:05Z

Knaadmin: Knaadmin moved page The Ekdahl FAR - Command langue to The Ekdahl FAR - Command language: Misspelled title

#REDIRECT [[The Ekdahl FAR - Command language]]

The Ekdahl FAR - Command language

2025-08-31T23:15:04Z

Knaadmin: Knaadmin moved page The Ekdahl FAR - Command langue to The Ekdahl FAR - Command language: Misspelled title

== Command language ==
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 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.

All ''commands'' can be manually invoked via ''USB-Serial'', in conjunction with certain software this presents an unprecedented level of control and sequenceability.

== 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 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>
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'' 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''.

To read up on existing ''commands'', their ''parameters'' and a brief description you can check the ''Command reference'' in the ''Configuration utility''.

== Variables, functions and equations ==
What makes the ''Command language'' truly powerful is the concept of ''variables, functions'' and ''equations''. All ''parameters'' that take numerical values can use any combination of ''variables, functions'' or ''equations.''

For instance, we can use the previous example and instead write our ''command string'' as follows<pre>
bowmotorrun:1,bowcontrolfrequency:82.5+note*20
</pre>This example requires of course that the ''variable'' ''note'' exists in the current context.

===== Variables =====
There are two types of ''variables'' in the Ekdahl FAR; ''global variables'' and ''event variables''.

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

* notecount - Contains the number of ''MIDI'' keys that are being held down, i.e. all ''Note on messages'' received that haven't gotten a paired ''Note off message'' yet
* uv0 - uv9 - These are ''user variables'' and can be set at any point using the ''globaluservariable command'' with the first ''parameter'' being which variable to set (0-9) and the second ''parameter'' being the value (float).
* e - Contains the constant ''[[wikipedia:E_(mathematical_constant)|e]]''
* pi - Contains the constant ''[[wikipedia:Pi|pi]]''

''Event variables'' are variables that are set by certain ''MIDI messages'' or when a new value is read on one of the jacks or knobs on the ''Control box''. The ''Event variables'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

* channel - Set by the ''Note on, Note off, Continuous Controller, Poly after touch, Pitch bend, Channel after touch'' and ''Program change MIDI messages''
* note - Set by the ''Note on, Note off'' and ''Poly after touch MIDI messages''
* velocity - Set by the ''Note on'' and ''Note off MIDI messages''
* pressure - Set by the ''Poly after touch'' and ''Channel after touch MIDI messages''
* value - Set by the ''Continuous Controller MIDI message'' and by the ''Control box''
* pitch - Set by the ''Pitch bend MIDI message''
* program - Set by the ''Program change MIDI message''

===== Functions =====
''Functions'' can be used to change a numerical value or the result of an ''equation'', the Ekdahl FAR contains both general ''arithmetic functions'' (courtesy of Lewis Van Winkle and the TINYEXPR engine) and ''specialized functions''.

The ''arithmetic functions'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

* abs(x) - Returns the ''[[wikipedia:Absolute_value|absolute value]]'' of ''x''
* acos(x), asin(x), atan(x), atan2(x, y) - Returns the [[wikipedia:Inverse_trigonometric_functions|''arc-cos, -sin, -tan'' and ''-tan2'']] of ''x''
* atan2(x,y) - Returns the ''[[wikipedia:Atan2|arctan2]]'' of ''x, y''
* floor(x), ceil(x) - Returns the [[wikipedia:Floor_and_ceiling_functions|''floor'' and ''ceiling'']] of ''x''
* exp(x) - Returns the ''[[wikipedia:Exponential_function|exponent]]'' of ''x''
* fac(x) - Returns the ''[[wikipedia:Factorial|factorial]]'' of x
* ln(x) - Returns the ''[[wikipedia:Natural_logarithm|natural logarithm]]'' of ''x''
* log10(x), log20(x) - Returns the ''[[wikipedia:Logarithm|logarithm]]'' of ''x'' using base 10 and 20 respectively
* ncr(x,y), npr(x,y) - Functions to calculate ''[[wikipedia:Combination|combinations]]'' and ''[[wikipedia:Permutation|permutations]]''
* pow(x,y) - Returns ''x^y''
* sqrt(x) - Returns the ''[[wikipedia:Square_root|square root]]'' of ''x''
* cos(x), sin(x), tan(x) - Returns the [[wikipedia:Trigonometric_functions|''cos, sin'' and ''tan'']] of ''x''
* cosh(x), sinh(x), tanh(x) - Returns the ''[[wikipedia:Hyperbolic_functions|hyperbolic cos, sin and tan]]'' of ''x''
The ''specialized functions'' that are incorporated in the ''firmware'' as of this writing (2025-01-21) are:

* bool(x) - Returns 1 if ''x'' is more than 0
* ibool(x) - Returns 0 if ''x'' is more than 0
* 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''<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 required 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 occurred, sent in ''plain text''
* expressionparser / ep - These messages contains debugging information regarding the internal ''expression parser'' and is used for development
*debug / dbg - These messages contains various debugging information and is used for development
*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 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 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

* ''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 third ''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. The idea of limiting the Ekdahl FAR to what is possible through ''MIDI'' seemed like a poor choice thus it was decided that most parameters will instead be 16-bit.

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! 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
# ''b:0'' - Sets ''bow'' to 0
# ''bchb:note'' - Invokes the ''bowcontrolharmonicbase-''command with the first ''parameter'' set to the ''variable note''.
# ''bmr:1'' - Sets the ''bowmotorrun''-command to '1', starting the ''bow motor''
# ''bpid:1'' - Sets the ''bowpid''-command to '1', making sure the ''PID'' is used
# ''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/>''

The ''bowcontrolharmonicbase''-command sets the speed of the ''bowing wheel'' to its corresponding ''harmonic number'' but also takes into account its ''<nowiki/>'base''' which is the ''MIDI key'' that is mapped to ''harmonic number 0''.

After this the bowing motor is started and the ''PID'' is turned, now the instrument will try and make sure that the ''bowing wheel'' is at the right speed.

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.

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

# ''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 = 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 - Configuration utility - Software tab|The ''Software'' tab]]
|[[The Ekdahl FAR - Command reference|Command reference]]
}}

The Ekdahl FAR - Service

2025-08-31T23:13:52Z

Knaadmin:

== General service & maintenance ==
The Ekdahl FAR requires periodic maintenance just like any acoustic instrument. One key difference from traditional instruments is that the [[The Ekdahl FAR - Calibrations|firmware can to some degree compensate]] for changes and variability in the hardware, meaning one can sometimes simply change a few software parameters instead of having to physically change things on the instrument.

=== Periodic maintenance ===
Things like [[The Ekdahl FAR - Bowing wheels|changing the bowing wheel]] and [[The Ekdahl FAR - Changing the string|changing strings]] are very commonplace and aren't really considered maintenance. However, changing either of these may necessitate things like changing bridge heights, lowering or raising the mutes or bowing jack and changing the pickup height.

=== Less frequent maintenance and repairs ===
The [https://github.com/Knaster/EkdahlFar firmware] inside the Ekdahl FAR is periodically updated, new versions may include bug fixes or added features therefore it may be recommended to update the firmware at certain times. New features in the instrument may necessitate an updated version of the [[The Ekdahl FAR - Configuration utility - Concept and Installation|Configuration Utility]] in order to take advantage of them.

Because the Ekdahl FAR is electro-mechanical, things will eventually break or get worn out. An effort has been made to find a middle ground in between durability, component availability, and cost. Standard parts have been used as much as possible inside the instrument. All 3D printed parts can be downloaded and printed using a regular SLA printer. Most hardware can easily be bought online and any specialty components can be gotten from Knas.

=== Updating the firmware ===

The easiest way to update the firmware is by installing [https://koromix.dev/tytools TyTools] and upload a [https://github.com/Knaster/EkdahlFar/tree/master/bin/Release binary] of the firmware using Teensy Commander.

Install TyTools as indicated on their website and [https://downgit.github.io/#/home?url=https://github.com/Knaster/EkdahlFar/refs/heads/master/bin/Release/EkdahlFarCB.hex download the latest binary .hex file] and unzip it at your desired location. After installing, start TyCommander, with the Ekdahl FAR plugged into one of the USB ports on your computer you should get a screen similar to this:
[[File:TyCommander main.png|center|thumb|905x905px]]
With the Ekdahl FAR selected, press "upload" and direct the dialog to where you unzipped the .hex-file. Wait a few moments for the upload to complete, the instrument will restart and then you are good to go!

{{docnav
|[[The Ekdahl FAR - Configuration utility - Software tab|- The Software tab]]
|[[The Ekdahl FAR - Command language|Command language]]
}}

== Notes ==
<references/>

The Ekdahl FAR - Service

2025-08-31T16:10:45Z

Knaadmin:

== General service & maintenance ==
The Ekdahl FAR requires periodic maintenance just like any acoustic instrument. One key difference from traditional instruments is that the [[The Ekdahl FAR - Calibrations|firmware can to some degree compensate]] for changes and variability in the hardware, meaning one can sometimes simply change a few software parameters instead of having to physically change things on the instrument.

=== Periodic maintenance ===
Things like [[The Ekdahl FAR - Bowing wheels|changing the bowing wheel]] and [[The Ekdahl FAR - Changing the string|changing strings]] are very commonplace and aren't really considered maintenance. However, changing either of these may necessitate things like changing bridge heights, lowering or raising the mutes or bowing jack and changing the pickup height.

=== Less frequent maintenance and repairs ===
The [https://github.com/Knaster/EkdahlFar firmware] inside the Ekdahl FAR is periodically updated, new versions may include bug fixes or added features therefore it may be recommended to update the firmware at certain times. New features in the instrument may necessitate an updated version of the [[The Ekdahl FAR - Configuration utility - Concept and Installation|Configuration Utility]] in order to take advantage of them.

Because the Ekdahl FAR is electro-mechanical, things will eventually break or get worn out. An effort has been made to find a middle ground in between durability, component availability, and cost. Standard parts have been used as much as possible inside the instrument. All 3D printed parts can be downloaded and printed using a regular SLA printer. Most hardware can easily be bought online and any specialty components can be gotten from Knas.

=== Updating the firmware ===

The easiest way to update the firmware is by installing [https://koromix.dev/tytools TyTools] and upload a [https://github.com/Knaster/EkdahlFar/tree/master/bin/Release binary] of the firmware using Teensy Commander.

Install TyTools as indicated on their website and [https://downgit.github.io/#/home?url=https://github.com/Knaster/EkdahlFar/refs/heads/master/bin/Release/EkdahlFarCB.hex download the latest binary .hex file] and unzip it at your desired location. After installing, start TyCommander, with the Ekdahl FAR plugged into one of the USB ports on your computer you should get a screen similar to this:
[[File:TyCommander main.png|center|thumb|905x905px]]
With the Ekdahl FAR selected, press "upload" and direct the dialog to where you unzipped the .hex-file. Wait a few moments for the upload to complete, the instrument will restart and then you are good to go!

{{docnav
|[[The Ekdahl FAR - Command reference|Command reference]]
|
}}

== Notes ==
<references/>

File:TyCommander main.png

2025-08-31T16:07:04Z

Knaadmin:

TyCommander main screen

The Ekdahl FAR - Service

2025-08-31T15:38:17Z

Knaadmin:

== General service & maintenance ==
The Ekdahl FAR requires periodic maintenance just like any acoustic instrument. One key difference from traditional instruments is that the [[The Ekdahl FAR - Calibrations|firmware can to some degree compensate]] for changes and variability in the hardware, meaning one can sometimes simply change a few software parameters instead of having to physically change things on the instrument.

=== Periodic maintenance ===
Things like [[The Ekdahl FAR - Bowing wheels|changing the bowing wheel]] and [[The Ekdahl FAR - Changing the string|changing strings]] are very commonplace and aren't really considered maintenance. However, changing either of these may necessitate things like changing bridge heights, lowering or raising the mutes or bowing jack and changing the pickup height.

=== Less frequent maintenance and repairs ===
The [https://github.com/Knaster/EkdahlFar firmware] inside the Ekdahl FAR is periodically updated, new versions may include bug fixes or added features therefore it may be recommended to update the firmware at certain times. New features in the instrument may necessitate an updated version of the [[The Ekdahl FAR - Configuration utility - Concept and Installation|Configuration Utility]] in order to take advantage of them.

Because the Ekdahl FAR is electro-mechanical, things will eventually break or get worn out. An effort has been made to find a middle ground in between durability, component availability, and cost. Standard parts have been used as much as possible inside the instrument. All 3D printed parts can be downloaded and printed using a regular SLA printer. Most hardware can easily be bought online and any specialty components can be gotten from Knas.

=== Updating the firmware ===

The easiest way to update the firmware is by installing [https://koromix.dev/tytools TyTools] and upload a [https://github.com/Knaster/EkdahlFar/tree/master/bin/Release binary] of the firmware using Teensy Commander.

Install TyTools as indicated on their website and [https://downgit.github.io/#/home?url=https://github.com/Knaster/EkdahlFar/refs/heads/master/bin/Release/EkdahlFarCB.hex download the latest binary .hex file]. After installing, start TyCommander, with the Ekdahl FAR plugged into one of the USB ports on your computer you should get a screen similar to this:

{{docnav
|[[The Ekdahl FAR - Command reference|Command reference]]
|
}}

== Notes ==
<references/>

The Ekdahl FAR - Service

2025-06-23T17:29:11Z

Knaadmin:

The Ekdahl FAR - Service

2025-06-23T17:15:22Z

Knaadmin:

The Ekdahl FAR - Service

2025-06-23T15:16:22Z

Knaadmin: Created page with "== General service & maintenance == The Ekdahl FAR requires periodic maintenance just like any acoustic instrument. One key difference from traditional instruments is that the firmware can to some degree compensate for changes and variability in the hardware, meaning one can sometimes simply change a few software parameters instead of having to physically open up the instrument. === Periodic maintenance === Things like changing the bowing wheel and changing strings are..."

The Ekdahl FAR - Configuration utility - Concept and Installation

2025-06-10T22:27:36Z

Knaadmin:

== The concept of the Configuration Utility ==
[[File:The Configuration utility.png|thumb|The Configuration utility]]
The ''configuration utility'' is a software that will connect to the Ekdahl FAR and reconfigure its internal parameters. It's important to realize that the ''configuration utility'' itself does not have any features that aren't already built in to the Ekdahl FAR, but rather it is just an interface for easily controlling its built-in parameters and commands. The reason that this needs to be pointed out is because everything that can be done with the ''configuration utility'' can be done either by manually sending the Ekdahl FAR various commands or invoking them through MIDI or CV mapping. For instance, in order to change the fundamental tuning of the Ekdahl FAR you don't '''have''' to use the ''configuration utility'', but you could map a slider on a MIDI Controller to send the appropriate commands. This means that a custom interface for the Ekdahl FAR, whether hardware or software, can be made and configured very quickly and easily. When settings are saved in the ''configuration utility'', these are saved into the instrument itself, thus the next time the Ekdahl FAR is powered on the same settings will be recalled whether it is connected to a computer or not.

== Software design choices ==
The ''configuration utility'' is not considered a primary part of the Ekdahl FAR since it isn't strictly needed, but being able to easily change parameters in the instrument is clearly beneficial. The software is ''open source'' and has been written with portability in mind, having a single software that can run on multiple different systems (Linux, MacOS, Windows etc.) is key both in terms of user access and due to the fact that Knas has no possibility of maintaining several different software variations for different systems. Since even maintaining a single software can be challenging for a single individual, and because capitalism is the greatest of evils, the choice was made to make the software ''open source'' so anyone with the skills required can help make it better. For these reasons the software is written in Python using QT as the graphical interface, this means that any system wanting to run the software has to be able to install these frameworks of the appropriate versions.

== Installation ==
The ''configuration utility'' is currently considered to be in beta development stage (2025-01-20) and will be so until Knas has gotten enough satisfiable user feedback. For this reason no binary releases of the software has yet to be made and the user will have to invoke the install scripts appropriate for their system manually.

The first step in the installation process is to download the software from its GitHub page 
https://github.com/Knaster/EkdahlFarConfig

On the page there's a green button with the caption "code", pressing this will reveal a drop-down menu with the option "Download ZIP" at the bottom. Download and extract the .ZIP file into any directory.

== Dependencies ==

All systems will need to have Python v3.10 or later and Qt6 / PySide6 installed, some of the below scripts will try to attempt to find out if these are installed and may launch an installer if not. It is recommended that these be installed before attempting to install the ''Configuration utility'' however.

https://www.python.org/

https://www.qt.io/download-qt-installer-oss

Furthermore the following python packages are required
<pre>
pyside6, pyserial, mido, sympy, pyqt6-charts
</pre>

== Installing on Linux ==
Open a Terminal in the folder where you extracted the .zip file to and install Python

<syntaxhighlight lang="bash">
sudo apt update
apt install python
</syntaxhighlight>
Make sure that apt is installing Python version 3.10 or later.

It is suggested that the dependencies are installed in a specific python environment
<syntaxhighlight lang="bash">
python3 -m venv ./venv
./venv/bin/pip3 install pyside6 pyserial mido sympy pyqt6-charts
</syntaxhighlight>
To run
<syntaxhighlight lang="bash">
./run_linux.sh
</syntaxhighlight>

== Installing on Windows ==
{{mbox|text=Windows 11 will by default block the running of the setup file, in order to unblock it left-click on 'setup_win.bat' in the directory where the files have been extracted, then right-click on it and choose 'properties'. On the bottom right check the 'unblock' box and press OK. }}

Right-click on 'setup_win.bat' and choose 'run as administrator' and click 'yes'.

If Python is not installed, this will launch the Python installer and exit and you have to run it again

The batch script will first install all python depencies and then it will copy the program files to
'C:\Program Files\Ekdahl FAR Configuration Utility' and create an icon in the start menu.

== Installing on MacOS ==

{{mbox|text=As of this writing (2025-01-20) the software has only been successfully installed on MacOS Ventura (13) and Sequoia (15)}} 
{{mbox|text=MacOS 12 requires XCode to be installed, the latest version that works on MacOS 12 is XCode 14.2 which can be downloaded from https://archive.org/details/xcode-14.2. By downloading this, extracting it and dragging it into the Applications folder, the Configuration utility has been successfully installed. If the installer still complains you may have to start a terminal, go to the folder where the Configuration utility has been downloaded and run
<syntaxhighlight lang="bash"> sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
./setup_mac.command</syntaxhighlight>
}}

 
{{mbox|text=MacOS Sequoia (15) will give you the warning "'setup_mac.command' was not opened" and some crap about malware. This is due to apples forever gatekeeping against independent and not-for-profit software development. To circumvent this, if you have tried to run the file once you can go to the apple menu at the top left and choose "system settings", here scroll down to "privacy & security" and it will say "'setup_mac.command' was blocked to protect your mac' - press "Open Anyway" to continue the installation }}
 
run 'setup_mac.command' from finder

The script will install Handbrake (if not present) which in turn will install Python 3.10 or later and the required python dependencies.
It will also copy the program files to '/Applications/Ekdahl FAR Configuration Utility' and create a launcher icon

{{docnav
|[[The Ekdahl FAR - Hammer|The hammer]]
|[[The Ekdahl FAR - Configuration utility - Overview|Configuration utility - Overview]]
}}

The Ekdahl FAR - Command reference

2025-02-03T21:11:20Z

Knaadmin:

== Introduction ==
The ''commands'' in the Ekdahl FAR are using a certain ''naming convention'' to make it more clear which parts of the instrument a certain ''command'' is dealing with. Furthermore commands can be global or local, global commands change settings that will affect the entire instrument, local commands change settings depending on previously set commands. The idea of local commands is a future-proofing of the Ekdahl FAR firmware and can generally be ignored for the time being. The first part of many ''command''-names are a prefix that denotes category, the ''global'' categories as of this writing (2025-01-26) are:

* ''global*'' - commands that have a global reach
* ''midi*'' - commands that deal with ''MIDI''
* ''adc*'' - commands that deal with the ''Control box'' and its ''analog-to-digital converter''
* ''expressionparser'' - commands that deal with how ''commands'' are interpreted and parsed, mainly used for debugging
* ''test''* - commands made for testing and debugging

The ''global'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|requestinfo
|rqi
|[command]:[optional parameters]
|Uses a ''command''-name to retrieve rather than set information associated with it, some commands have no information associated and will return nothing. Some commands require the use of optional ''parameters'' to specify which information that is to be retrieved.
|-
|module
|m
|[module number (0)]
|Sets the current ''module''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''string module.'' Currently '0' is the only valid ''parameter''
|-
|modulecount
|mc
|none
|Returns the number of ''modules'' in the Ekdahl FAR. Currently always returns '1'
|-
|debugprint
|dp
|<nowiki>[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]</nowiki>
|Used to turn on or off whether the instrument will return certain information over ''USB-Serial''. The first ''parameter'' is the category, the second ''parameter'' is a boolean value.
|-
|version
|ver
|none
|Returns the current ''firmware'' version
|-
|globalsaveallparameters
|gsap
|none
|Saves all current data into the internal flash memory
|-
|globalloadallparameters
|glap
|none
|Loads all data saved into flash, effectively overwriting any changed parameters included in the last save
|-
|globalresetparameters
|grap
|none
|Resets all saved data in the flash memory, requires a immediate reset to be enacted
|-
|globaluservariable
|guv
|[variable number (0-9)]:[value (float)]
|Sets or returns the user variable defined in the first ''parameter,'' if used to set the variable, the second ''parameter'' is the value.
|-
|expressionparserevaluate
|epev
|[expression]
|Evaluates the given ''expression'' and returns the calculated value. Used for debugging
|-
|testadclatency
|tal
|[value (0 - 65535)]
|Debugging command to test ADC latency
|-
|testadclatencyreturn
|talr
|none
|Stops ADC latency testing started with ''tal''
|-
|testadcminmac
|tamm
|[channel]
|Debugging command to test the min/max value for a given ''channel''
|}

MIDI commands

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|midiconfiguration
|mcf
|[config (0-9)]
|Sets or returns the ''current MIDI configuration''
|-
|midiconfigurationadd
|mcfa
|none
|Adds a new ''MIDI configuration''
|-
|midiconfigurationremove
|mcfr
|[config (0-9)]
|Removes the ''MIDI configuration'' denoted by the ''parameter'' passed. If there are ''MIDI configurations'' with a higher number, these are moved down the list. The ''current configuration'' may be changed during the execution of this ''command''
|-
|midiconfigurationcount
|mcfc
|none
|Returns the number of ''MIDI configurations'' available
|-
|midiconfigurationname
|mcfn
|<nowiki>[config|name]</nowiki>
|When used as a 'set'-command, the first ''parameter'' sets the name of the ''current MIDI configuration''. When used to retrieve information, the first ''parameter'' sets which ''MIDI configuration'' to return the name for
|-
|midieventhandler
|mev
|<nowiki>[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]</nowiki>
|Used to set the ''command string'' executed when a certain ''MIDI event'' occurs. The first ''parameter'' is the type of ''MIDI event.'' With exception for the ''<nowiki/>'cc' MIDI event'' the second ''parameter'' is the ''command string''. For ''<nowiki/>'cc''' the second ''parameter'' is the ''controller number'' and the third ''parameter'' is the ''command string''
|-
|midiconfigurationdefaults
|mcfd
|none
|Reverts all settings of the ''current MIDI configuration'' to default values and remove any added ''continuous controllers''
|-
|midireceivechannel
|mrc
|[channel (0-16)]
|Sets which ''MIDI channel'' the instrument will respond to. 1-16 sets the ''MIDI channel'' while all other values sets the instrument to ''<nowiki/>'Omni''' (the instrument responding to all channels)
|-
|midiallnotesoff
|mano
|<nowiki>[conditional (0|1)]</nowiki>
|Clears the entire ''MIDI'' buffer of notes held and turns off any bowing
|}

ADC / Control box commands

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|adccommandmap
|acm
|[channel]:[command string]
|Sets the ''command string'' associated with the ''analog-to-digital converter channel'' of the ''Control box''
|-
|adcdefaults
|acd
|none
|Sets all ''command strings'' associated with all ''analog-to-digital converter channels'' to their default values
|-
|adcread
|adcr
|[channel]:[return only: value]
|Returns the last value read by the ''analog-to-digital converter'' of the ''Command box'' on the ''channel'' given. This value is sent automatically any time a change in data is read
|-
|adcsettings
|adcs
|[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]
|Sets the settings for the ''averager'' used for the given ''Control box analog-to-digital channel''. ''Averages'' denote number of values read and averaged, ''interrupterrorthreshold'' sets the value change required for the ''Control box'' to report a new value. The ''continuouserrorthreshold'' and ''continuoustimeout'' are used to allow for ''continuous'' changes. See the ''firmware'' for more information
|}

MIDI commands

The ''local'' commands as of this writing (2025-01-26) are:

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bow
|bow
|[bow (0)]
|Sets the ''current bow.'' This command is intended for future versions of the Ekdahl FAR that may have more than one ''bow'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|bowstatus
|bs
|none
|Outputs debugging data. Deprecated
|-
|pickupstringfrequency
|psf
|none
|Returns the fundamental frequency calculated from the current audio signal if, applicable
|-
|pickupaudiopeak
|pap
|none
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
|none
|Returns the [[wikipedia:Root_mean_square|RMS]] amplitude of the current audio signal
|-
|bowdebugmeasuretimetotarget
|bdmtt
|[frequency]
|Measure the time it takes to change from the current frequency to the target frequency, used to debug the ''PID''
|-
|bowhome
|bh
|none
|Homing bow, used at startup and in case of the bow loosing position
|-
|bowcalibrateall
|bca
|none
|Performs all calibration routines for a single bow available in the given firmware
|-
|bowcalibratespeed
|bcf
|none
|Performs a ''bowing speed calibration''
|-
|bowcalibratepressure
|bcp
|none
|Performs a ''pressure calibration''
|-
|nooperation
|nop
|none
|Do absolutely, positively, nothing
|}

Commands setting parameters relating to the bow PID

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bowpid
|bpid
|<nowiki>[conditional (0|1)]</nowiki>
|Sets whether the [[wikipedia:Proportional–integral–derivative_controller|Proprtional-Integral-Deriviate controller]] is on or off. For all normal operation, the ''PID'' should be turned on. If it is turned off the instrument will not be able to play specific frequencies, but will only respond to ''bowmotordirectpwm''-commands
|-
|bowpidki
|bpki
|[float]
|Sets the ''ki''-value of the ''PID''
|-
|bowpidkp
|bpkp
|[float]
|Sets the ''kp-''value of the ''PID''
|-
|bowpidkd
|bpkd
|[float]
|Sets the ''kd''-value of the ''PID''
|-
|bowpidintegratorerror
|bpie
|[float]
|Sets the minimum ''error value'' required in between the ''set point'' and the ''process variable'' for the integrator part of the ''PID'' to initiate correction
|-
|bowpidmaxerror
|bpme
|[float]
|Sets the maximum error correction attempted in each call to the ''PID loop''
|-
|bowpidr
|bpir
|none
|Resets all data stored by the ''PID''
|-
|bowpidpeakerror
|bpperr
|none
|Returns the last ''error value'' measured in between the ''set point'' and the ''process variable''
|}

Commands relating to bow frequency control

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bowcontrolfrequecy
|bcf
|[float]
|Sets the frequency (in Hertz) that the ''bowing motor'' should attempt to run at
|-
|bowcontrolfundamental
|bcu
|[float]
|Sets the ''fundamental frequency'' that all ''harmonics'' are using as its base for calculations
|-
|bowcontrolharmonic
|bch
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed''. See ''bowcontrolharmonicadd'' and ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicadd
|bcha
|[float]
|Sets the number of ''harmonic numbers'' to add or remove to the value given in ''bowcontrolharmonic'' and ''bowcontrolharmonicbase''. Can be negative values
|-
|bowcontrolharmonicbase
|bchb
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed'' but uses the value set by ''bowcontrolharmonicbasenote'' as its base. Includes any value set by ''bowcontrolharmonicadd'' and overwrites any value set by ''bowcontrolharmonic''
|-
|bowcontrolharmonicbasenote
|bchbn
|[midi key (0-127)]
|Sets the ''MIDI'' key to use as the base for ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicshift
|bchsh
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. The ''harmonic shift'' is dependent on the range set by ''bowcontrolharmonicshiftrange''. Also see ''bowcontrolharmonicshift5''
|-
|bowcontrolharmonicshiftrange
|bchsr
|[harmonics (0-36)]
|Sets the range of the ''bowcontrolharmonicshift''-command. The ''parameter'' given denotes how many ''harmonic numbers'' to shift from the current ''harmonic number'' when the maximum ''harmonic shift'' has been set.
|-
|bowcontrolharmonicshift5
|bchs5
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. Unlike ''bowcontrolharmonicshift'' this value is always calculated on a range of 5 octaves, meaning a maximum ''harmonic shift'' will equal 5 times the amount of ''harmonic ratios'' in the current ''harmonic table''. This value is added to the ''harmonic shift'' set by ''bowcontrolharmonicshift''
|-
|bowcontrolspeedmode
|bcsm
|<nowiki>[mode (0|1)]</nowiki>
|Sets the ''speed mode'' where ''0 = Automatic'' and ''1 = Manual''. The only difference in between these two modes is that ''Automatic'' will automatically turn off the motor when the bow has been set in its ''rest position'' and no frequency changing ''commands'' have been sent within the time period given by ''bowmotortimeout''
|}

Commands for controlling harmonic series

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bowharmonicseries
|bhs
|[series]
|Sets the ''current harmonic series''
|-
|bowharmonicseriesdata
|bhsl
|[(set only) series]:[name]:[ratios]
|Sets all ''ratios'' and the ''name'' of the ''harmonic list'' in the given ''series''. There can be any number of ''ratio''-parameters and this effectively sets the number of ''harmonics'' per octave. If required, empty ''harmonic lists'' will be added until ''slot'' is a valid number. On return, requires [series] and returns ''name'' and ''ratios'' of the ''harmonic series'' given
|-
|bowharmonicseriesratio
|bhsr
|[harmonic]:[ratio]
|Sets the ''ratio'' of the given ''harmonic number'' in the ''current harmonic series''. Will increase the number of ratios in the series if needed
|-
|bowharmonicseriesratioremove
|bhsrr
|[ratio]
|Removes the ''ratio'' given, will move all ''ratios'' with a higher ''harmonic number'' in the series. Cannot remove all ''ratios''
|-
|bowharmonicseriescount
|bhsc
|none
|Returns the number of ''harmonic series'' and their ''names'' in the format ''ratios:name1:name2 [etc]''
|-
|bowharmonicseriessave
|bhss
|[series]:[name]
|Saves the current ''harmonic series'' into the slot given by the second ''parameter'' with the name give in the first ''parameter''. Note that this ''command'' does not save it into flash memory
|-
|bowharmonicseriesremove
|bhsrm
|[series]
|Removes the ''harmonic series'' given in the ''parameter''. Shifts all ''series''' with a higher ''series'' number
|}

Commands relating to the bowing motor

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bowmotorrun
|bmr
|<nowiki>[(0|1)]</nowiki>
|Sets the ''bow motor'' to off or on
|-
|bowmotordirectpwm
|bmdp
|[pwm (0 - 65535)]
|Sets the ''bow motor'' power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|bowmotortimeout
|bmt
|[ms (0 - 65535)]
|Sets the ''bow motor'' shutdown timeout after bow having been put into the rest position, given in milli-seconds
|-
|bowmotorspeedmax
|bmsx
|[pwm (0 - 65535)]
|Sets ''bow motor'' maximum speed in 16-bit PWM
|-
|bowmotorspeedmin
|bmsi
|[pwm (0 - 65535)]
|Sets ''bow motor'' minimum speed in 16-bit PWM
|-
|bowmotorvoltage
|bmv
|[voltage (1.2 - 9)]
|Sets the ''bow motor'' voltage
|-
|bowmotorfrequency
|bmf
|none
|Returns the last read ''bow motor frequency''
|-
|bowmotorcurrent
|bmc
|none
|Returns the last read current usage of the ''bowing motor''
|-
|bowmotorcurrentlimit
|bmcl
|[current]
|Sets the current limit of the ''bowing motor'' in ''amperes'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorpowerlimit
|bmpl
|[power]
|Sets the power limit of the ''bowing motor'' in ''watts'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorfaultcommands
|bmfc
|[command string]
|Sets the ''commands'' to execute when a motor fault is tripped, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotoroverpowercommands
|bmopc
|[command string]
|Sets the ''commands'' to execute when the ''bowing motor'' is over the power limit, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|}

Commands for controlling bow pressure

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bowpressurebaseline
|bpb
|[pressure (0 - 65535)]
|Sets the ''pressure baseline'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressuremodifier
|bpm
|[pressure (0 - 65535)]
|Sets the ''pressure modifier'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressurerest
|bpr
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''rest position''
|-
|bowpressureengage
|bpe
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''engage position''
|-
|bowpressurepositionmax
|bppx
|[value (0 - 65535)]
|Sets the maximum hardware position of the ''bowing jack''
|-
|bowpressurepositionengage
|bppe
|[value (0 - 65535)]
|Sets the ''engage'' ''position'' hardware position of the ''bowing jack''
|-
|bowpressurepositionrest
|bppr
|[value (0 - 65535)]
|Sets the ''rest position'' hardware position of the ''bowing jack''
|-
|bowpressureengagespeed
|bpes
|[speed (0 - 100)]
|Sets the speed of the ''pressure motor'' in RPM when going from ''rest'' to ''engage'' or vice versa. Setting this value too high will result in the ''pressure motor'' loosing track and the instrument malfunctioning as a result. Setting this value too low will result in the instrument getting increased ''latency'' and feeling sluggish.
|-
|bowpressuremodulationspeed
|bpms
|[speed (0.1 - ''bpes'')]
|Sets the speed of the ''pressure motor'' in RPM when at ''engage'' and modulating the pressure. The main purpose of this setting is to avoid the ''bowing motor'' slowing down too much when modulating the ''pressure'', resulting in audible artifacts
|-
|bowpressurehold
|bph
|<nowiki>[(0|1)]</nowiki>
|Sets ''bow hold'' off or on. If ''bow hold'' is on, any ''bowpressurerest''-command will be ignored until ''bowpressurehold'' is set to off. Analog to the concept of ''infinite sustain''
|}

Commands for solenoid control

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|solenoid
|so
|[('0')]
|Sets the ''current solenoid''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''solenoid'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|solenoidengage
|se
|[force (0 - 65535)]
|Engages the ''current solenoid'' with the ''force'' given, the ''force'' is mutiplied by the ''force multiplier'' as set by ''solenoidforcemultiplier''. The ''force'' is scaled according to the ''solenoidmaxforce'' and ''solenoidminforce'' parameters, a ''force'' of ''0'' always means to not engage. Also see ''solenoidengageduration''
|-
|solenoiddisengage
|sd
|<nowiki>[conditional (0|1)]</nowiki>
|Disengages the ''solenoid''
|-
|solenoidmaxforce
|sxf
|[value (0 - 65535)]
|Sets the maximum hardware force used
|-
|solenoidminforce
|sif
|[value (0 - 65535)]
|Sets the minimum hardware force used
|-
|solenoidforcemultiplier
|sfm
|[value (0 - 1)]
|Sets the value of the ''force multiplier''
|-
|solenoidengageduration
|sed
|[duration (0 - 65535)]
|Sets the duration of the ''solenoid engagement'' in ɥS. if a value of ''0'' is set the ''solenoid'' will not disengage until a ''solenoiddisengage-''command has been given. This latter behavior is not encouraged as it '''can ruin the instrument if improperly used'''
|}

Commands for controlling the mute

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|mutesetposition
|msp
|[position (0 - 65535)]
|Sets the ''mute position'', scaled by the ''mutefullmuteposition'' and ''muterestposition''
|-
|mutefullmute
|mfm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''full mute position''
|-
|mutehalfmute
|mhm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''half mute position''
|-
|muterest
|mr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''mute rest position''
|-
|mutesavefull
|msf
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''full mute position'' to be equal to the current ''mute position''
|-
|mutesavehalf
|msh
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''half mute position'' to be equal to the current ''mute position''
|-
|mutesaverest
|msr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute rest position'' to be equal to the current ''mute position''
|-
|mutefullmuteposition
|mfmp
|[value (0 - 65535)]
|Sets the ''full mute position'' to ''value''
|-
|mutehalfmuteposition
|mhmp
|[value (0 - 65535)]
|Sets the ''half mute position'' to ''value''
|-
|muterestposition
|mrp
|[value (0 - 65535)]
|Sets the ''mute rest position'' to ''value''
|-
|mutesustain
|ms
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute sustain'' to ''off'' or ''on''. When ''mute sustain'' is ''on'', any ''mutefullmute-''commands sent will be ignored until ''mute sustain'' is set to ''off''
|-
|mutebackoff
|mbo
|[backoff (0 - 65535)]
|Sets the ''mute backoff'' to ''backoff'', given in mS. The ''mute backoff'' sets the time that the ''mute'' stays in the ''mutefullmute'' position before automatically going to the ''rest position''
|-
|mutehome
|mh
|none
|Homing the ''mute''
|-
|mutecalibrate
|mca
|none
|Runs the ''mute calibration''
|}

Commands for bow actuators

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|<s>bowactuatoradd</s>
|baa
|none
|Add new bow ''actuator''
|-
|bowacutatorremove
|bar
|[actuator]
|Removes the ''actuator'' given in the ''parameter''
|-
|<s>bowactuatorset</s>
|bas
|[actuator]
|Sets the ''current actuator'' to the number given in the ''parameter''
|-
|<s>bowactuatorload</s>
|bal
|none
|Loads data from the ''current actuator''
|-
|bowactuatorsave
|bas
|none
|Saves the ''bow pressure position rest, bow pressure position engage'' and ''bow pressure position max'' into the ''current actuator''
|-
|bowactuatordata
|bad
|[actuator]:[engage]:[max]:[rest]:[id]
|Sets the ''bow pressure position engage, bow pressure position max, bow pressure position rest'' and ''actuator id'' of the ''actuator'' given by the first ''parameter''
|-
|bowactuatorcount
|bac
|none
|Returns the number of saved ''actuators''
|-
|<s>bowactuatorid</s>
|bai
|id
|Sets the ''id'' of the ''current actuator''
|}
Please note that ''commands'' may be added or subtracted from this list as the Ekdahl FAR ''firmware'' development progresses, the most sincere attempts will be made to keep this list up to date but no guarantees will be made.{{docnav
|[[The Ekdahl FAR - Command langue|Command language]]
|[[The Ekdahl FAR - Specifications|Specifications]]
}}

The Ekdahl FAR - Command reference

2025-02-03T21:06:45Z

Knaadmin:

== Introduction ==
The ''commands'' in the Ekdahl FAR are using a certain ''naming convention'' to make it more clear which parts of the instrument a certain ''command'' is dealing with. Furthermore commands can be global or local, global commands change settings that will affect the entire instrument, local commands change settings depending on previously set commands. The idea of local commands is a future-proofing of the Ekdahl FAR firmware and can generally be ignored for the time being. The first part of many ''command''-names are a prefix that denotes category, the ''global'' categories as of this writing (2025-01-26) are:

* ''global*'' - commands that have a global reach
* ''midi*'' - commands that deal with ''MIDI''
* ''adc*'' - commands that deal with the ''Control box'' and its ''analog-to-digital converter''
* ''expressionparser'' - commands that deal with how ''commands'' are interpreted and parsed, mainly used for debugging
* ''test''* - commands made for testing and debugging

The ''global'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|requestinfo
|rqi
|[command]:[optional parameters]
|Uses a ''command''-name to retrieve rather than set information associated with it, some commands have no information associated and will return nothing. Some commands require the use of optional ''parameters'' to specify which information that is to be retrieved.
|-
|module
|m
|[module number (0)]
|Sets the current ''module''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''string module.'' Currently '0' is the only valid ''parameter''
|-
|modulecount
|mc
|none
|Returns the number of ''modules'' in the Ekdahl FAR. Currently always returns '1'
|-
|debugprint
|dp
|<nowiki>[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]</nowiki>
|Used to turn on or off whether the instrument will return certain information over ''USB-Serial''. The first ''parameter'' is the category, the second ''parameter'' is a boolean value.
|-
|version
|ver
|none
|Returns the current ''firmware'' version
|-
|globalsaveallparameters
|gsap
|none
|Saves all current data into the internal flash memory
|-
|globalloadallparameters
|glap
|none
|Loads all data saved into flash, effectively overwriting any changed parameters included in the last save
|-
|globalresetparameters
|grap
|none
|Resets all saved data in the flash memory, requires a immediate reset to be enacted
|-
|globaluservariable
|guv
|[variable number (0-9)]:[value (float)]
|Sets or returns the user variable defined in the first ''parameter,'' if used to set the variable, the second ''parameter'' is the value.
|-
|expressionparserevaluate
|epev
|[expression]
|Evaluates the given ''expression'' and returns the calculated value. Used for debugging
|-
|testadclatency
|tal
|[value (0 - 65535)]
|Debugging command to test ADC latency
|-
|testadclatencyreturn
|talr
|none
|Stops ADC latency testing started with ''tal''
|-
|testadcminmac
|tamm
|[channel]
|Debugging command to test the min/max value for a given ''channel''
|}

MIDI commands

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|midiconfiguration
|mcf
|[config (0-9)]
|Sets or returns the ''current MIDI configuration''
|-
|midiconfigurationadd
|mcfa
|none
|Adds a new ''MIDI configuration''
|-
|midiconfigurationremove
|mcfr
|[config (0-9)]
|Removes the ''MIDI configuration'' denoted by the ''parameter'' passed. If there are ''MIDI configurations'' with a higher number, these are moved down the list. The ''current configuration'' may be changed during the execution of this ''command''
|-
|midiconfigurationcount
|mcfc
|none
|Returns the number of ''MIDI configurations'' available
|-
|midiconfigurationname
|mcfn
|<nowiki>[config|name]</nowiki>
|When used as a 'set'-command, the first ''parameter'' sets the name of the ''current MIDI configuration''. When used to retrieve information, the first ''parameter'' sets which ''MIDI configuration'' to return the name for
|-
|midieventhandler
|mev
|<nowiki>[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]</nowiki>
|Used to set the ''command string'' executed when a certain ''MIDI event'' occurs. The first ''parameter'' is the type of ''MIDI event.'' With exception for the ''<nowiki/>'cc' MIDI event'' the second ''parameter'' is the ''command string''. For ''<nowiki/>'cc''' the second ''parameter'' is the ''controller number'' and the third ''parameter'' is the ''command string''
|-
|midiconfigurationdefaults
|mcfd
|none
|Reverts all settings of the ''current MIDI configuration'' to default values and remove any added ''continuous controllers''
|-
|midireceivechannel
|mrc
|[channel (0-16)]
|Sets which ''MIDI channel'' the instrument will respond to. 1-16 sets the ''MIDI channel'' while all other values sets the instrument to ''<nowiki/>'Omni''' (the instrument responding to all channels)
|-
|midiallnotesoff
|mano
|<nowiki>[conditional (0|1)]</nowiki>
|Clears the entire ''MIDI'' buffer of notes held and turns off any bowing
|}

ADC / Control box commands

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|adccommandmap
|acm
|[channel]:[command string]
|Sets the ''command string'' associated with the ''analog-to-digital converter channel'' of the ''Control box''
|-
|adcdefaults
|acd
|none
|Sets all ''command strings'' associated with all ''analog-to-digital converter channels'' to their default values
|-
|adcread
|adcr
|[channel]:[return only: value]
|Returns the last value read by the ''analog-to-digital converter'' of the ''Command box'' on the ''channel'' given. This value is sent automatically any time a change in data is read
|-
|adcsettings
|adcs
|[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]
|Sets the settings for the ''averager'' used for the given ''Control box analog-to-digital channel''. ''Averages'' denote number of values read and averaged, ''interrupterrorthreshold'' sets the value change required for the ''Control box'' to report a new value. The ''continuouserrorthreshold'' and ''continuoustimeout'' are used to allow for ''continuous'' changes. See the ''firmware'' for more information
|}

MIDI commands

The ''local'' commands as of this writing (2025-01-26) are:

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bow
|bow
|[bow (0)]
|Sets the ''current bow.'' This command is intended for future versions of the Ekdahl FAR that may have more than one ''bow'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|bowpid
|bpid
|<nowiki>[conditional (0|1)]</nowiki>
|Sets whether the [[wikipedia:Proportional–integral–derivative_controller|Proprtional-Integral-Deriviate controller]] is on or off. For all normal operation, the ''PID'' should be turned on. If it is turned off the instrument will not be able to play specific frequencies, but will only respond to ''bowmotordirectpwm''-commands
|-
|bowpidki
|bpki
|[float]
|Sets the ''ki''-value of the ''PID''
|-
|bowpidkp
|bpkp
|[float]
|Sets the ''kp-''value of the ''PID''
|-
|bowpidkd
|bpkd
|[float]
|Sets the ''kd''-value of the ''PID''
|-
|bowpidintegratorerror
|bpie
|[float]
|Sets the minimum ''error value'' required in between the ''set point'' and the ''process variable'' for the integrator part of the ''PID'' to initiate correction
|-
|bowpidmaxerror
|bpme
|[float]
|Sets the maximum error correction attempted in each call to the ''PID loop''
|-
|bowpidr
|bpir
|none
|Resets all data stored by the ''PID''
|-
|bowpidpeakerror
|bpperr
|none
|Returns the last ''error value'' measured in between the ''set point'' and the ''process variable''
|-
|bowcontrolfrequecy
|bcf
|[float]
|Sets the frequency (in Hertz) that the ''bowing motor'' should attempt to run at
|-
|bowcontrolfundamental
|bcu
|[float]
|Sets the ''fundamental frequency'' that all ''harmonics'' are using as its base for calculations
|-
|bowcontrolharmonic
|bch
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed''. See ''bowcontrolharmonicadd'' and ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicadd
|bcha
|[float]
|Sets the number of ''harmonic numbers'' to add or remove to the value given in ''bowcontrolharmonic'' and ''bowcontrolharmonicbase''. Can be negative values
|-
|bowcontrolharmonicbase
|bchb
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed'' but uses the value set by ''bowcontrolharmonicbasenote'' as its base. Includes any value set by ''bowcontrolharmonicadd'' and overwrites any value set by ''bowcontrolharmonic''
|-
|bowcontrolharmonicbasenote
|bchbn
|[midi key (0-127)]
|Sets the ''MIDI'' key to use as the base for ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicshift
|bchsh
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. The ''harmonic shift'' is dependent on the range set by ''bowcontrolharmonicshiftrange''. Also see ''bowcontrolharmonicshift5''
|-
|bowcontrolharmonicshiftrange
|bchsr
|[harmonics (0-36)]
|Sets the range of the ''bowcontrolharmonicshift''-command. The ''parameter'' given denotes how many ''harmonic numbers'' to shift from the current ''harmonic number'' when the maximum ''harmonic shift'' has been set.
|-
|bowcontrolharmonicshift5
|bchs5
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. Unlike ''bowcontrolharmonicshift'' this value is always calculated on a range of 5 octaves, meaning a maximum ''harmonic shift'' will equal 5 times the amount of ''harmonic ratios'' in the current ''harmonic table''. This value is added to the ''harmonic shift'' set by ''bowcontrolharmonicshift''
|-
|bowcontrolspeedmode
|bcsm
|<nowiki>[mode (0|1)]</nowiki>
|Sets the ''speed mode'' where ''0 = Automatic'' and ''1 = Manual''. The only difference in between these two modes is that ''Automatic'' will automatically turn off the motor when the bow has been set in its ''rest position'' and no frequency changing ''commands'' have been sent within the time period given by ''bowmotortimeout''
|}

Commands for controlling harmonic series

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bowharmonicseries
|bhs
|[series]
|Sets the ''current harmonic series''
|-
|bowharmonicseriesdata
|bhsl
|[(set only) series]:[name]:[ratios]
|Sets all ''ratios'' and the ''name'' of the ''harmonic list'' in the given ''series''. There can be any number of ''ratio''-parameters and this effectively sets the number of ''harmonics'' per octave. If required, empty ''harmonic lists'' will be added until ''slot'' is a valid number. On return, requires [series] and returns ''name'' and ''ratios'' of the ''harmonic series'' given
|-
|bowharmonicseriesratio
|bhsr
|[harmonic]:[ratio]
|Sets the ''ratio'' of the given ''harmonic number'' in the ''current harmonic series''. Will increase the number of ratios in the series if needed
|-
|bowharmonicseriesratioremove
|bhsrr
|[ratio]
|Removes the ''ratio'' given, will move all ''ratios'' with a higher ''harmonic number'' in the series. Cannot remove all ''ratios''
|-
|bowharmonicseriescount
|bhsc
|none
|Returns the number of ''harmonic series'' and their ''names'' in the format ''ratios:name1:name2 [etc]''
|-
|bowharmonicseriessave
|bhss
|[series]:[name]
|Saves the current ''harmonic series'' into the slot given by the second ''parameter'' with the name give in the first ''parameter''. Note that this ''command'' does not save it into flash memory
|-
|bowharmonicseriesremove
|bhsrm
|[series]
|Removes the ''harmonic series'' given in the ''parameter''. Shifts all ''series''' with a higher ''series'' number
|}

Various

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bowstatus
|bs
|none
|Outputs debugging data. Deprecated
|-
|pickupstringfrequency
|psf
|none
|Returns the fundamental frequency calculated from the current audio signal if, applicable
|-
|pickupaudiopeak
|pap
|none
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
|none
|Returns the [[wikipedia:Root_mean_square|RMS]] amplitude of the current audio signal
|-
|bowdebugmeasuretimetotarget
|bdmtt
|[frequency]
|Measure the time it takes to change from the current frequency to the target frequency, used to debug the ''PID''
|-
|bowhome
|bh
|none
|Homing bow, used at startup and in case of the bow loosing position
|-
|bowcalibrateall
|bca
|none
|Performs all calibration routines for a single bow available in the given firmware
|-
|bowcalibratespeed
|bcf
|none
|Performs a ''bowing speed calibration''
|-
|bowcalibratepressure
|bcp
|none
|Performs a ''pressure calibration''
|-
|nooperation
|nop
|none
|Do absolutely, positively, nothing
|}

Commands relating to the bowing motor

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bowmotorrun
|bmr
|<nowiki>[(0|1)]</nowiki>
|Sets the ''bow motor'' to off or on
|-
|bowmotordirectpwm
|bmdp
|[pwm (0 - 65535)]
|Sets the ''bow motor'' power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|bowmotortimeout
|bmt
|[ms (0 - 65535)]
|Sets the ''bow motor'' shutdown timeout after bow having been put into the rest position, given in milli-seconds
|-
|bowmotorspeedmax
|bmsx
|[pwm (0 - 65535)]
|Sets ''bow motor'' maximum speed in 16-bit PWM
|-
|bowmotorspeedmin
|bmsi
|[pwm (0 - 65535)]
|Sets ''bow motor'' minimum speed in 16-bit PWM
|-
|bowmotorvoltage
|bmv
|[voltage (1.2 - 9)]
|Sets the ''bow motor'' voltage
|-
|bowmotorfrequency
|bmf
|none
|Returns the last read ''bow motor frequency''
|-
|bowmotorcurrent
|bmc
|none
|Returns the last read current usage of the ''bowing motor''
|-
|bowmotorcurrentlimit
|bmcl
|[current]
|Sets the current limit of the ''bowing motor'' in ''amperes'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorpowerlimit
|bmpl
|[power]
|Sets the power limit of the ''bowing motor'' in ''watts'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorfaultcommands
|bmfc
|[command string]
|Sets the ''commands'' to execute when a motor fault is tripped, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotoroverpowercommands
|bmopc
|[command string]
|Sets the ''commands'' to execute when the ''bowing motor'' is over the power limit, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|}

Commands for controlling bow pressure

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bowpressurebaseline
|bpb
|[pressure (0 - 65535)]
|Sets the ''pressure baseline'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressuremodifier
|bpm
|[pressure (0 - 65535)]
|Sets the ''pressure modifier'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressurerest
|bpr
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''rest position''
|-
|bowpressureengage
|bpe
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''engage position''
|-
|bowpressurepositionmax
|bppx
|[value (0 - 65535)]
|Sets the maximum hardware position of the ''bowing jack''
|-
|bowpressurepositionengage
|bppe
|[value (0 - 65535)]
|Sets the ''engage'' ''position'' hardware position of the ''bowing jack''
|-
|bowpressurepositionrest
|bppr
|[value (0 - 65535)]
|Sets the ''rest position'' hardware position of the ''bowing jack''
|-
|bowpressureengagespeed
|bpes
|[speed (0 - 100)]
|Sets the speed of the ''pressure motor'' in RPM when going from ''rest'' to ''engage'' or vice versa. Setting this value too high will result in the ''pressure motor'' loosing track and the instrument malfunctioning as a result. Setting this value too low will result in the instrument getting increased ''latency'' and feeling sluggish.
|-
|bowpressuremodulationspeed
|bpms
|[speed (0.1 - ''bpes'')]
|Sets the speed of the ''pressure motor'' in RPM when at ''engage'' and modulating the pressure. The main purpose of this setting is to avoid the ''bowing motor'' slowing down too much when modulating the ''pressure'', resulting in audible artifacts
|-
|bowpressurehold
|bph
|<nowiki>[(0|1)]</nowiki>
|Sets ''bow hold'' off or on. If ''bow hold'' is on, any ''bowpressurerest''-command will be ignored until ''bowpressurehold'' is set to off. Analog to the concept of ''infinite sustain''
|}

Commands for solenoid control

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|solenoid
|so
|[('0')]
|Sets the ''current solenoid''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''solenoid'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|solenoidengage
|se
|[force (0 - 65535)]
|Engages the ''current solenoid'' with the ''force'' given, the ''force'' is mutiplied by the ''force multiplier'' as set by ''solenoidforcemultiplier''. The ''force'' is scaled according to the ''solenoidmaxforce'' and ''solenoidminforce'' parameters, a ''force'' of ''0'' always means to not engage. Also see ''solenoidengageduration''
|-
|solenoiddisengage
|sd
|<nowiki>[conditional (0|1)]</nowiki>
|Disengages the ''solenoid''
|-
|solenoidmaxforce
|sxf
|[value (0 - 65535)]
|Sets the maximum hardware force used
|-
|solenoidminforce
|sif
|[value (0 - 65535)]
|Sets the minimum hardware force used
|-
|solenoidforcemultiplier
|sfm
|[value (0 - 1)]
|Sets the value of the ''force multiplier''
|-
|solenoidengageduration
|sed
|[duration (0 - 65535)]
|Sets the duration of the ''solenoid engagement'' in ɥS. if a value of ''0'' is set the ''solenoid'' will not disengage until a ''solenoiddisengage-''command has been given. This latter behavior is not encouraged as it '''can ruin the instrument if improperly used'''
|}

Commands for controlling the mute

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|mutesetposition
|msp
|[position (0 - 65535)]
|Sets the ''mute position'', scaled by the ''mutefullmuteposition'' and ''muterestposition''
|-
|mutefullmute
|mfm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''full mute position''
|-
|mutehalfmute
|mhm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''half mute position''
|-
|muterest
|mr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''mute rest position''
|-
|mutesavefull
|msf
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''full mute position'' to be equal to the current ''mute position''
|-
|mutesavehalf
|msh
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''half mute position'' to be equal to the current ''mute position''
|-
|mutesaverest
|msr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute rest position'' to be equal to the current ''mute position''
|-
|mutefullmuteposition
|mfmp
|[value (0 - 65535)]
|Sets the ''full mute position'' to ''value''
|-
|mutehalfmuteposition
|mhmp
|[value (0 - 65535)]
|Sets the ''half mute position'' to ''value''
|-
|muterestposition
|mrp
|[value (0 - 65535)]
|Sets the ''mute rest position'' to ''value''
|-
|mutesustain
|ms
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute sustain'' to ''off'' or ''on''. When ''mute sustain'' is ''on'', any ''mutefullmute-''commands sent will be ignored until ''mute sustain'' is set to ''off''
|-
|mutebackoff
|mbo
|[backoff (0 - 65535)]
|Sets the ''mute backoff'' to ''backoff'', given in mS. The ''mute backoff'' sets the time that the ''mute'' stays in the ''mutefullmute'' position before automatically going to the ''rest position''
|-
|mutehome
|mh
|none
|Homing the ''mute''
|-
|mutecalibrate
|mca
|none
|Runs the ''mute calibration''
|}

Commands for bow actuators

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|<s>bowactuatoradd</s>
|baa
|none
|Add new bow ''actuator''
|-
|bowacutatorremove
|bar
|[actuator]
|Removes the ''actuator'' given in the ''parameter''
|-
|<s>bowactuatorset</s>
|bas
|[actuator]
|Sets the ''current actuator'' to the number given in the ''parameter''
|-
|<s>bowactuatorload</s>
|bal
|none
|Loads data from the ''current actuator''
|-
|bowactuatorsave
|bas
|none
|Saves the ''bow pressure position rest, bow pressure position engage'' and ''bow pressure position max'' into the ''current actuator''
|-
|bowactuatordata
|bad
|[actuator]:[engage]:[max]:[rest]:[id]
|Sets the ''bow pressure position engage, bow pressure position max, bow pressure position rest'' and ''actuator id'' of the ''actuator'' given by the first ''parameter''
|-
|bowactuatorcount
|bac
|none
|Returns the number of saved ''actuators''
|-
|<s>bowactuatorid</s>
|bai
|id
|Sets the ''id'' of the ''current actuator''
|}
Please note that ''commands'' may be added or subtracted from this list as the Ekdahl FAR ''firmware'' development progresses, the most sincere attempts will be made to keep this list up to date but no guarantees will be made.{{docnav
|[[The Ekdahl FAR - Command langue|Command language]]
|[[The Ekdahl FAR - Specifications|Specifications]]
}}

The Ekdahl FAR - Command reference

2025-02-03T20:57:36Z

Knaadmin:

== Introduction ==
The ''commands'' in the Ekdahl FAR are using a certain ''naming convention'' to make it more clear which parts of the instrument a certain ''command'' is dealing with. Furthermore commands can be global or local, global commands change settings that will affect the entire instrument, local commands change settings depending on previously set commands. The idea of local commands is a future-proofing of the Ekdahl FAR firmware and can generally be ignored for the time being. The first part of many ''command''-names are a prefix that denotes category, the ''global'' categories as of this writing (2025-01-26) are:

* ''global*'' - commands that have a global reach
* ''midi*'' - commands that deal with ''MIDI''
* ''adc*'' - commands that deal with the ''Control box'' and its ''analog-to-digital converter''
* ''expressionparser'' - commands that deal with how ''commands'' are interpreted and parsed, mainly used for debugging
* ''test''* - commands made for testing and debugging

The ''global'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|requestinfo
|rqi
|[command]:[optional parameters]
|Uses a ''command''-name to retrieve rather than set information associated with it, some commands have no information associated and will return nothing. Some commands require the use of optional ''parameters'' to specify which information that is to be retrieved.
|-
|module
|m
|[module number (0)]
|Sets the current ''module''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''string module.'' Currently '0' is the only valid ''parameter''
|-
|modulecount
|mc
|none
|Returns the number of ''modules'' in the Ekdahl FAR. Currently always returns '1'
|-
|debugprint
|dp
|<nowiki>[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]</nowiki>
|Used to turn on or off whether the instrument will return certain information over ''USB-Serial''. The first ''parameter'' is the category, the second ''parameter'' is a boolean value.
|-
|version
|ver
|none
|Returns the current ''firmware'' version
|-
|globalsaveallparameters
|gsap
|none
|Saves all current data into the internal flash memory
|-
|globalloadallparameters
|glap
|none
|Loads all data saved into flash, effectively overwriting any changed parameters included in the last save
|-
|globalresetparameters
|grap
|none
|Resets all saved data in the flash memory, requires a immediate reset to be enacted
|-
|globaluservariable
|guv
|[variable number (0-9)]:[value (float)]
|Sets or returns the user variable defined in the first ''parameter,'' if used to set the variable, the second ''parameter'' is the value.
|-
|midiconfiguration
|mcf
|[config (0-9)]
|Sets or returns the ''current MIDI configuration''
|-
|midiconfigurationadd
|mcfa
|none
|Adds a new ''MIDI configuration''
|-
|midiconfigurationremove
|mcfr
|[config (0-9)]
|Removes the ''MIDI configuration'' denoted by the ''parameter'' passed. If there are ''MIDI configurations'' with a higher number, these are moved down the list. The ''current configuration'' may be changed during the execution of this ''command''
|-
|midiconfigurationcount
|mcfc
|none
|Returns the number of ''MIDI configurations'' available
|-
|midiconfigurationname
|mcfn
|<nowiki>[config|name]</nowiki>
|When used as a 'set'-command, the first ''parameter'' sets the name of the ''current MIDI configuration''. When used to retrieve information, the first ''parameter'' sets which ''MIDI configuration'' to return the name for
|-
|midieventhandler
|mev
|<nowiki>[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]</nowiki>
|Used to set the ''command string'' executed when a certain ''MIDI event'' occurs. The first ''parameter'' is the type of ''MIDI event.'' With exception for the ''<nowiki/>'cc' MIDI event'' the second ''parameter'' is the ''command string''. For ''<nowiki/>'cc''' the second ''parameter'' is the ''controller number'' and the third ''parameter'' is the ''command string''
|-
|midiconfigurationdefaults
|mcfd
|none
|Reverts all settings of the ''current MIDI configuration'' to default values and remove any added ''continuous controllers''
|-
|midireceivechannel
|mrc
|[channel (0-16)]
|Sets which ''MIDI channel'' the instrument will respond to. 1-16 sets the ''MIDI channel'' while all other values sets the instrument to ''<nowiki/>'Omni''' (the instrument responding to all channels)
|-
|midiallnotesoff
|mano
|<nowiki>[conditional (0|1)]</nowiki>
|Clears the entire ''MIDI'' buffer of notes held and turns off any bowing
|-
|adccommandmap
|acm
|[channel]:[command string]
|Sets the ''command string'' associated with the ''analog-to-digital converter channel'' of the ''Control box''
|-
|adcdefaults
|acd
|none
|Sets all ''command strings'' associated with all ''analog-to-digital converter channels'' to their default values
|-
|adcread
|adcr
|[channel]:[return only: value]
|Returns the last value read by the ''analog-to-digital converter'' of the ''Command box'' on the ''channel'' given. This value is sent automatically any time a change in data is read
|-
|adcsettings
|adcs
|[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]
|Sets the settings for the ''averager'' used for the given ''Control box analog-to-digital channel''. ''Averages'' denote number of values read and averaged, ''interrupterrorthreshold'' sets the value change required for the ''Control box'' to report a new value. The ''continuouserrorthreshold'' and ''continuoustimeout'' are used to allow for ''continuous'' changes. See the ''firmware'' for more information
|-
|expressionparserevaluate
|epev
|[expression]
|Evaluates the given ''expression'' and returns the calculated value. Used for debugging
|-
|testadclatency
|tal
|[value (0 - 65535)]
|Debugging command to test ADC latency
|-
|testadclatencyreturn
|talr
|none
|Stops ADC latency testing started with ''tal''
|-
|testadcminmac
|tamm
|[channel]
|Debugging command to test the min/max value for a given ''channel''
|}
The ''local'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bow
|bow
|[bow (0)]
|Sets the ''current bow.'' This command is intended for future versions of the Ekdahl FAR that may have more than one ''bow'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|bowpid
|bpid
|<nowiki>[conditional (0|1)]</nowiki>
|Sets whether the [[wikipedia:Proportional–integral–derivative_controller|Proprtional-Integral-Deriviate controller]] is on or off. For all normal operation, the ''PID'' should be turned on. If it is turned off the instrument will not be able to play specific frequencies, but will only respond to ''bowmotordirectpwm''-commands
|-
|bowpidki
|bpki
|[float]
|Sets the ''ki''-value of the ''PID''
|-
|bowpidkp
|bpkp
|[float]
|Sets the ''kp-''value of the ''PID''
|-
|bowpidkd
|bpkd
|[float]
|Sets the ''kd''-value of the ''PID''
|-
|bowpidintegratorerror
|bpie
|[float]
|Sets the minimum ''error value'' required in between the ''set point'' and the ''process variable'' for the integrator part of the ''PID'' to initiate correction
|-
|bowpidmaxerror
|bpme
|[float]
|Sets the maximum error correction attempted in each call to the ''PID loop''
|-
|bowpidr
|bpir
|none
|Resets all data stored by the ''PID''
|-
|bowpidpeakerror
|bpperr
|none
|Returns the last ''error value'' measured in between the ''set point'' and the ''process variable''
|-
|bowcontrolfrequecy
|bcf
|[float]
|Sets the frequency (in Hertz) that the ''bowing motor'' should attempt to run at
|-
|bowcontrolfundamental
|bcu
|[float]
|Sets the ''fundamental frequency'' that all ''harmonics'' are using as its base for calculations
|-
|bowcontrolharmonic
|bch
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed''. See ''bowcontrolharmonicadd'' and ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicadd
|bcha
|[float]
|Sets the number of ''harmonic numbers'' to add or remove to the value given in ''bowcontrolharmonic'' and ''bowcontrolharmonicbase''. Can be negative values
|-
|bowcontrolharmonicbase
|bchb
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed'' but uses the value set by ''bowcontrolharmonicbasenote'' as its base. Includes any value set by ''bowcontrolharmonicadd'' and overwrites any value set by ''bowcontrolharmonic''
|-
|bowcontrolharmonicbasenote
|bchbn
|[midi key (0-127)]
|Sets the ''MIDI'' key to use as the base for ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicshift
|bchsh
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. The ''harmonic shift'' is dependent on the range set by ''bowcontrolharmonicshiftrange''. Also see ''bowcontrolharmonicshift5''
|-
|bowcontrolharmonicshiftrange
|bchsr
|[harmonics (0-36)]
|Sets the range of the ''bowcontrolharmonicshift''-command. The ''parameter'' given denotes how many ''harmonic numbers'' to shift from the current ''harmonic number'' when the maximum ''harmonic shift'' has been set.
|-
|bowcontrolharmonicshift5
|bchs5
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. Unlike ''bowcontrolharmonicshift'' this value is always calculated on a range of 5 octaves, meaning a maximum ''harmonic shift'' will equal 5 times the amount of ''harmonic ratios'' in the current ''harmonic table''. This value is added to the ''harmonic shift'' set by ''bowcontrolharmonicshift''
|-
|bowcontrolspeedmode
|bcsm
|<nowiki>[mode (0|1)]</nowiki>
|Sets the ''speed mode'' where ''0 = Automatic'' and ''1 = Manual''. The only difference in between these two modes is that ''Automatic'' will automatically turn off the motor when the bow has been set in its ''rest position'' and no frequency changing ''commands'' have been sent within the time period given by ''bowmotortimeout''
|-
|bowharmonicseries
|bhs
|[series]
|Sets the ''current harmonic series''
|-
|bowharmonicseriesdata
|bhsl
|[(set only) series]:[name]:[ratios]
|Sets all ''ratios'' and the ''name'' of the ''harmonic list'' in the given ''series''. There can be any number of ''ratio''-parameters and this effectively sets the number of ''harmonics'' per octave. If required, empty ''harmonic lists'' will be added until ''slot'' is a valid number. On return, requires [series] and returns ''name'' and ''ratios'' of the ''harmonic series'' given
|-
|bowharmonicseriesratio
|bhsr
|[harmonic]:[ratio]
|Sets the ''ratio'' of the given ''harmonic number'' in the ''current harmonic series''. Will increase the number of ratios in the series if needed
|-
|bowharmonicseriesratioremove
|bhsrr
|[ratio]
|Removes the ''ratio'' given, will move all ''ratios'' with a higher ''harmonic number'' in the series. Cannot remove all ''ratios''
|-
|bowharmonicseriescount
|bhsc
|none
|Returns the number of ''harmonic series'' and their ''names'' in the format ''ratios:name1:name2 [etc]''
|-
|bowharmonicseriessave
|bhss
|[series]:[name]
|Saves the current ''harmonic series'' into the slot given by the second ''parameter'' with the name give in the first ''parameter''. Note that this ''command'' does not save it into flash memory
|-
|bowharmonicseriesremove
|bhsrm
|[series]
|Removes the ''harmonic series'' given in the ''parameter''. Shifts all ''series''' with a higher ''series'' number
|-
|bowstatus
|bs
|none
|Outputs debugging data. Deprecated
|-
|pickupstringfrequency
|psf
|none
|Returns the fundamental frequency calculated from the current audio signal if, applicable
|-
|pickupaudiopeak
|pap
|none
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
|none
|Returns the [[wikipedia:Root_mean_square|RMS]] amplitude of the current audio signal
|-
|bowdebugmeasuretimetotarget
|bdmtt
|[frequency]
|Measure the time it takes to change from the current frequency to the target frequency, used to debug the ''PID''
|-
|bowhome
|bh
|none
|Homing bow, used at startup and in case of the bow loosing position
|-
|bowcalibrateall
|bca
|none
|Performs all calibration routines for a single bow available in the given firmware
|-
|bowcalibratespeed
|bcf
|none
|Performs a ''bowing speed calibration''
|-
|bowcalibratepressure
|bcp
|none
|Performs a ''pressure calibration''
|-
|bowmotorrun
|bmr
|<nowiki>[(0|1)]</nowiki>
|Sets the ''bow motor'' to off or on
|-
|bowmotordirectpwm
|bmdp
|[pwm (0 - 65535)]
|Sets the ''bow motor'' power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|bowmotortimeout
|bmt
|[ms (0 - 65535)]
|Sets the ''bow motor'' shutdown timeout after bow having been put into the rest position, given in milli-seconds
|-
|bowmotorspeedmax
|bmsx
|[pwm (0 - 65535)]
|Sets ''bow motor'' maximum speed in 16-bit PWM
|-
|bowmotorspeedmin
|bmsi
|[pwm (0 - 65535)]
|Sets ''bow motor'' minimum speed in 16-bit PWM
|-
|bowmotorvoltage
|bmv
|[voltage (1.2 - 9)]
|Sets the ''bow motor'' voltage
|-
|bowmotorfrequency
|bmf
|none
|Returns the last read ''bow motor frequency''
|-
|bowmotorcurrent
|bmc
|none
|Returns the last read current usage of the ''bowing motor''
|-
|bowmotorcurrentlimit
|bmcl
|[current]
|Sets the current limit of the ''bowing motor'' in ''amperes'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorpowerlimit
|bmpl
|[power]
|Sets the power limit of the ''bowing motor'' in ''watts'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorfaultcommands
|bmfc
|[command string]
|Sets the ''commands'' to execute when a motor fault is tripped, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotoroverpowercommands
|bmopc
|[command string]
|Sets the ''commands'' to execute when the ''bowing motor'' is over the power limit, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowpressurebaseline
|bpb
|[pressure (0 - 65535)]
|Sets the ''pressure baseline'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressuremodifier
|bpm
|[pressure (0 - 65535)]
|Sets the ''pressure modifier'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressurerest
|bpr
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''rest position''
|-
|bowpressureengage
|bpe
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''engage position''
|-
|bowpressurepositionmax
|bppx
|[value (0 - 65535)]
|Sets the maximum hardware position of the ''bowing jack''
|-
|bowpressurepositionengage
|bppe
|[value (0 - 65535)]
|Sets the ''engage'' ''position'' hardware position of the ''bowing jack''
|-
|bowpressurepositionrest
|bppr
|[value (0 - 65535)]
|Sets the ''rest position'' hardware position of the ''bowing jack''
|-
|bowpressureengagespeed
|bpes
|[speed (0 - 100)]
|Sets the speed of the ''pressure motor'' in RPM when going from ''rest'' to ''engage'' or vice versa. Setting this value too high will result in the ''pressure motor'' loosing track and the instrument malfunctioning as a result. Setting this value too low will result in the instrument getting increased ''latency'' and feeling sluggish.
|-
|bowpressuremodulationspeed
|bpms
|[speed (0.1 - ''bpes'')]
|Sets the speed of the ''pressure motor'' in RPM when at ''engage'' and modulating the pressure. The main purpose of this setting is to avoid the ''bowing motor'' slowing down too much when modulating the ''pressure'', resulting in audible artifacts
|-
|bowpressurehold
|bph
|<nowiki>[(0|1)]</nowiki>
|Sets ''bow hold'' off or on. If ''bow hold'' is on, any ''bowpressurerest''-command will be ignored until ''bowpressurehold'' is set to off. Analog to the concept of ''infinite sustain''
|-
|solenoid
|so
|[('0')]
|Sets the ''current solenoid''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''solenoid'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|solenoidengage
|se
|[force (0 - 65535)]
|Engages the ''current solenoid'' with the ''force'' given, the ''force'' is mutiplied by the ''force multiplier'' as set by ''solenoidforcemultiplier''. The ''force'' is scaled according to the ''solenoidmaxforce'' and ''solenoidminforce'' parameters, a ''force'' of ''0'' always means to not engage. Also see ''solenoidengageduration''
|-
|solenoiddisengage
|sd
|<nowiki>[conditional (0|1)]</nowiki>
|Disengages the ''solenoid''
|-
|solenoidmaxforce
|sxf
|[value (0 - 65535)]
|Sets the maximum hardware force used
|-
|solenoidminforce
|sif
|[value (0 - 65535)]
|Sets the minimum hardware force used
|-
|solenoidforcemultiplier
|sfm
|[value (0 - 1)]
|Sets the value of the ''force multiplier''
|-
|solenoidengageduration
|sed
|[duration (0 - 65535)]
|Sets the duration of the ''solenoid engagement'' in ɥS. if a value of ''0'' is set the ''solenoid'' will not disengage until a ''solenoiddisengage-''command has been given. This latter behavior is not encouraged as it '''can ruin the instrument if improperly used'''
|-
|mutesetposition
|msp
|[position (0 - 65535)]
|Sets the ''mute position'', scaled by the ''mutefullmuteposition'' and ''muterestposition''
|-
|mutefullmute
|mfm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''full mute position''
|-
|mutehalfmute
|mhm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''half mute position''
|-
|muterest
|mr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''mute rest position''
|-
|mutesavefull
|msf
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''full mute position'' to be equal to the current ''mute position''
|-
|mutesavehalf
|msh
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''half mute position'' to be equal to the current ''mute position''
|-
|mutesaverest
|msr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute rest position'' to be equal to the current ''mute position''
|-
|mutefullmuteposition
|mfmp
|[value (0 - 65535)]
|Sets the ''full mute position'' to ''value''
|-
|mutehalfmuteposition
|mhmp
|[value (0 - 65535)]
|Sets the ''half mute position'' to ''value''
|-
|muterestposition
|mrp
|[value (0 - 65535)]
|Sets the ''mute rest position'' to ''value''
|-
|mutesustain
|ms
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute sustain'' to ''off'' or ''on''. When ''mute sustain'' is ''on'', any ''mutefullmute-''commands sent will be ignored until ''mute sustain'' is set to ''off''
|-
|mutebackoff
|mbo
|[backoff (0 - 65535)]
|Sets the ''mute backoff'' to ''backoff'', given in mS. The ''mute backoff'' sets the time that the ''mute'' stays in the ''mutefullmute'' position before automatically going to the ''rest position''
|-
|mutehome
|mh
|none
|Homing the ''mute''
|-
|mutecalibrate
|mca
|none
|Runs the ''mute calibration''
|-
|<s>bowactuatoradd</s>
|baa
|none
|Add new bow ''actuator''
|-
|bowacutatorremove
|bar
|[actuator]
|Removes the ''actuator'' given in the ''parameter''
|-
|<s>bowactuatorset</s>
|bas
|[actuator]
|Sets the ''current actuator'' to the number given in the ''parameter''
|-
|<s>bowactuatorload</s>
|bal
|none
|Loads data from the ''current actuator''
|-
|bowactuatorsave
|bas
|none
|Saves the ''bow pressure position rest, bow pressure position engage'' and ''bow pressure position max'' into the ''current actuator''
|-
|bowactuatordata
|bad
|[actuator]:[engage]:[max]:[rest]:[id]
|Sets the ''bow pressure position engage, bow pressure position max, bow pressure position rest'' and ''actuator id'' of the ''actuator'' given by the first ''parameter''
|-
|bowactuatorcount
|bac
|none
|Returns the number of saved ''actuators''
|-
|<s>bowactuatorid</s>
|bai
|id
|Sets the ''id'' of the ''current actuator''
|-
|nooperation
|nop
|none
|Do absolutely, positively, nothing
|}
Please note that ''commands'' may be added or subtracted from this list as the Ekdahl FAR ''firmware'' development progresses, the most sincere attempts will be made to keep this list up to date but no guarantees will be made.{{docnav
|[[The Ekdahl FAR - Command langue|Command language]]
|[[The Ekdahl FAR - Specifications|Specifications]]
}}

The Ekdahl FAR - Command reference

2025-02-03T19:12:53Z

Knaadmin:

== Introduction ==
The ''commands'' in the Ekdahl FAR are using a certain ''naming convention'' to make it more clear which parts of the instrument a certain ''command'' is dealing with. Furthermore commands can be global or local, global commands change settings that will affect the entire instrument, local commands change settings depending on previously set commands. The idea of local commands is a future-proofing of the Ekdahl FAR firmware and can generally be ignored for the time being. The first part of many ''command''-names are a prefix that denotes category, the ''global'' categories as of this writing (2025-01-26) are:

* ''global*'' - commands that have a global reach
* ''midi*'' - commands that deal with ''MIDI''
* ''adc*'' - commands that deal with the ''Control box'' and its ''analog-to-digital converter''
* ''expressionparser'' - commands that deal with how ''commands'' are interpreted and parsed, mainly used for debugging
* ''test''* - commands made for testing and debugging

The ''global'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|requestinfo
|rqi
|[command]:[optional parameters]
|Uses a ''command''-name to retrieve rather than set information associated with it, some commands have no information associated and will return nothing. Some commands require the use of optional ''parameters'' to specify which information that is to be retrieved.
|-
|module
|m
|[module number (0)]
|Sets the current ''module''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''string module.'' Currently '0' is the only valid ''parameter''
|-
|modulecount
|mc
|none
|Returns the number of ''modules'' in the Ekdahl FAR. Currently always returns '1'
|-
|debugprint
|dp
|<nowiki>[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]</nowiki>
|Used to turn on or off whether the instrument will return certain information over ''USB-Serial''. The first ''parameter'' is the category, the second ''parameter'' is a boolean value.
|-
|version
|ver
|none
|Returns the current ''firmware'' version
|-
|globalsaveallparameters
|gsap
|none
|Saves all current data into the internal flash memory
|-
|globalloadallparameters
|glap
|none
|Loads all data saved into flash, effectively overwriting any changed parameters included in the last save
|-
|globalresetparameters
|grap
|none
|Resets all saved data in the flash memory, requires a immediate reset to be enacted
|-
|globaluservariable
|guv
|[variable number (0-9)]:[value (float)]
|Sets or returns the user variable defined in the first ''parameter,'' if used to set the variable, the second ''parameter'' is the value.
|-
|midiconfiguration
|mcf
|[config (0-9)]
|Sets or returns the ''current MIDI configuration''
|-
|midiconfigurationadd
|mcfa
|none
|Adds a new ''MIDI configuration''
|-
|midiconfigurationremove
|mcfr
|[config (0-9)]
|Removes the ''MIDI configuration'' denoted by the ''parameter'' passed. If there are ''MIDI configurations'' with a higher number, these are moved down the list. The ''current configuration'' may be changed during the execution of this ''command''
|-
|midiconfigurationcount
|mcfc
|none
|Returns the number of ''MIDI configurations'' available
|-
|midiconfigurationname
|mcfn
|<nowiki>[config|name]</nowiki>
|When used as a 'set'-command, the first ''parameter'' sets the name of the ''current MIDI configuration''. When used to retrieve information, the first ''parameter'' sets which ''MIDI configuration'' to return the name for
|-
|midieventhandler
|mev
|<nowiki>[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]</nowiki>
|Used to set the ''command string'' executed when a certain ''MIDI event'' occurs. The first ''parameter'' is the type of ''MIDI event.'' With exception for the ''<nowiki/>'cc' MIDI event'' the second ''parameter'' is the ''command string''. For ''<nowiki/>'cc''' the second ''parameter'' is the ''controller number'' and the third ''parameter'' is the ''command string''
|-
|midiconfigurationdefaults
|mcfd
|none
|Reverts all settings of the ''current MIDI configuration'' to default values and remove any added ''continuous controllers''
|-
|midireceivechannel
|mrc
|[channel (0-16)]
|Sets which ''MIDI channel'' the instrument will respond to. 1-16 sets the ''MIDI channel'' while all other values sets the instrument to ''<nowiki/>'Omni''' (the instrument responding to all channels)
|-
|midiallnotesoff
|mano
|<nowiki>[conditional (0|1)]</nowiki>
|Clears the entire ''MIDI'' buffer of notes held and turns off any bowing
|-
|adccommandmap
|acm
|[channel]:[command string]
|Sets the ''command string'' associated with the ''analog-to-digital converter channel'' of the ''Control box''
|-
|adcdefaults
|acd
|none
|Sets all ''command strings'' associated with all ''analog-to-digital converter channels'' to their default values
|-
|adcread
|adcr
|[channel]:[return only: value]
|Returns the last value read by the ''analog-to-digital converter'' of the ''Command box'' on the ''channel'' given. This value is sent automatically any time a change in data is read
|-
|adcsettings
|adcs
|[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]
|Sets the settings for the ''averager'' used for the given ''Control box analog-to-digital channel''. ''Averages'' denote number of values read and averaged, ''interrupterrorthreshold'' sets the value change required for the ''Control box'' to report a new value. The ''continuouserrorthreshold'' and ''continuoustimeout'' are used to allow for ''continuous'' changes. See the ''firmware'' for more information
|-
|expressionparserevaluate
|epev
|[expression]
|Evaluates the given ''expression'' and returns the calculated value. Used for debugging
|-
|testadclatency
|tal
|[value (0 - 65535)]
|Debugging command to test ADC latency
|-
|testadclatencyreturn
|talr
|none
|Stops ADC latency testing started with ''tal''
|-
|testadcminmac
|tamm
|[channel]
|Debugging command to test the min/max value for a given ''channel''
|}
The ''local'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bow
|bow
|[bow (0)]
|Sets the ''current bow.'' This command is intended for future versions of the Ekdahl FAR that may have more than one ''bow'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|bowpid
|bpid
|<nowiki>[conditional (0|1)]</nowiki>
|Sets whether the [[wikipedia:Proportional–integral–derivative_controller|Proprtional-Integral-Deriviate controller]] is on or off. For all normal operation, the ''PID'' should be turned on. If it is turned off the instrument will not be able to play specific frequencies, but will only respond to ''bowmotordirectpwm''-commands
|-
|bowpidki
|bpki
|[float]
|Sets the ''ki''-value of the ''PID''
|-
|bowpidkp
|bpkp
|[float]
|Sets the ''kp-''value of the ''PID''
|-
|bowpidkd
|bpkd
|[float]
|Sets the ''kd''-value of the ''PID''
|-
|bowpidintegratorerror
|bpie
|[float]
|Sets the minimum ''error value'' required in between the ''set point'' and the ''process variable'' for the integrator part of the ''PID'' to initiate correction
|-
|bowpidmaxerror
|bpme
|[float]
|Sets the maximum error correction attempted in each call to the ''PID loop''
|-
|bowpidr
|bpir
|none
|Resets all data stored by the ''PID''
|-
|bowpidpeakerror
|bpperr
|none
|Returns the last ''error value'' measured in between the ''set point'' and the ''process variable''
|-
|bowcontrolfrequecy
|bcf
|[float]
|Sets the frequency (in Hertz) that the ''bowing motor'' should attempt to run at
|-
|bowcontrolfundamental
|bcu
|[float]
|Sets the ''fundamental frequency'' that all ''harmonics'' are using as its base for calculations
|-
|bowcontrolharmonic
|bch
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed''. See ''bowcontrolharmonicadd'' and ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicadd
|bcha
|[float]
|Sets the number of ''harmonic numbers'' to add or remove to the value given in ''bowcontrolharmonic'' and ''bowcontrolharmonicbase''. Can be negative values
|-
|bowcontrolharmonicbase
|bchb
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed'' but uses the value set by ''bowcontrolharmonicbasenote'' as its base. Includes any value set by ''bowcontrolharmonicadd'' and overwrites any value set by ''bowcontrolharmonic''
|-
|bowcontrolharmonicbasenote
|bchbn
|[midi key (0-127)]
|Sets the ''MIDI'' key to use as the base for ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicshift
|bchsh
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. The ''harmonic shift'' is dependent on the range set by ''bowcontrolharmonicshiftrange''. Also see ''bowcontrolharmonicshift5''
|-
|bowcontrolharmonicshiftrange
|bchsr
|[harmonics (0-36)]
|Sets the range of the ''bowcontrolharmonicshift''-command. The ''parameter'' given denotes how many ''harmonic numbers'' to shift from the current ''harmonic number'' when the maximum ''harmonic shift'' has been set.
|-
|bowcontrolharmonicshift5
|bchs5
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. Unlike ''bowcontrolharmonicshift'' this value is always calculated on a range of 5 octaves, meaning a maximum ''harmonic shift'' will equal 5 times the amount of ''harmonic ratios'' in the current ''harmonic table''. This value is added to the ''harmonic shift'' set by ''bowcontrolharmonicshift''
|-
|bowcontrolspeedmode
|bcsm
|<nowiki>[mode (0|1)]</nowiki>
|Sets the ''speed mode'' where ''0 = Automatic'' and ''1 = Manual''. The only difference in between these two modes is that ''Automatic'' will automatically turn off the motor when the bow has been set in its ''rest position'' and no frequency changing ''commands'' have been sent within the time period given by ''bowmotortimeout''
|-
|bowharmonicseries
|bhs
|[series]
|Sets the ''current harmonic series''
|-
|bowharmonicseriesdata
|bhsl
|[(set only) series]:[name]:[ratios]
|Sets all ''ratios'' and the ''name'' of the ''harmonic list'' in the given ''series''. There can be any number of ''ratio''-parameters and this effectively sets the number of ''harmonics'' per octave. If required, empty ''harmonic lists'' will be added until ''slot'' is a valid number. On return, requires [series] and returns ''name'' and ''ratios'' of the ''harmonic series'' given
|-
|bowharmonicseriesratio
|bhsr
|[harmonic]:[ratio]
|Sets the ''ratio'' of the given ''harmonic number'' in the ''current harmonic series''. Will increase the number of ratios in the series if needed
|-
|bowharmonicseriesratioremove
|bhsrr
|[ratio]
|Removes the ''ratio'' given, will move all ''ratios'' with a higher ''harmonic number'' in the series. Cannot remove all ''ratios''
|-
|bowharmonicseriescount
|bhsc
|none
|Returns the number of ''harmonic series'' and their ''names'' in the format ''ratios:name1:name2 [etc]''
|-
|bowharmonicseriessave
|bhss
|[series]:[name]
|Saves the current ''harmonic series'' into the slot given by the second ''parameter'' with the name give in the first ''parameter''. Note that this ''command'' does not save it into flash memory
|-
|bowharmonicseriesremove
|bhsrm
|[series]
|Removes the ''harmonic series'' given in the ''parameter''. Shifts all ''series''' with a higher ''series'' number
|-
|bowstatus
|bs
|none
|Outputs debugging data. Deprecated
|-
|pickupstringfrequency
|psf
|none
|Returns the fundamental frequency calculated from the current audio signal if, applicable
|-
|pickupaudiopeak
|pap
|none
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
|none
|Returns the [[wikipedia:Root_mean_square|RMS]] amplitude of the current audio signal
|-
|bowdebugmeasuretimetotarget
|bdmtt
|[frequency]
|Measure the time it takes to change from the current frequency to the target frequency, used to debug the ''PID''
|-
|bowhome
|bh
|none
|Homing bow, used at startup and in case of the bow loosing position
|-
|bowcalibrateall
|bca
|none
|Performs all calibration routines for a single bow available in the given firmware
|-
|bowcalibratespeed
|bcf
|none
|Performs a ''bowing speed calibration''
|-
|bowcalibratepressure
|bcp
|none
|Performs a ''pressure calibration''
|-
|bowmotorrun
|bmr
|<nowiki>[(0|1)]</nowiki>
|Sets the ''bow motor'' to off or on
|-
|bowmotordirectpwm
|bmdp
|[pwm (0 - 65535)]
|Sets the ''bow motor'' power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|bowmotortimeout
|bmt
|[ms (0 - 65535)]
|Sets the ''bow motor'' shutdown timeout after bow having been put into the rest position, given in milli-seconds
|-
|bowmotorspeedmax
|bmsx
|[pwm (0 - 65535)]
|Sets ''bow motor'' maximum speed in 16-bit PWM
|-
|bowmotorspeedmin
|bmsi
|[pwm (0 - 65535)]
|Sets ''bow motor'' minimum speed in 16-bit PWM
|-
|bowmotorvoltage
|bmv
|[voltage (1.2 - 9)]
|Sets the ''bow motor'' voltage
|-
|bowmotorfrequency
|bmf
|none
|Returns the last read ''bow motor frequency''
|-
|bowmotorcurrent
|bmc
|none
|Returns the last read current usage of the ''bowing motor''
|-
|bowmotorcurrentlimit
|bmcl
|[current]
|Sets the current limit of the ''bowing motor'' in ''amperes'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorpowerlimit
|bmpl
|[power]
|Sets the power limit of the ''bowing motor'' in ''watts'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorfaultcommands
|bmfc
|[command string]
|Sets the ''commands'' to execute when a motor fault is tripped, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotoroverpowercommands
|bmopc
|[command string]
|Sets the ''commands'' to execute when the ''bowing motor'' is over the power limit, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowpressurebaseline
|bpb
|[pressure (0 - 65535)]
|Sets the ''pressure baseline'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressuremodifier
|bpm
|[pressure (0 - 65535)]
|Sets the ''pressure modifier'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressurerest
|bpr
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''rest position''
|-
|bowpressureengage
|bpe
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''engage position''
|-
|bowpressurepositionmax
|bppx
|[value (0 - 65535)]
|Sets the maximum hardware position of the ''bowing jack''
|-
|bowpressurepositionengage
|bppe
|[value (0 - 65535)]
|Sets the ''engage'' ''position'' hardware position of the ''bowing jack''
|-
|bowpressurepositionrest
|bppr
|[value (0 - 65535)]
|Sets the ''rest position'' hardware position of the ''bowing jack''
|-
|bowpressureengagespeed
|bpes
|[speed (0 - 100)]
|Sets the speed of the ''pressure motor'' in RPM when going from ''rest'' to ''engage'' or vice versa. Setting this value too high will result in the ''pressure motor'' loosing track and the instrument malfunctioning as a result. Setting this value too low will result in the instrument getting increased ''latency'' and feeling sluggish.
|-
|bowpressuremodulationspeed
|bpms
|[speed (0.1 - ''bpes'')]
|Sets the speed of the ''pressure motor'' in RPM when at ''engage'' and modulating the pressure. The main purpose of this setting is to avoid the ''bowing motor'' slowing down too much when modulating the ''pressure'', resulting in audible artifacts
|-
|bowpressurehold
|bph
|<nowiki>[(0|1)]</nowiki>
|Sets ''bow hold'' off or on. If ''bow hold'' is on, any ''bowpressurerest''-command will be ignored until ''bowpressurehold'' is set to off. Analog to the concept of ''infinite sustain''
|-
|solenoid
|so
|[('0')]
|Sets the ''current solenoid''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''solenoid'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|solenoidengage
|se
|[force (0 - 65535)]
|Engages the ''current solenoid'' with the ''force'' given, the ''force'' is mutiplied by the ''force multiplier'' as set by ''solenoidforcemultiplier''. The ''force'' is scaled according to the ''solenoidmaxforce'' and ''solenoidminforce'' parameters, a ''force'' of ''0'' always means to not engage. Also see ''solenoidengageduration''
|-
|solenoiddisengage
|sd
|<nowiki>[conditional (0|1)]</nowiki>
|Disengages the ''solenoid''
|-
|solenoidmaxforce
|sxf
|[value (0 - 65535)]
|Sets the maximum hardware force used
|-
|solenoidminforce
|sif
|[value (0 - 65535)]
|Sets the minimum hardware force used
|-
|solenoidforcemultiplier
|sfm
|[value (0 - 1)]
|Sets the value of the ''force multiplier''
|-
|solenoidengageduration
|sed
|[duration (0 - 65535)]
|Sets the duration of the ''solenoid engagement'' in ɥS. if a value of ''0'' is set the ''solenoid'' will not disengage until a ''solenoiddisengage-''command has been given. This latter behavior is not encouraged as it '''can ruin the instrument if improperly used'''
|-
|mutesetposition
|msp
|[position (0 - 65535)]
|Sets the ''mute position'', scaled by the ''mutefullmuteposition'' and ''muterestposition''
|-
|mutefullmute
|mfm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''full mute position''
|-
|mutehalfmute
|mhm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''half mute position''
|-
|muterest
|mr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''mute rest position''
|-
|mutesavefull
|msf
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''full mute position'' to be equal to the current ''mute position''
|-
|mutesavehalf
|msh
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''half mute position'' to be equal to the current ''mute position''
|-
|mutesaverest
|msr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute rest position'' to be equal to the current ''mute position''
|-
|mutefullmuteposition
|mfmp
|[value (0 - 65535)]
|Sets the ''full mute position'' to ''value''
|-
|mutehalfmuteposition
|mhmp
|[value (0 - 65535)]
|Sets the ''half mute position'' to ''value''
|-
|muterestposition
|mrp
|[value (0 - 65535)]
|Sets the ''mute rest position'' to ''value''
|-
|mutesustain
|ms
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute sustain'' to ''off'' or ''on''. When ''mute sustain'' is ''on'', any ''mutefullmute-''commands sent will be ignored until ''mute sustain'' is set to ''off''
|-
|mutebackoff
|mbo
|[backoff (0 - 65535)]
|Sets the ''mute backoff'' to ''backoff'', given in mS. The ''mute backoff'' sets the time that the ''mute'' stays in the ''mutefullmute'' position before automatically going to the ''rest position''
|-
|mutehome
|mh
|none
|Homing the ''mute''
|-
|mutecalibrate
|mca
|none
|Runs the ''mute calibration''
|-
|bowactuatoradd
|baa
|none
|Add new bow ''actuator''
|-
|bowacutatorremove
|bar
|[actuator]
|Removes the ''actuator'' given in the ''parameter''
|-
|bowactuatorset
|bas
|[actuator]
|Sets the ''current actuator'' to the number given in the ''parameter''
|-
|bowactuatorload
|bal
|none
|Loads data from the ''current actuator''
|-
|bowactuatorsave
|bas
|none
|Saves the ''bow pressure position rest, bow pressure position engage'' and ''bow pressure position max'' into the ''current actuator''
|-
|bowactuatordata
|bad
|[actuator]:[engage]:[max]:[rest]:[id]
|Sets the ''bow pressure position engage, bow pressure position max, bow pressure position rest'' and ''actuator id'' of the ''actuator'' given by the first ''parameter''
|-
|bowactuatorcount
|bac
|none
|Returns the number of saved ''actuators''
|-
|bowactuatorid
|bai
|id
|Sets the ''id'' of the ''current actuator''
|-
|nooperation
|nop
|none
|Do absolutely, positively, nothing
|}
Please note that ''commands'' may be added or subtracted from this list as the Ekdahl FAR ''firmware'' development progresses, the most sincere attempts will be made to keep this list up to date but no guarantees will be made.{{docnav
|[[The Ekdahl FAR - Command langue|Command language]]
|[[The Ekdahl FAR - Specifications|Specifications]]
}}

The Ekdahl FAR - Command reference

2025-02-03T19:12:10Z

Knaadmin:

== Introduction ==
The ''commands'' in the Ekdahl FAR are using a certain ''naming convention'' to make it more clear which parts of the instrument a certain ''command'' is dealing with. Furthermore commands can be global or local, global commands change settings that will affect the entire instrument, local commands change settings depending on previously set commands. The idea of local commands is a future-proofing of the Ekdahl FAR firmware and can generally be ignored for the time being. The first part of many ''command''-names are a prefix that denotes category, the ''global'' categories as of this writing (2025-01-26) are:

* ''global*'' - commands that have a global reach
* ''midi*'' - commands that deal with ''MIDI''
* ''adc*'' - commands that deal with the ''Control box'' and its ''analog-to-digital converter''
* ''expressionparser'' - commands that deal with how ''commands'' are interpreted and parsed, mainly used for debugging
* ''test''* - commands made for testing and debugging

The ''global'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|requestinfo
|rqi
|[command]:[optional parameters]
|Uses a ''command''-name to retrieve rather than set information associated with it, some commands have no information associated and will return nothing. Some commands require the use of optional ''parameters'' to specify which information that is to be retrieved.
|-
|module
|m
|[module number (0)]
|Sets the current ''module''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''string module.'' Currently '0' is the only valid ''parameter''
|-
|modulecount
|mc
|none
|Returns the number of ''modules'' in the Ekdahl FAR. Currently always returns '1'
|-
|debugprint
|dp
|<nowiki>[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]</nowiki>
|Used to turn on or off whether the instrument will return certain information over ''USB-Serial''. The first ''parameter'' is the category, the second ''parameter'' is a boolean value.
|-
|version
|ver
|none
|Returns the current ''firmware'' version
|-
|globalsaveallparameters
|gsap
|none
|Saves all current data into the internal flash memory
|-
|globalloadallparameters
|glap
|none
|Loads all data saved into flash, effectively overwriting any changed parameters included in the last save
|-
|globalresetparameters
|grap
|none
|Resets all saved data in the flash memory, requires a immediate reset to be enacted
|-
|globaluservariable
|guv
|[variable number (0-9)]:[value (float)]
|Sets or returns the user variable defined in the first ''parameter,'' if used to set the variable, the second ''parameter'' is the value.
|-
|midiconfiguration
|mcf
|[config (0-9)]
|Sets or returns the ''current MIDI configuration''
|-
|midiconfigurationadd
|mcfa
|none
|Adds a new ''MIDI configuration''
|-
|midiconfigurationremove
|mcfr
|[config (0-9)]
|Removes the ''MIDI configuration'' denoted by the ''parameter'' passed. If there are ''MIDI configurations'' with a higher number, these are moved down the list. The ''current configuration'' may be changed during the execution of this ''command''
|-
|midiconfigurationcount
|mcfc
|none
|Returns the number of ''MIDI configurations'' available
|-
|midiconfigurationname
|mcfn
|<nowiki>[config|name]</nowiki>
|When used as a 'set'-command, the first ''parameter'' sets the name of the ''current MIDI configuration''. When used to retrieve information, the first ''parameter'' sets which ''MIDI configuration'' to return the name for
|-
|midieventhandler
|mev
|<nowiki>[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]</nowiki>
|Used to set the ''command string'' executed when a certain ''MIDI event'' occurs. The first ''parameter'' is the type of ''MIDI event.'' With exception for the ''<nowiki/>'cc' MIDI event'' the second ''parameter'' is the ''command string''. For ''<nowiki/>'cc''' the second ''parameter'' is the ''controller number'' and the third ''parameter'' is the ''command string''
|-
|midiconfigurationdefaults
|mcfd
|none
|Reverts all settings of the ''current MIDI configuration'' to default values and remove any added ''continuous controllers''
|-
|midireceivechannel
|mrc
|[channel (0-16)]
|Sets which ''MIDI channel'' the instrument will respond to. 1-16 sets the ''MIDI channel'' while all other values sets the instrument to ''<nowiki/>'Omni''' (the instrument responding to all channels)
|-
|midiallnotesoff
|mano
|<nowiki>[conditional (0|1)]</nowiki>
|Clears the entire ''MIDI'' buffer of notes held and turns off any bowing
|-
|adccommandmap
|acm
|[channel]:[command string]
|Sets the ''command string'' associated with the ''analog-to-digital converter channel'' of the ''Control box''
|-
|adcdefaults
|acd
|none
|Sets all ''command strings'' associated with all ''analog-to-digital converter channels'' to their default values
|-
|adcread
|adcr
|[channel]:[return only: value]
|Returns the last value read by the ''analog-to-digital converter'' of the ''Command box'' on the ''channel'' given. This value is sent automatically any time a change in data is read
|-
|adcsettings
|adcs
|[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]
|Sets the settings for the ''averager'' used for the given ''Control box analog-to-digital channel''. ''Averages'' denote number of values read and averaged, ''interrupterrorthreshold'' sets the value change required for the ''Control box'' to report a new value. The ''continuouserrorthreshold'' and ''continuoustimeout'' are used to allow for ''continuous'' changes. See the ''firmware'' for more information
|-
|expressionparserevaluate
|epev
|[expression]
|Evaluates the given ''expression'' and returns the calculated value. Used for debugging
|-
|testadclatency
|tal
|[value (0 - 65535)]
|Debugging command to test ADC latency
|-
|testadclatencyreturn
|talr
|none
|Stops ADC latency testing started with ''tal''
|-
|testadcminmac
|tamm
|[channel]
|Debugging command to test the min/max value for a given ''channel''
|}
The ''local'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bow
|bow
|[bow (0)]
|Sets the ''current bow.'' This command is intended for future versions of the Ekdahl FAR that may have more than one ''bow'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|bowpid
|bpid
|<nowiki>[conditional (0|1)]</nowiki>
|Sets whether the [[wikipedia:Proportional–integral–derivative_controller|Proprtional-Integral-Deriviate controller]] is on or off. For all normal operation, the ''PID'' should be turned on. If it is turned off the instrument will not be able to play specific frequencies, but will only respond to ''bowmotordirectpwm''-commands
|-
|bowpidki
|bpki
|[float]
|Sets the ''ki''-value of the ''PID''
|-
|bowpidkp
|bpkp
|[float]
|Sets the ''kp-''value of the ''PID''
|-
|bowpidkd
|bpkd
|[float]
|Sets the ''kd''-value of the ''PID''
|-
|bowpidintegratorerror
|bpie
|[float]
|Sets the minimum ''error value'' required in between the ''set point'' and the ''process variable'' for the integrator part of the ''PID'' to initiate correction
|-
|bowpidmaxerror
|bpme
|[float]
|Sets the maximum error correction attempted in each call to the ''PID loop''
|-
|bowpidr
|bpir
|none
|Resets all data stored by the ''PID''
|-
|bowpidpeakerror
|bpperr
|none
|Returns the last ''error value'' measured in between the ''set point'' and the ''process variable''
|-
|bowcontrolfrequecy
|bcf
|[float]
|Sets the frequency (in Hertz) that the ''bowing motor'' should attempt to run at
|-
|bowcontrolfundamental
|bcu
|[float]
|Sets the ''fundamental frequency'' that all ''harmonics'' are using as its base for calculations
|-
|bowcontrolharmonic
|bch
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed''. See ''bowcontrolharmonicadd'' and ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicadd
|bcha
|[float]
|Sets the number of ''harmonic numbers'' to add or remove to the value given in ''bowcontrolharmonic'' and ''bowcontrolharmonicbase''. Can be negative values
|-
|bowcontrolharmonicbase
|bchb
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed'' but uses the value set by ''bowcontrolharmonicbasenote'' as its base. Includes any value set by ''bowcontrolharmonicadd'' and overwrites any value set by ''bowcontrolharmonic''
|-
|bowcontrolharmonicbasenote
|bchbn
|[midi key (0-127)]
|Sets the ''MIDI'' key to use as the base for ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicshift
|bchsh
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. The ''harmonic shift'' is dependent on the range set by ''bowcontrolharmonicshiftrange''. Also see ''bowcontrolharmonicshift5''
|-
|bowcontrolharmonicshiftrange
|bchsr
|[harmonics (0-36)]
|Sets the range of the ''bowcontrolharmonicshift''-command. The ''parameter'' given denotes how many ''harmonic numbers'' to shift from the current ''harmonic number'' when the maximum ''harmonic shift'' has been set.
|-
|bowcontrolharmonicshift5
|bchs5
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. Unlike ''bowcontrolharmonicshift'' this value is always calculated on a range of 5 octaves, meaning a maximum ''harmonic shift'' will equal 5 times the amount of ''harmonic ratios'' in the current ''harmonic table''. This value is added to the ''harmonic shift'' set by ''bowcontrolharmonicshift''
|-
|bowcontrolspeedmode
|bcsm
|<nowiki>[mode (0|1)]</nowiki>
|Sets the ''speed mode'' where ''0 = Automatic'' and ''1 = Manual''. The only difference in between these two modes is that ''Automatic'' will automatically turn off the motor when the bow has been set in its ''rest position'' and no frequency changing ''commands'' have been sent within the time period given by ''bowmotortimeout''
|-
|bowharmonicseries
|bhs
|[series]
|Sets the ''current harmonic series''
|-
|bowharmonicseriesdata
|bhsl
|[(set only) series]:[name]:[ratios]
|Sets all ''ratios'' and the ''name'' of the ''harmonic list'' in the given ''series''. There can be any number of ''ratio''-parameters and this effectively sets the number of ''harmonics'' per octave. If required, empty ''harmonic lists'' will be added until ''slot'' is a valid number. On return, requires [series] and returns ''name'' and ''ratios'' of the ''harmonic series'' given
|-
|bowharmonicseriesratio
|bhsr
|[harmonic]:[ratio]
|Sets the ''ratio'' of the given ''harmonic number'' in the ''current harmonic series''. Will increase the number of ratios in the series if needed
|-
|bowharmonicseriesratioremove
|bhsrr
|[ratio]
|Removes the ''ratio'' given, will move all ''ratios'' with a higher ''harmonic number'' in the series. Cannot remove all ''ratios''
|-
|bowharmonicseriescount
|bhsc
|none
|Returns the number of ''harmonic series'' and their ''names'' in the format ''ratios:name1:name2 [etc]''
|-
|bowharmonicseriessave
|bhss
|[name]:[series]
|Saves the current ''harmonic series'' into the slot given by the second ''parameter'' with the name give in the first ''parameter''. Note that this ''command'' does not save it into flash memory
|-
|bowharmonicseriesremove
|bhsrm
|[series]
|Removes the ''harmonic series'' given in the ''parameter''. Shifts all ''series''' with a higher ''series'' number
|-
|bowstatus
|bs
|none
|Outputs debugging data. Deprecated
|-
|pickupstringfrequency
|psf
|none
|Returns the fundamental frequency calculated from the current audio signal if, applicable
|-
|pickupaudiopeak
|pap
|none
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
|none
|Returns the [[wikipedia:Root_mean_square|RMS]] amplitude of the current audio signal
|-
|bowdebugmeasuretimetotarget
|bdmtt
|[frequency]
|Measure the time it takes to change from the current frequency to the target frequency, used to debug the ''PID''
|-
|bowhome
|bh
|none
|Homing bow, used at startup and in case of the bow loosing position
|-
|bowcalibrateall
|bca
|none
|Performs all calibration routines for a single bow available in the given firmware
|-
|bowcalibratespeed
|bcf
|none
|Performs a ''bowing speed calibration''
|-
|bowcalibratepressure
|bcp
|none
|Performs a ''pressure calibration''
|-
|bowmotorrun
|bmr
|<nowiki>[(0|1)]</nowiki>
|Sets the ''bow motor'' to off or on
|-
|bowmotordirectpwm
|bmdp
|[pwm (0 - 65535)]
|Sets the ''bow motor'' power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|bowmotortimeout
|bmt
|[ms (0 - 65535)]
|Sets the ''bow motor'' shutdown timeout after bow having been put into the rest position, given in milli-seconds
|-
|bowmotorspeedmax
|bmsx
|[pwm (0 - 65535)]
|Sets ''bow motor'' maximum speed in 16-bit PWM
|-
|bowmotorspeedmin
|bmsi
|[pwm (0 - 65535)]
|Sets ''bow motor'' minimum speed in 16-bit PWM
|-
|bowmotorvoltage
|bmv
|[voltage (1.2 - 9)]
|Sets the ''bow motor'' voltage
|-
|bowmotorfrequency
|bmf
|none
|Returns the last read ''bow motor frequency''
|-
|bowmotorcurrent
|bmc
|none
|Returns the last read current usage of the ''bowing motor''
|-
|bowmotorcurrentlimit
|bmcl
|[current]
|Sets the current limit of the ''bowing motor'' in ''amperes'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorpowerlimit
|bmpl
|[power]
|Sets the power limit of the ''bowing motor'' in ''watts'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorfaultcommands
|bmfc
|[command string]
|Sets the ''commands'' to execute when a motor fault is tripped, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotoroverpowercommands
|bmopc
|[command string]
|Sets the ''commands'' to execute when the ''bowing motor'' is over the power limit, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowpressurebaseline
|bpb
|[pressure (0 - 65535)]
|Sets the ''pressure baseline'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressuremodifier
|bpm
|[pressure (0 - 65535)]
|Sets the ''pressure modifier'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressurerest
|bpr
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''rest position''
|-
|bowpressureengage
|bpe
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''engage position''
|-
|bowpressurepositionmax
|bppx
|[value (0 - 65535)]
|Sets the maximum hardware position of the ''bowing jack''
|-
|bowpressurepositionengage
|bppe
|[value (0 - 65535)]
|Sets the ''engage'' ''position'' hardware position of the ''bowing jack''
|-
|bowpressurepositionrest
|bppr
|[value (0 - 65535)]
|Sets the ''rest position'' hardware position of the ''bowing jack''
|-
|bowpressureengagespeed
|bpes
|[speed (0 - 100)]
|Sets the speed of the ''pressure motor'' in RPM when going from ''rest'' to ''engage'' or vice versa. Setting this value too high will result in the ''pressure motor'' loosing track and the instrument malfunctioning as a result. Setting this value too low will result in the instrument getting increased ''latency'' and feeling sluggish.
|-
|bowpressuremodulationspeed
|bpms
|[speed (0.1 - ''bpes'')]
|Sets the speed of the ''pressure motor'' in RPM when at ''engage'' and modulating the pressure. The main purpose of this setting is to avoid the ''bowing motor'' slowing down too much when modulating the ''pressure'', resulting in audible artifacts
|-
|bowpressurehold
|bph
|<nowiki>[(0|1)]</nowiki>
|Sets ''bow hold'' off or on. If ''bow hold'' is on, any ''bowpressurerest''-command will be ignored until ''bowpressurehold'' is set to off. Analog to the concept of ''infinite sustain''
|-
|solenoid
|so
|[('0')]
|Sets the ''current solenoid''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''solenoid'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|solenoidengage
|se
|[force (0 - 65535)]
|Engages the ''current solenoid'' with the ''force'' given, the ''force'' is mutiplied by the ''force multiplier'' as set by ''solenoidforcemultiplier''. The ''force'' is scaled according to the ''solenoidmaxforce'' and ''solenoidminforce'' parameters, a ''force'' of ''0'' always means to not engage. Also see ''solenoidengageduration''
|-
|solenoiddisengage
|sd
|<nowiki>[conditional (0|1)]</nowiki>
|Disengages the ''solenoid''
|-
|solenoidmaxforce
|sxf
|[value (0 - 65535)]
|Sets the maximum hardware force used
|-
|solenoidminforce
|sif
|[value (0 - 65535)]
|Sets the minimum hardware force used
|-
|solenoidforcemultiplier
|sfm
|[value (0 - 1)]
|Sets the value of the ''force multiplier''
|-
|solenoidengageduration
|sed
|[duration (0 - 65535)]
|Sets the duration of the ''solenoid engagement'' in ɥS. if a value of ''0'' is set the ''solenoid'' will not disengage until a ''solenoiddisengage-''command has been given. This latter behavior is not encouraged as it '''can ruin the instrument if improperly used'''
|-
|mutesetposition
|msp
|[position (0 - 65535)]
|Sets the ''mute position'', scaled by the ''mutefullmuteposition'' and ''muterestposition''
|-
|mutefullmute
|mfm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''full mute position''
|-
|mutehalfmute
|mhm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''half mute position''
|-
|muterest
|mr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''mute rest position''
|-
|mutesavefull
|msf
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''full mute position'' to be equal to the current ''mute position''
|-
|mutesavehalf
|msh
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''half mute position'' to be equal to the current ''mute position''
|-
|mutesaverest
|msr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute rest position'' to be equal to the current ''mute position''
|-
|mutefullmuteposition
|mfmp
|[value (0 - 65535)]
|Sets the ''full mute position'' to ''value''
|-
|mutehalfmuteposition
|mhmp
|[value (0 - 65535)]
|Sets the ''half mute position'' to ''value''
|-
|muterestposition
|mrp
|[value (0 - 65535)]
|Sets the ''mute rest position'' to ''value''
|-
|mutesustain
|ms
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute sustain'' to ''off'' or ''on''. When ''mute sustain'' is ''on'', any ''mutefullmute-''commands sent will be ignored until ''mute sustain'' is set to ''off''
|-
|mutebackoff
|mbo
|[backoff (0 - 65535)]
|Sets the ''mute backoff'' to ''backoff'', given in mS. The ''mute backoff'' sets the time that the ''mute'' stays in the ''mutefullmute'' position before automatically going to the ''rest position''
|-
|mutehome
|mh
|none
|Homing the ''mute''
|-
|mutecalibrate
|mca
|none
|Runs the ''mute calibration''
|-
|bowactuatoradd
|baa
|none
|Add new bow ''actuator''
|-
|bowacutatorremove
|bar
|[actuator]
|Removes the ''actuator'' given in the ''parameter''
|-
|bowactuatorset
|bas
|[actuator]
|Sets the ''current actuator'' to the number given in the ''parameter''
|-
|bowactuatorload
|bal
|none
|Loads data from the ''current actuator''
|-
|bowactuatorsave
|bas
|none
|Saves the ''bow pressure position rest, bow pressure position engage'' and ''bow pressure position max'' into the ''current actuator''
|-
|bowactuatordata
|bad
|[actuator]:[engage]:[max]:[rest]:[id]
|Sets the ''bow pressure position engage, bow pressure position max, bow pressure position rest'' and ''actuator id'' of the ''actuator'' given by the first ''parameter''
|-
|bowactuatorcount
|bac
|none
|Returns the number of saved ''actuators''
|-
|bowactuatorid
|bai
|id
|Sets the ''id'' of the ''current actuator''
|-
|nooperation
|nop
|none
|Do absolutely, positively, nothing
|}
Please note that ''commands'' may be added or subtracted from this list as the Ekdahl FAR ''firmware'' development progresses, the most sincere attempts will be made to keep this list up to date but no guarantees will be made.{{docnav
|[[The Ekdahl FAR - Command langue|Command language]]
|[[The Ekdahl FAR - Specifications|Specifications]]
}}

The Ekdahl FAR

2025-01-27T02:16:56Z

Knaadmin:

[[File:Ekdahl FAR - Overview.jpg|thumb|Ekdahl FAR Overview]]

== Introduction ==
The Ekdahl FAR is a string based electro-acoustic instrument whose main way of generating sound is by utilizing a [[The Ekdahl FAR - Getting started#bowing wheel|bowing wheel]] that rubs against the string and by very precisely controlling the speed of the wheel, emphasizing natural overtones in the string. The [[The Ekdahl FAR - Getting started#bowing wheel|bowing wheel]] is situated on a pivot which pushes the wheel into the string with a controllable [[The Ekdahl FAR - Getting started#pressure|pressure]] in order to affect both volume and harmonic content. To further extend the capabilities of the instrument it also has a [[The Ekdahl FAR - Hammer|hammer]], a variable [[The Ekdahl FAR - Mute|mute]] and a electromagnetic [[The Ekdahl FAR - Pickup|pickup]]. While the audio path on The Ekdahl FAR is entirely analog-acoustic, the internals of the instrument is a highly sophisticated network of sensors, motors and a built-in computer running a complex firmware allowing for precision control and interfacing via USB-MIDI, MIDI, CV and USB-Serial.

Like all Knas instruments, the Ekdahl FAR - while a new and somewhat experimental concept - can be used for any regular musical composition and expression, but also allows for deep explorations of naturally occurring overtones within the realms of digital precision control and repeatability. The instrument is designed to perform excellently whether being in an improvisational setting, or being sequenced. All aspects of The Ekdahl FAR can be mapped to respond to any available ''control mechanisms'' (USB, MIDI, CV etc.) and emphasis has been put on configurability and modification both from a software and a hardware perspective.
 
The hardware
<hr/>

[[The Ekdahl FAR - Getting started|Getting started]]

[[The Ekdahl FAR - The Control box|The Control box]]

[[The Ekdahl FAR - Basic MIDI Setup|Basic MIDI Setup]]

[[The Ekdahl FAR - Tuning|Tuning]]

[[The Ekdahl FAR - Limits|Limits]]

[[The Ekdahl FAR - Calibrations|Automatic calibrations]]

[[The Ekdahl FAR - Changing the string|Changing the string]]

[[The Ekdahl FAR - Bowing wheels|Bowing wheels and changing them]]

[[The Ekdahl FAR - Bowing jack|The bowing jack]]

[[The Ekdahl FAR - Mute|The mute]]

[[The Ekdahl FAR - Hammer|The hammer]]

[[The Ekdahl FAR - Pickup|The pickup]]

The Configuration utility
<hr/>
[[The Ekdahl FAR - Configuration utility - Concept and Installation|Concept and Installation]]

[[The Ekdahl FAR - Configuration utility - Overview|Overview]]

[[The Ekdahl FAR - Configuration utility - Tuning tab|The ''Tuning'' tab]]

[[The Ekdahl FAR - Configuration utility - Midi tab|The ''MIDI'' tab]]

[[The Ekdahl FAR - Configuration utility - CV tab|The ''CV'' tab]]

[[The Ekdahl FAR - Configuration utility - Advanced tab|The ''Advanced'' tab]]

[[The Ekdahl FAR - Configuration utility - Statistics tab|The ''Statistics'' tab]]

[[The Ekdahl FAR - Configuration utility - Software tab|The ''Software'' tab]]

Appendix
<hr/>

[[The Ekdahl FAR - Command langue|Command language]]

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

[[The Ekdahl FAR - Specifications|Specifications]]

{{Docnav
|
|[[The Ekdahl FAR - Getting started|Getting started]]
}}

The Ekdahl FAR

2025-01-27T02:15:50Z

Knaadmin:

[[File:Ekdahl FAR - Overview.jpg|thumb|Ekdahl FAR Overview]]

== Introduction ==
The Ekdahl FAR is a string based electro-acoustic instrument whose main way of generating sound is by utilizing a [[The Ekdahl FAR - Getting started#bowing wheel|bowing wheel]] that rubs against the string and by very precisely controlling the speed of the wheel, emphasizing natural overtones in the string. The [[The Ekdahl FAR - Getting started#bowing wheel|bowing wheel]] is situated on a pivot which pushes the wheel into the string with a controllable [[The Ekdahl FAR - Getting started#pressure|pressure]] in order to affect both volume and harmonic content. To further extend the capabilities of the instrument it also has a [[The Ekdahl FAR - Hammer|hammer]], a variable [[The Ekdahl FAR - Mute|mute]] and a electromagnetic [[The Ekdahl FAR - Pickup|pickup]]. While the audio path on The Ekdahl FAR is entirely analog-acoustic, the internals of the instrument is a highly sophisticated network of sensors, motors and a built-in computer running a complex firmware allowing for precision control and interfacing via USB-MIDI, MIDI, CV and USB-Serial.

Like all Knas instruments, the Ekdahl FAR - while a new and somewhat experimental concept - can be used for any regular musical composition and expression, but also allows for deep explorations of naturally occurring overtones within the realms of digital precision control and repeatability. The instrument is designed to perform excellently whether being in an improvisational setting, or being sequenced. All aspects of The Ekdahl FAR can be mapped to respond to any available ''control mechanisms'' (USB, MIDI, CV etc.) and emphasis has been put on configurability and modification both from a software and a hardware perspective.
 
<hr/>

[[The Ekdahl FAR - Getting started|Getting started]]

[[The Ekdahl FAR - The Control box|The Control box]]

[[The Ekdahl FAR - Basic MIDI Setup|Basic MIDI Setup]]

[[The Ekdahl FAR - Tuning|Tuning]]

[[The Ekdahl FAR - Limits|Limits]]

[[The Ekdahl FAR - Calibrations|Automatic calibrations]]

[[The Ekdahl FAR - Changing the string|Changing the string]]

[[The Ekdahl FAR - Bowing wheels|Bowing wheels and changing them]]

[[The Ekdahl FAR - Bowing jack|The bowing jack]]

[[The Ekdahl FAR - Mute|The mute]]

[[The Ekdahl FAR - Hammer|The hammer]]

[[The Ekdahl FAR - Pickup|The pickup]]

The Configuration utility
<hr/>
[[The Ekdahl FAR - Configuration utility - Concept and Installation|Concept and Installation]]

[[The Ekdahl FAR - Configuration utility - Overview|Overview]]

[[The Ekdahl FAR - Configuration utility - Tuning tab|The ''Tuning'' tab]]

[[The Ekdahl FAR - Configuration utility - Midi tab|The ''MIDI'' tab]]

[[The Ekdahl FAR - Configuration utility - CV tab|The ''CV'' tab]]

[[The Ekdahl FAR - Configuration utility - Advanced tab|The ''Advanced'' tab]]

[[The Ekdahl FAR - Configuration utility - Statistics tab|The ''Statistics'' tab]]

[[The Ekdahl FAR - Configuration utility - Software tab|The ''Software'' tab]]

Appendix
<hr/>

[[The Ekdahl FAR - Command langue|Command language]]

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

[[The Ekdahl FAR - Specifications|Specifications]]

{{Docnav
|
|[[The Ekdahl FAR - Getting started|Getting started]]
}}

The Ekdahl FAR - Command reference

2025-01-27T00:16:49Z

Knaadmin:

== Introduction ==
The ''commands'' in the Ekdahl FAR are using a certain ''naming convention'' to make it more clear which parts of the instrument a certain ''command'' is dealing with. Furthermore commands can be global or local, global commands change settings that will affect the entire instrument, local commands change settings depending on previously set commands. The idea of local commands is a future-proofing of the Ekdahl FAR firmware and can generally be ignored for the time being. The first part of many ''command''-names are a prefix that denotes category, the ''global'' categories as of this writing (2025-01-26) are:

* ''global*'' - commands that have a global reach
* ''midi*'' - commands that deal with ''MIDI''
* ''adc*'' - commands that deal with the ''Control box'' and its ''analog-to-digital converter''
* ''expressionparser'' - commands that deal with how ''commands'' are interpreted and parsed, mainly used for debugging
* ''test''* - commands made for testing and debugging

The ''global'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|requestinfo
|rqi
|[command]:[optional parameters]
|Uses a ''command''-name to retrieve rather than set information associated with it, some commands have no information associated and will return nothing. Some commands require the use of optional ''parameters'' to specify which information that is to be retrieved.
|-
|module
|m
|[module number (0)]
|Sets the current ''module''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''string module.'' Currently '0' is the only valid ''parameter''
|-
|modulecount
|mc
|none
|Returns the number of ''modules'' in the Ekdahl FAR. Currently always returns '1'
|-
|debugprint
|dp
|<nowiki>[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]</nowiki>
|Used to turn on or off whether the instrument will return certain information over ''USB-Serial''. The first ''parameter'' is the category, the second ''parameter'' is a boolean value.
|-
|version
|ver
|none
|Returns the current ''firmware'' version
|-
|globalsaveallparameters
|gsap
|none
|Saves all current data into the internal flash memory
|-
|globalloadallparameters
|glap
|none
|Loads all data saved into flash, effectively overwriting any changed parameters included in the last save
|-
|globalresetparameters
|grap
|none
|Resets all saved data in the flash memory, requires a immediate reset to be enacted
|-
|globaluservariable
|guv
|[variable number (0-9)]:[value (float)]
|Sets or returns the user variable defined in the first ''parameter,'' if used to set the variable, the second ''parameter'' is the value.
|-
|midiconfiguration
|mcf
|[config (0-9)]
|Sets or returns the ''current MIDI configuration''
|-
|midiconfigurationadd
|mcfa
|none
|Adds a new ''MIDI configuration''
|-
|midiconfigurationremove
|mcfr
|[config (0-9)]
|Removes the ''MIDI configuration'' denoted by the ''parameter'' passed. If there are ''MIDI configurations'' with a higher number, these are moved down the list. The ''current configuration'' may be changed during the execution of this ''command''
|-
|midiconfigurationcount
|mcfc
|none
|Returns the number of ''MIDI configurations'' available
|-
|midiconfigurationname
|mcfn
|<nowiki>[config|name]</nowiki>
|When used as a 'set'-command, the first ''parameter'' sets the name of the ''current MIDI configuration''. When used to retrieve information, the first ''parameter'' sets which ''MIDI configuration'' to return the name for
|-
|midieventhandler
|mev
|<nowiki>[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]</nowiki>
|Used to set the ''command string'' executed when a certain ''MIDI event'' occurs. The first ''parameter'' is the type of ''MIDI event.'' With exception for the ''<nowiki/>'cc' MIDI event'' the second ''parameter'' is the ''command string''. For ''<nowiki/>'cc''' the second ''parameter'' is the ''controller number'' and the third ''parameter'' is the ''command string''
|-
|midiconfigurationdefaults
|mcfd
|none
|Reverts all settings of the ''current MIDI configuration'' to default values and remove any added ''continuous controllers''
|-
|midireceivechannel
|mrc
|[channel (0-16)]
|Sets which ''MIDI channel'' the instrument will respond to. 1-16 sets the ''MIDI channel'' while all other values sets the instrument to ''<nowiki/>'Omni''' (the instrument responding to all channels)
|-
|midiallnotesoff
|mano
|<nowiki>[conditional (0|1)]</nowiki>
|Clears the entire ''MIDI'' buffer of notes held and turns off any bowing
|-
|adccommandmap
|acm
|[channel]:[command string]
|Sets the ''command string'' associated with the ''analog-to-digital converter channel'' of the ''Control box''
|-
|adcdefaults
|acd
|none
|Sets all ''command strings'' associated with all ''analog-to-digital converter channels'' to their default values
|-
|adcread
|adcr
|[channel]:[return only: value]
|Returns the last value read by the ''analog-to-digital converter'' of the ''Command box'' on the ''channel'' given. This value is sent automatically any time a change in data is read
|-
|adcsettings
|adcs
|[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]
|Sets the settings for the ''averager'' used for the given ''Control box analog-to-digital channel''. ''Averages'' denote number of values read and averaged, ''interrupterrorthreshold'' sets the value change required for the ''Control box'' to report a new value. The ''continuouserrorthreshold'' and ''continuoustimeout'' are used to allow for ''continuous'' changes. See the ''firmware'' for more information
|-
|expressionparserevaluate
|epev
|[expression]
|Evaluates the given ''expression'' and returns the calculated value. Used for debugging
|-
|testadclatency
|tal
|[value (0 - 65535)]
|Debugging command to test ADC latency
|-
|testadclatencyreturn
|talr
|none
|Stops ADC latency testing started with ''tal''
|-
|testadcminmac
|tamm
|[channel]
|Debugging command to test the min/max value for a given ''channel''
|}
The ''local'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bow
|bow
|[bow (0)]
|Sets the ''current bow.'' This command is intended for future versions of the Ekdahl FAR that may have more than one ''bow'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|bowpid
|bpid
|<nowiki>[conditional (0|1)]</nowiki>
|Sets whether the [[wikipedia:Proportional–integral–derivative_controller|Proprtional-Integral-Deriviate controller]] is on or off. For all normal operation, the ''PID'' should be turned on. If it is turned off the instrument will not be able to play specific frequencies, but will only respond to ''bowmotordirectpwm''-commands
|-
|bowpidki
|bpki
|[float]
|Sets the ''ki''-value of the ''PID''
|-
|bowpidkp
|bpkp
|[float]
|Sets the ''kp-''value of the ''PID''
|-
|bowpidkd
|bpkd
|[float]
|Sets the ''kd''-value of the ''PID''
|-
|bowpidintegratorerror
|bpie
|[float]
|Sets the minimum ''error value'' required in between the ''set point'' and the ''process variable'' for the integrator part of the ''PID'' to initiate correction
|-
|bowpidmaxerror
|bpme
|[float]
|Sets the maximum error correction attempted in each call to the ''PID loop''
|-
|bowpidr
|bpir
|none
|Resets all data stored by the ''PID''
|-
|bowpidpeakerror
|bpperr
|none
|Returns the last ''error value'' measured in between the ''set point'' and the ''process variable''
|-
|bowcontrolfrequecy
|bcf
|[float]
|Sets the frequency (in Hertz) that the ''bowing motor'' should attempt to run at
|-
|bowcontrolfundamental
|bcu
|[float]
|Sets the ''fundamental frequency'' that all ''harmonics'' are using as its base for calculations
|-
|bowcontrolharmonic
|bch
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed''. See ''bowcontrolharmonicadd'' and ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicadd
|bcha
|[float]
|Sets the number of ''harmonic numbers'' to add or remove to the value given in ''bowcontrolharmonic'' and ''bowcontrolharmonicbase''. Can be negative values
|-
|bowcontrolharmonicbase
|bchb
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed'' but uses the value set by ''bowcontrolharmonicbasenote'' as its base. Includes any value set by ''bowcontrolharmonicadd'' and overwrites any value set by ''bowcontrolharmonic''
|-
|bowcontrolharmonicbasenote
|bchbn
|[midi key (0-127)]
|Sets the ''MIDI'' key to use as the base for ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicshift
|bchsh
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. The ''harmonic shift'' is dependent on the range set by ''bowcontrolharmonicshiftrange''. Also see ''bowcontrolharmonicshift5''
|-
|bowcontrolharmonicshiftrange
|bchsr
|[harmonics (0-36)]
|Sets the range of the ''bowcontrolharmonicshift''-command. The ''parameter'' given denotes how many ''harmonic numbers'' to shift from the current ''harmonic number'' when the maximum ''harmonic shift'' has been set.
|-
|bowcontrolharmonicshift5
|bchs5
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. Unlike ''bowcontrolharmonicshift'' this value is always calculated on a range of 5 octaves, meaning a maximum ''harmonic shift'' will equal 5 times the amount of ''harmonic ratios'' in the current ''harmonic table''. This value is added to the ''harmonic shift'' set by ''bowcontrolharmonicshift''
|-
|bowcontrolspeedmode
|bcsm
|<nowiki>[mode (0|1)]</nowiki>
|Sets the ''speed mode'' where ''0 = Automatic'' and ''1 = Manual''. The only difference in between these two modes is that ''Automatic'' will automatically turn off the motor when the bow has been set in its ''rest position'' and no frequency changing ''commands'' have been sent within the time period given by ''bowmotortimeout''
|-
|bowharmonicseries
|bhs
|[series]
|Sets the ''current harmonic series''
|-
|bowharmonicserieslist
|bhsl
|[(set only) series]:[(set only) name]:[ratios]
|Sets all ''ratios'' and the ''name'' of the ''harmonic list'' in the given ''series''. There can be any number of ''ratio''-parameters and this effectively sets the number of ''harmonics'' per octave. If required, empty ''harmonic lists'' will be added until ''slot'' is a valid number. On return, only returns ''ratios'' of the ''current harmonic list'' (takes no ''parameters'')
|-
|bowharmonicseriesratio
|bhsr
|[harmonic]:[ratio]
|Sets the ''ratio'' of the given ''harmonic number'' in the ''current harmonic series''. Will increase the number of ratios in the series if needed
|-
|bowharmonicseriesratioremove
|bhsrr
|[ratio]
|Removes the ''ratio'' given, will move all ''ratios'' with a higher ''harmonic number'' in the series. Cannot remove all ''ratios''
|-
|bowharmonicseriescount
|bhsc
|none
|Returns the number of ''harmonic series'' and their ''names'' in the format ''ratios:name1:name2 [etc]''
|-
|bowharmonicseriessave
|bhss
|[name]:[series]
|Saves the current ''harmonic series'' into the slot given by the second ''parameter'' with the name give in the first ''parameter''. Note that this ''command'' does not save it into flash memory
|-
|bowharmonicseriesremove
|bhsrm
|[series]
|Removes the ''harmonic series'' given in the ''parameter''. Shifts all ''series''' with a higher ''series'' number
|-
|bowstatus
|bs
|none
|Outputs debugging data. Deprecated
|-
|pickupstringfrequency
|psf
|none
|Returns the fundamental frequency calculated from the current audio signal if, applicable
|-
|pickupaudiopeak
|pap
|none
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
|none
|Returns the [[wikipedia:Root_mean_square|RMS]] amplitude of the current audio signal
|-
|bowdebugmeasuretimetotarget
|bdmtt
|[frequency]
|Measure the time it takes to change from the current frequency to the target frequency, used to debug the ''PID''
|-
|bowhome
|bh
|none
|Homing bow, used at startup and in case of the bow loosing position
|-
|bowcalibrateall
|bca
|none
|Performs all calibration routines for a single bow available in the given firmware
|-
|bowcalibratespeed
|bcf
|none
|Performs a ''bowing speed calibration''
|-
|bowcalibratepressure
|bcp
|none
|Performs a ''pressure calibration''
|-
|bowmotorrun
|bmr
|<nowiki>[(0|1)]</nowiki>
|Sets the ''bow motor'' to off or on
|-
|bowmotordirectpwm
|bmdp
|[pwm (0 - 65535)]
|Sets the ''bow motor'' power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|bowmotortimeout
|bmt
|[ms (0 - 65535)]
|Sets the ''bow motor'' shutdown timeout after bow having been put into the rest position, given in milli-seconds
|-
|bowmotorspeedmax
|bmsx
|[pwm (0 - 65535)]
|Sets ''bow motor'' maximum speed in 16-bit PWM
|-
|bowmotorspeedmin
|bmsi
|[pwm (0 - 65535)]
|Sets ''bow motor'' minimum speed in 16-bit PWM
|-
|bowmotorvoltage
|bmv
|[voltage (1.2 - 9)]
|Sets the ''bow motor'' voltage
|-
|bowmotorfrequency
|bmf
|none
|Returns the last read ''bow motor frequency''
|-
|bowmotorcurrent
|bmc
|none
|Returns the last read current usage of the ''bowing motor''
|-
|bowmotorcurrentlimit
|bmcl
|[current]
|Sets the current limit of the ''bowing motor'' in ''amperes'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorpowerlimit
|bmpl
|[power]
|Sets the power limit of the ''bowing motor'' in ''watts'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorfaultcommands
|bmfc
|[command string]
|Sets the ''commands'' to execute when a motor fault is tripped, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotoroverpowercommands
|bmopc
|[command string]
|Sets the ''commands'' to execute when the ''bowing motor'' is over the power limit, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowpressurebaseline
|bpb
|[pressure (0 - 65535)]
|Sets the ''pressure baseline'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressuremodifier
|bpm
|[pressure (0 - 65535)]
|Sets the ''pressure modifier'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressurerest
|bpr
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''rest position''
|-
|bowpressureengage
|bpe
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''engage position''
|-
|bowpressurepositionmax
|bppx
|[value (0 - 65535)]
|Sets the maximum hardware position of the ''bowing jack''
|-
|bowpressurepositionengage
|bppe
|[value (0 - 65535)]
|Sets the ''engage'' ''position'' hardware position of the ''bowing jack''
|-
|bowpressurepositionrest
|bppr
|[value (0 - 65535)]
|Sets the ''rest position'' hardware position of the ''bowing jack''
|-
|bowpressureengagespeed
|bpes
|[speed (0 - 100)]
|Sets the speed of the ''pressure motor'' in RPM when going from ''rest'' to ''engage'' or vice versa. Setting this value too high will result in the ''pressure motor'' loosing track and the instrument malfunctioning as a result. Setting this value too low will result in the instrument getting increased ''latency'' and feeling sluggish.
|-
|bowpressuremodulationspeed
|bpms
|[speed (0.1 - ''bpes'')]
|Sets the speed of the ''pressure motor'' in RPM when at ''engage'' and modulating the pressure. The main purpose of this setting is to avoid the ''bowing motor'' slowing down too much when modulating the ''pressure'', resulting in audible artifacts
|-
|bowpressurehold
|bph
|<nowiki>[(0|1)]</nowiki>
|Sets ''bow hold'' off or on. If ''bow hold'' is on, any ''bowpressurerest''-command will be ignored until ''bowpressurehold'' is set to off. Analog to the concept of ''infinite sustain''
|-
|solenoid
|so
|[('0')]
|Sets the ''current solenoid''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''solenoid'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|solenoidengage
|se
|[force (0 - 65535)]
|Engages the ''current solenoid'' with the ''force'' given, the ''force'' is mutiplied by the ''force multiplier'' as set by ''solenoidforcemultiplier''. The ''force'' is scaled according to the ''solenoidmaxforce'' and ''solenoidminforce'' parameters, a ''force'' of ''0'' always means to not engage. Also see ''solenoidengageduration''
|-
|solenoiddisengage
|sd
|<nowiki>[conditional (0|1)]</nowiki>
|Disengages the ''solenoid''
|-
|solenoidmaxforce
|sxf
|[value (0 - 65535)]
|Sets the maximum hardware force used
|-
|solenoidminforce
|sif
|[value (0 - 65535)]
|Sets the minimum hardware force used
|-
|solenoidforcemultiplier
|sfm
|[value (0 - 1)]
|Sets the value of the ''force multiplier''
|-
|solenoidengageduration
|sed
|[duration (0 - 65535)]
|Sets the duration of the ''solenoid engagement'' in ɥS. if a value of ''0'' is set the ''solenoid'' will not disengage until a ''solenoiddisengage-''command has been given. This latter behavior is not encouraged as it '''can ruin the instrument if improperly used'''
|-
|mutesetposition
|msp
|[position (0 - 65535)]
|Sets the ''mute position'', scaled by the ''mutefullmuteposition'' and ''muterestposition''
|-
|mutefullmute
|mfm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''full mute position''
|-
|mutehalfmute
|mhm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''half mute position''
|-
|muterest
|mr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''mute rest position''
|-
|mutesavefull
|msf
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''full mute position'' to be equal to the current ''mute position''
|-
|mutesavehalf
|msh
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''half mute position'' to be equal to the current ''mute position''
|-
|mutesaverest
|msr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute rest position'' to be equal to the current ''mute position''
|-
|mutefullmuteposition
|mfmp
|[value (0 - 65535)]
|Sets the ''full mute position'' to ''value''
|-
|mutehalfmuteposition
|mhmp
|[value (0 - 65535)]
|Sets the ''half mute position'' to ''value''
|-
|muterestposition
|mrp
|[value (0 - 65535)]
|Sets the ''mute rest position'' to ''value''
|-
|mutesustain
|ms
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute sustain'' to ''off'' or ''on''. When ''mute sustain'' is ''on'', any ''mutefullmute-''commands sent will be ignored until ''mute sustain'' is set to ''off''
|-
|mutebackoff
|mbo
|[backoff (0 - 65535)]
|Sets the ''mute backoff'' to ''backoff'', given in mS. The ''mute backoff'' sets the time that the ''mute'' stays in the ''mutefullmute'' position before automatically going to the ''rest position''
|-
|mutehome
|mh
|none
|Homing the ''mute''
|-
|mutecalibrate
|mca
|none
|Runs the ''mute calibration''
|-
|bowactuatoradd
|baa
|none
|Add new bow ''actuator''
|-
|bowacutatorremove
|bar
|[actuator]
|Removes the ''actuator'' given in the ''parameter''
|-
|bowactuatorset
|bas
|[actuator]
|Sets the ''current actuator'' to the number given in the ''parameter''
|-
|bowactuatorload
|bal
|none
|Loads data from the ''current actuator''
|-
|bowactuatorsave
|bas
|none
|Saves the ''bow pressure position rest, bow pressure position engage'' and ''bow pressure position max'' into the ''current actuator''
|-
|bowactuatordata
|bad
|[actuator]:[engage]:[max]:[rest]:[id]
|Sets the ''bow pressure position engage, bow pressure position max, bow pressure position rest'' and ''actuator id'' of the ''actuator'' given by the first ''parameter''
|-
|bowactuatorcount
|bac
|none
|Returns the number of saved ''actuators''
|-
|bowactuatorid
|bai
|id
|Sets the ''id'' of the ''current actuator''
|-
|nooperation
|nop
|none
|Do absolutely, positively, nothing
|}
Please note that ''commands'' may be added or subtracted from this list as the Ekdahl FAR ''firmware'' development progresses, the most sincere attempts will be made to keep this list up to date but no guarantees will be made.{{docnav
|[[The Ekdahl FAR - Command langue|Command language]]
|[[The Ekdahl FAR - Specifications|Specifications]]
}}

The Ekdahl FAR - Command reference

2025-01-27T00:12:47Z

Knaadmin:

== Introduction ==
The ''commands'' in the Ekdahl FAR are using a certain ''naming convention'' to make it more clear which parts of the instrument a certain ''command'' is dealing with. Furthermore commands can be global or local, global commands change settings that will affect the entire instrument, local commands change settings depending on previously set commands. The idea of local commands is a future-proofing of the Ekdahl FAR firmware and can generally be ignored for the time being. The first part of many ''command''-names are a prefix that denotes category, the ''global'' categories as of this writing (2025-01-26) are:

* ''global*'' - commands that have a global reach
* ''midi*'' - commands that deal with ''MIDI''
* ''adc*'' - commands that deal with the ''Control box'' and its ''analog-to-digital converter''
* ''expressionparser'' - commands that deal with how ''commands'' are interpreted and parsed, mainly used for debugging
* ''test''* - commands made for testing and debugging

The ''global'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|requestinfo
|rqi
|[command]:[optional parameters]
|Uses a ''command''-name to retrieve rather than set information associated with it, some commands have no information associated and will return nothing. Some commands require the use of optional ''parameters'' to specify which information that is to be retrieved.
|-
|module
|m
|[module number (0)]
|Sets the current ''module''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''string module.'' Currently '0' is the only valid ''parameter''
|-
|modulecount
|mc
|none
|Returns the number of ''modules'' in the Ekdahl FAR. Currently always returns '1'
|-
|debugprint
|dp
|<nowiki>[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]</nowiki>
|Used to turn on or off whether the instrument will return certain information over ''USB-Serial''. The first ''parameter'' is the category, the second ''parameter'' is a boolean value.
|-
|version
|ver
|none
|Returns the current ''firmware'' version
|-
|globalsaveallparameters
|gsap
|none
|Saves all current data into the internal flash memory
|-
|globalloadallparameters
|glap
|none
|Loads all data saved into flash, effectively overwriting any changed parameters included in the last save
|-
|globalresetparameters
|grap
|none
|Resets all saved data in the flash memory, requires a immediate reset to be enacted
|-
|globaluservariable
|guv
|[variable number (0-9)]:[value (float)]
|Sets or returns the user variable defined in the first ''parameter,'' if used to set the variable, the second ''parameter'' is the value.
|-
|midiconfiguration
|mcf
|[config (0-9)]
|Sets or returns the ''current MIDI configuration''
|-
|midiconfigurationadd
|mcfa
|none
|Adds a new ''MIDI configuration''
|-
|midiconfigurationremove
|mcfr
|[config (0-9)]
|Removes the ''MIDI configuration'' denoted by the ''parameter'' passed. If there are ''MIDI configurations'' with a higher number, these are moved down the list. The ''current configuration'' may be changed during the execution of this ''command''
|-
|midiconfigurationcount
|mcfc
|none
|Returns the number of ''MIDI configurations'' available
|-
|midiconfigurationname
|mcfn
|<nowiki>[config|name]</nowiki>
|When used as a 'set'-command, the first ''parameter'' sets the name of the ''current MIDI configuration''. When used to retrieve information, the first ''parameter'' sets which ''MIDI configuration'' to return the name for
|-
|midieventhandler
|mev
|<nowiki>[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]</nowiki>
|Used to set the ''command string'' executed when a certain ''MIDI event'' occurs. The first ''parameter'' is the type of ''MIDI event.'' With exception for the ''<nowiki/>'cc' MIDI event'' the second ''parameter'' is the ''command string''. For ''<nowiki/>'cc''' the second ''parameter'' is the ''controller number'' and the third ''parameter'' is the ''command string''
|-
|midiconfigurationdefaults
|mcfd
|none
|Reverts all settings of the ''current MIDI configuration'' to default values and remove any added ''continuous controllers''
|-
|midireceivechannel
|mrc
|[channel (0-16)]
|Sets which ''MIDI channel'' the instrument will respond to. 1-16 sets the ''MIDI channel'' while all other values sets the instrument to ''<nowiki/>'Omni''' (the instrument responding to all channels)
|-
|midiallnotesoff
|mano
|<nowiki>[conditional (0|1)]</nowiki>
|Clears the entire ''MIDI'' buffer of notes held and turns off any bowing
|-
|adccommandmap
|acm
|[channel]:[command string]
|Sets the ''command string'' associated with the ''analog-to-digital converter channel'' of the ''Control box''
|-
|adcdefaults
|acd
|none
|Sets all ''command strings'' associated with all ''analog-to-digital converter channels'' to their default values
|-
|adcread
|adcr
|[channel]:[return only: value]
|Returns the last value read by the ''analog-to-digital converter'' of the ''Command box'' on the ''channel'' given. This value is sent automatically any time a change in data is read
|-
|adcsettings
|adcs
|[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]
|Sets the settings for the ''averager'' used for the given ''Control box analog-to-digital channel''. ''Averages'' denote number of values read and averaged, ''interrupterrorthreshold'' sets the value change required for the ''Control box'' to report a new value. The ''continuouserrorthreshold'' and ''continuoustimeout'' are used to allow for ''continuous'' changes. See the ''firmware'' for more information
|-
|expressionparserevaluate
|epev
|[expression]
|Evaluates the given ''expression'' and returns the calculated value. Used for debugging
|-
|testadclatency
|tal
|[value (0 - 65535)]
|Debugging command to test ADC latency
|-
|testadclatencyreturn
|talr
|none
|Stops ADC latency testing started with ''tal''
|-
|testadcminmac
|tamm
|[channel]
|Debugging command to test the min/max value for a given ''channel''
|}
The ''local'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bow
|bow
|[bow (0)]
|Sets the ''current bow.'' This command is intended for future versions of the Ekdahl FAR that may have more than one ''bow'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|bowpid
|bpid
|<nowiki>[conditional (0|1)]</nowiki>
|Sets whether the [[wikipedia:Proportional–integral–derivative_controller|Proprtional-Integral-Deriviate controller]] is on or off. For all normal operation, the ''PID'' should be turned on. If it is turned off the instrument will not be able to play specific frequencies, but will only respond to ''bowmotordirectpwm''-commands
|-
|bowpidki
|bpki
|[float]
|Sets the ''ki''-value of the ''PID''
|-
|bowpidkp
|bpkp
|[float]
|Sets the ''kp-''value of the ''PID''
|-
|bowpidkd
|bpkd
|[float]
|Sets the ''kd''-value of the ''PID''
|-
|bowpidintegratorerror
|bpie
|[float]
|Sets the minimum ''error value'' required in between the ''set point'' and the ''process variable'' for the integrator part of the ''PID'' to initiate correction
|-
|bowpidmaxerror
|bpme
|[float]
|Sets the maximum error correction attempted in each call to the ''PID loop''
|-
|bowpidr
|bpir
|none
|Resets all data stored by the ''PID''
|-
|bowpidpeakerror
|bpperr
|none
|Returns the last ''error value'' measured in between the ''set point'' and the ''process variable''
|-
|bowcontrolfrequecy
|bcf
|[float]
|Sets the frequency (in Hertz) that the ''bowing motor'' should attempt to run at
|-
|bowcontrolfundamental
|bcu
|[float]
|Sets the ''fundamental frequency'' that all ''harmonics'' are using as its base for calculations
|-
|bowcontrolharmonic
|bch
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed''. See ''bowcontrolharmonicadd'' and ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicadd
|bcha
|[float]
|Sets the number of ''harmonic numbers'' to add or remove to the value given in ''bowcontrolharmonic'' and ''bowcontrolharmonicbase''. Can be negative values
|-
|bowcontrolharmonicbase
|bchb
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed'' but uses the value set by ''bowcontrolharmonicbasenote'' as its base. Includes any value set by ''bowcontrolharmonicadd'' and overwrites any value set by ''bowcontrolharmonic''
|-
|bowcontrolharmonicbasenote
|bchbn
|[midi key (0-127)]
|Sets the ''MIDI'' key to use as the base for ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicshift
|bchsh
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. The ''harmonic shift'' is dependent on the range set by ''bowcontrolharmonicshiftrange''. Also see ''bowcontrolharmonicshift5''
|-
|bowcontrolharmonicshiftrange
|bchsr
|[harmonics (0-36)]
|Sets the range of the ''bowcontrolharmonicshift''-command. The ''parameter'' given denotes how many ''harmonic numbers'' to shift from the current ''harmonic number'' when the maximum ''harmonic shift'' has been set.
|-
|bowcontrolharmonicshift5
|bchs5
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. Unlike ''bowcontrolharmonicshift'' this value is always calculated on a range of 5 octaves, meaning a maximum ''harmonic shift'' will equal 5 times the amount of ''harmonic ratios'' in the current ''harmonic table''. This value is added to the ''harmonic shift'' set by ''bowcontrolharmonicshift''
|-
|bowcontrolspeedmode
|bcsm
|<nowiki>[mode (0|1)]</nowiki>
|Sets the ''speed mode'' where ''0 = Automatic'' and ''1 = Manual''. The only difference in between these two modes is that ''Automatic'' will automatically turn off the motor when the bow has been set in its ''rest position'' and no frequency changing ''commands'' have been sent within the time period given by ''bowmotortimeout''
|-
|bowharmonicseries
|bhs
|[series]
|Sets the ''current harmonic series''
|-
|bowharmonicserieslist
|bhsl
|[(set only) series]:[(set only) name]:[ratios]
|Sets all ''ratios'' and the ''name'' of the ''harmonic list'' in the given ''series''. There can be any number of ''ratio''-parameters and this effectively sets the number of ''harmonics'' per octave. If required, empty ''harmonic lists'' will be added until ''slot'' is a valid number. On return, only returns ''ratios'' of the ''current harmonic list'' (takes no ''parameters'')
|-
|bowharmonicseriesratio
|bhsr
|[harmonic]:[ratio]
|Sets the ''ratio'' of the given ''harmonic number'' in the ''current harmonic series''. Will increase the number of ratios in the series if needed
|-
|bowharmonicseriesratioremove
|bhsrr
|[ratio]
|Removes the ''ratio'' given, will move all ''ratios'' with a higher ''harmonic number'' in the series. Cannot remove all ''ratios''
|-
|bowharmonicseriescount
|bhsc
|none
|Returns the number of ''harmonic series'' and their ''names'' in the format ''ratios:name1:name2 [etc]''
|-
|bowharmonicseriessave
|bhss
|[name]:[series]
|Saves the current ''harmonic series'' into the slot given by the second ''parameter'' with the name give in the first ''parameter''. Note that this ''command'' does not save it into flash memory
|-
|bowharmonicseriesremove
|bhsrm
|[series]
|Removes the ''harmonic series'' given in the ''parameter''. Shifts all ''series''' with a higher ''series'' number
|-
|bowstatus
|bs
|none
|Outputs debugging data. Deprecated
|-
|pickupstringfrequency
|psf
|none
|Returns the fundamental frequency calculated from the current audio signal if, applicable
|-
|pickupaudiopeak
|pap
|none
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
|none
|Returns the [[wikipedia:Root_mean_square|RMS]] amplitude of the current audio signal
|-
|bowdebugmeasuretimetotarget
|bdmtt
|[frequency]
|Measure the time it takes to change from the current frequency to the target frequency, used to debug the ''PID''
|-
|bowhome
|bh
|none
|Homing bow, used at startup and in case of the bow loosing position
|-
|bowcalibrateall
|bca
|none
|Performs all calibration routines for a single bow available in the given firmware
|-
|bowcalibratespeed
|bcf
|none
|Performs a ''bowing speed calibration''
|-
|bowcalibratepressure
|bcp
|none
|Performs a ''pressure calibration''
|-
|bowmotorrun
|bmr
|<nowiki>[(0|1)]</nowiki>
|Sets the ''bow motor'' to off or on
|-
|bowmotordirectpwm
|bmdp
|[pwm (0 - 65535)]
|Sets the ''bow motor'' power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|bowmotortimeout
|bmt
|[ms (0 - 65535)]
|Sets the ''bow motor'' shutdown timeout after bow having been put into the rest position, given in milli-seconds
|-
|bowmotorspeedmax
|bmsx
|[pwm (0 - 65535)]
|Sets ''bow motor'' maximum speed in 16-bit PWM
|-
|bowmotorspeedmin
|bmsi
|[pwm (0 - 65535)]
|Sets ''bow motor'' minimum speed in 16-bit PWM
|-
|bowmotorvoltage
|bmv
|[voltage (1.2 - 9)]
|Sets the ''bow motor'' voltage
|-
|bowmotorfrequency
|bmf
|none
|Returns the last read ''bow motor frequency''
|-
|bowmotorcurrent
|bmc
|none
|Returns the last read current usage of the ''bowing motor''
|-
|bowmotorcurrentlimit
|bmcl
|[current]
|Sets the current limit of the ''bowing motor'' in ''amperes'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorpowerlimit
|bmpl
|[power]
|Sets the power limit of the ''bowing motor'' in ''watts'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorfaultcommands
|bmfc
|[command string]
|Sets the ''commands'' to execute when a motor fault is tripped, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotoroverpowercommands
|bmopc
|[command string]
|Sets the ''commands'' to execute when the ''bowing motor'' is over the power limit, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowpressurebaseline
|bpb
|[pressure (0 - 65535)]
|Sets the ''pressure baseline'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressuremodifier
|bpm
|[pressure (0 - 65535)]
|Sets the ''pressure modifier'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressurerest
|bpr
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''rest position''
|-
|bowpressureengage
|bpe
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''engage position''
|-
|bowpressurepositionmax
|bppx
|[value (0 - 65535)]
|Sets the maximum hardware position of the ''bowing jack''
|-
|bowpressurepositionengage
|bppe
|[value (0 - 65535)]
|Sets the ''engage'' ''position'' hardware position of the ''bowing jack''
|-
|bowpressurepositionrest
|bppr
|[value (0 - 65535)]
|Sets the ''rest position'' hardware position of the ''bowing jack''
|-
|bowpressureengagespeed
|bpes
|[speed (0 - 100)]
|Sets the speed of the ''pressure motor'' in RPM when going from ''rest'' to ''engage'' or vice versa. Setting this value too high will result in the ''pressure motor'' loosing track and the instrument malfunctioning as a result. Setting this value too low will result in the instrument getting increased ''latency'' and feeling sluggish.
|-
|bowpressuremodulationspeed
|bpms
|[speed (0.1 - ''bpes'')]
|Sets the speed of the ''pressure motor'' in RPM when at ''engage'' and modulating the pressure. The main purpose of this setting is to avoid the ''bowing motor'' slowing down too much when modulating the ''pressure'', resulting in audible artifacts
|-
|bowpressurehold
|bph
|<nowiki>[(0|1)]</nowiki>
|Sets ''bow hold'' off or on. If ''bow hold'' is on, any ''bowpressurerest''-command will be ignored until ''bowpressurehold'' is set to off. Analog to the concept of ''infinite sustain''
|-
|solenoid
|so
|[('0')]
|Sets the ''current solenoid''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''solenoid'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|solenoidengage
|se
|[force (0 - 65535)]
|Engages the ''current solenoid'' with the ''force'' given, the ''force'' is mutiplied by the ''force multiplier'' as set by ''solenoidforcemultiplier''. The ''force'' is scaled according to the ''solenoidmaxforce'' and ''solenoidminforce'' parameters, a ''force'' of ''0'' always means to not engage. Also see ''solenoidengageduration''
|-
|solenoiddisengage
|sd
|<nowiki>[conditional (0|1)]</nowiki>
|Disengages the ''solenoid''
|-
|solenoidmaxforce
|sxf
|[value (0 - 65535)]
|Sets the maximum hardware force used
|-
|solenoidminforce
|sif
|[value (0 - 65535)]
|Sets the minimum hardware force used
|-
|solenoidforcemultiplier
|sfm
|[value (0 - 1)]
|Sets the value of the ''force multiplier''
|-
|solenoidengageduration
|sed
|[duration (0 - 65535)]
|Sets the duration of the ''solenoid engagement'' in ɥS. if a value of ''0'' is set the ''solenoid'' will not disengage until a ''solenoiddisengage-''command has been given. This latter behavior is not encouraged as it '''can ruin the instrument if improperly used'''
|-
|mutesetposition
|msp
|[position (0 - 65535)]
|Sets the ''mute position'', scaled by the ''mutefullmuteposition'' and ''muterestposition''
|-
|mutefullmute
|mfm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''full mute position''
|-
|mutehalfmute
|mhm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''half mute position''
|-
|muterest
|mr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''mute rest position''
|-
|mutesavefull
|msf
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''full mute position'' to be equal to the current ''mute position''
|-
|mutesavehalf
|msh
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''half mute position'' to be equal to the current ''mute position''
|-
|mutesaverest
|msr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute rest position'' to be equal to the current ''mute position''
|-
|mutefullmuteposition
|mfmp
|[value (0 - 65535)]
|Sets the ''full mute position'' to ''value''
|-
|mutehalfmuteposition
|mhmp
|[value (0 - 65535)]
|Sets the ''half mute position'' to ''value''
|-
|muterestposition
|mrp
|[value (0 - 65535)]
|Sets the ''mute rest position'' to ''value''
|-
|mutesustain
|ms
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute sustain'' to ''off'' or ''on''. When ''mute sustain'' is ''on'', any ''mutefullmute-''commands sent will be ignored until ''mute sustain'' is set to ''off''
|-
|mutebackoff
|mbo
|[backoff (0 - 65535)]
|Sets the ''mute backoff'' to ''backoff'', given in mS. The ''mute backoff'' sets the time that the ''mute'' stays in the ''mutefullmute'' position before automatically going to the ''rest position''
|-
|mutehome
|mh
|none
|Homing the ''mute''
|-
|mutecalibrate
|mca
|none
|Runs the ''mute calibration''
|-
|bowactuatoradd
|baa
|none
|Add new bow ''actuator''
|-
|bowacutatorremove
|bar
|[actuator]
|Removes the ''actuator'' given in the ''parameter''
|-
|bowactuatorset
|bas
|[actuator]
|Sets the ''current actuator'' to the number given in the ''parameter''
|-
|bowactuatorload
|bal
|none
|Loads data from the ''current actuator''
|-
|bowactuatorsave
|bas
|none
|Saves the ''bow pressure position rest, bow pressure position engage'' and ''bow pressure position max'' into the ''current actuator''
|-
|bowactuatordata
|bad
|[actuator]:[engage]:[max]:[rest]:[id]
|Sets the ''bow pressure position engage, bow pressure position max, bow pressure position rest'' and ''actuator id'' of the ''actuator'' given by the first ''parameter''
|-
|bowactuatorcount
|bac
|none
|Returns the number of saved ''actuators''
|-
|bowactuatorid
|bai
|id
|Sets the ''id'' of the ''current actuator''
|-
|nooperation
|nop
|none
|Do absolutely, positively, nothing
|}
a{{docnav
|[[The Ekdahl FAR - Command langue|Command language]]
|[[The Ekdahl FAR - Specifications|Specifications]]
}}

The Ekdahl FAR - Command reference

2025-01-27T00:06:30Z

Knaadmin:

== Introduction ==
The ''commands'' in the Ekdahl FAR are using a certain ''naming convention'' to make it more clear which parts of the instrument a certain ''command'' is dealing with. Furthermore commands can be global or local, global commands change settings that will affect the entire instrument, local commands change settings depending on previously set commands. The idea of local commands is a future-proofing of the Ekdahl FAR firmware and can generally be ignored for the time being. The first part of many ''command''-names are a prefix that denotes category, the ''global'' categories as of this writing (2025-01-26) are:

* ''global*'' - commands that have a global reach
* ''midi*'' - commands that deal with ''MIDI''
* ''adc*'' - commands that deal with the ''Control box'' and its ''analog-to-digital converter''
* ''expressionparser'' - commands that deal with how ''commands'' are interpreted and parsed, mainly used for debugging
* ''test''* - commands made for testing and debugging

The ''global'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|requestinfo
|rqi
|[command]:[optional parameters]
|Uses a ''command''-name to retrieve rather than set information associated with it, some commands have no information associated and will return nothing. Some commands require the use of optional ''parameters'' to specify which information that is to be retrieved.
|-
|module
|m
|[module number (0)]
|Sets the current ''module''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''string module.'' Currently '0' is the only valid ''parameter''
|-
|modulecount
|mc
|none
|Returns the number of ''modules'' in the Ekdahl FAR. Currently always returns '1'
|-
|debugprint
|dp
|<nowiki>[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]</nowiki>
|Used to turn on or off whether the instrument will return certain information over ''USB-Serial''. The first ''parameter'' is the category, the second ''parameter'' is a boolean value.
|-
|version
|ver
|none
|Returns the current ''firmware'' version
|-
|globalsaveallparameters
|gsap
|none
|Saves all current data into the internal flash memory
|-
|globalloadallparameters
|glap
|none
|Loads all data saved into flash, effectively overwriting any changed parameters included in the last save
|-
|globalresetparameters
|grap
|none
|Resets all saved data in the flash memory, requires a immediate reset to be enacted
|-
|globaluservariable
|guv
|[variable number (0-9)]:[value (float)]
|Sets or returns the user variable defined in the first ''parameter,'' if used to set the variable, the second ''parameter'' is the value.
|-
|midiconfiguration
|mcf
|[config (0-9)]
|Sets or returns the ''current MIDI configuration''
|-
|midiconfigurationadd
|mcfa
|none
|Adds a new ''MIDI configuration''
|-
|midiconfigurationremove
|mcfr
|[config (0-9)]
|Removes the ''MIDI configuration'' denoted by the ''parameter'' passed. If there are ''MIDI configurations'' with a higher number, these are moved down the list. The ''current configuration'' may be changed during the execution of this ''command''
|-
|midiconfigurationcount
|mcfc
|none
|Returns the number of ''MIDI configurations'' available
|-
|midiconfigurationname
|mcfn
|<nowiki>[config|name]</nowiki>
|When used as a 'set'-command, the first ''parameter'' sets the name of the ''current MIDI configuration''. When used to retrieve information, the first ''parameter'' sets which ''MIDI configuration'' to return the name for
|-
|midieventhandler
|mev
|<nowiki>[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]</nowiki>
|Used to set the ''command string'' executed when a certain ''MIDI event'' occurs. The first ''parameter'' is the type of ''MIDI event.'' With exception for the ''<nowiki/>'cc' MIDI event'' the second ''parameter'' is the ''command string''. For ''<nowiki/>'cc''' the second ''parameter'' is the ''controller number'' and the third ''parameter'' is the ''command string''
|-
|midiconfigurationdefaults
|mcfd
|none
|Reverts all settings of the ''current MIDI configuration'' to default values and remove any added ''continuous controllers''
|-
|midireceivechannel
|mrc
|[channel (0-16)]
|Sets which ''MIDI channel'' the instrument will respond to. 1-16 sets the ''MIDI channel'' while all other values sets the instrument to ''<nowiki/>'Omni''' (the instrument responding to all channels)
|-
|midiallnotesoff
|mano
|<nowiki>[conditional (0|1)]</nowiki>
|Clears the entire ''MIDI'' buffer of notes held and turns off any bowing
|-
|adccommandmap
|acm
|[channel]:[command string]
|Sets the ''command string'' associated with the ''analog-to-digital converter channel'' of the ''Control box''
|-
|adcdefaults
|acd
|none
|Sets all ''command strings'' associated with all ''analog-to-digital converter channels'' to their default values
|-
|adcread
|adcr
|[channel]:[return only: value]
|Returns the last value read by the ''analog-to-digital converter'' of the ''Command box'' on the ''channel'' given. This value is sent automatically any time a change in data is read
|-
|adcsettings
|adcs
|[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]
|Sets the settings for the ''averager'' used for the given ''Control box analog-to-digital channel''. ''Averages'' denote number of values read and averaged, ''interrupterrorthreshold'' sets the value change required for the ''Control box'' to report a new value. The ''continuouserrorthreshold'' and ''continuoustimeout'' are used to allow for ''continuous'' changes. See the ''firmware'' for more information
|-
|expressionparserevaluate
|epev
|[expression]
|Evaluates the given ''expression'' and returns the calculated value. Used for debugging
|-
|testadclatency
|tal
|[value (0 - 65535)]
|Debugging command to test ADC latency
|-
|testadclatencyreturn
|talr
|none
|Stops ADC latency testing started with ''tal''
|-
|testadcminmac
|tamm
|[channel]
|Debugging command to test the min/max value for a given ''channel''
|}
The ''local'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bow
|bow
|[bow (0)]
|Sets the ''current bow.'' This command is intended for future versions of the Ekdahl FAR that may have more than one ''bow'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|bowpid
|bpid
|<nowiki>[conditional (0|1)]</nowiki>
|Sets whether the [[wikipedia:Proportional–integral–derivative_controller|Proprtional-Integral-Deriviate controller]] is on or off. For all normal operation, the ''PID'' should be turned on. If it is turned off the instrument will not be able to play specific frequencies, but will only respond to ''bowmotordirectpwm''-commands
|-
|bowpidki
|bpki
|[float]
|Sets the ''ki''-value of the ''PID''
|-
|bowpidkp
|bpkp
|[float]
|Sets the ''kp-''value of the ''PID''
|-
|bowpidkd
|bpkd
|[float]
|Sets the ''kd''-value of the ''PID''
|-
|bowpidintegratorerror
|bpie
|[float]
|Sets the minimum ''error value'' required in between the ''set point'' and the ''process variable'' for the integrator part of the ''PID'' to initiate correction
|-
|bowpidmaxerror
|bpme
|[float]
|Sets the maximum error correction attempted in each call to the ''PID loop''
|-
|bowpidr
|bpir
|none
|Resets all data stored by the ''PID''
|-
|bowpidpeakerror
|bpperr
|none
|Returns the last ''error value'' measured in between the ''set point'' and the ''process variable''
|-
|bowcontrolfrequecy
|bcf
|[float]
|Sets the frequency (in Hertz) that the ''bowing motor'' should attempt to run at
|-
|bowcontrolfundamental
|bcu
|[float]
|Sets the ''fundamental frequency'' that all ''harmonics'' are using as its base for calculations
|-
|bowcontrolharmonic
|bch
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed''. See ''bowcontrolharmonicadd'' and ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicadd
|bcha
|[float]
|Sets the number of ''harmonic numbers'' to add or remove to the value given in ''bowcontrolharmonic'' and ''bowcontrolharmonicbase''. Can be negative values
|-
|bowcontrolharmonicbase
|bchb
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed'' but uses the value set by ''bowcontrolharmonicbasenote'' as its base. Includes any value set by ''bowcontrolharmonicadd'' and overwrites any value set by ''bowcontrolharmonic''
|-
|bowcontrolharmonicbasenote
|bchbn
|[midi key (0-127)]
|Sets the ''MIDI'' key to use as the base for ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicshift
|bchsh
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. The ''harmonic shift'' is dependent on the range set by ''bowcontrolharmonicshiftrange''. Also see ''bowcontrolharmonicshift5''
|-
|bowcontrolharmonicshiftrange
|bchsr
|[harmonics (0-36)]
|Sets the range of the ''bowcontrolharmonicshift''-command. The ''parameter'' given denotes how many ''harmonic numbers'' to shift from the current ''harmonic number'' when the maximum ''harmonic shift'' has been set.
|-
|bowcontrolharmonicshift5
|bchs5
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. Unlike ''bowcontrolharmonicshift'' this value is always calculated on a range of 5 octaves, meaning a maximum ''harmonic shift'' will equal 5 times the amount of ''harmonic ratios'' in the current ''harmonic table''. This value is added to the ''harmonic shift'' set by ''bowcontrolharmonicshift''
|-
|bowcontrolspeedmode
|bcsm
|<nowiki>[mode (0|1)]</nowiki>
|Sets the ''speed mode'' where ''0 = Automatic'' and ''1 = Manual''. The only difference in between these two modes is that ''Automatic'' will automatically turn off the motor when the bow has been set in its ''rest position'' and no frequency changing ''commands'' have been sent within the time period given by ''bowmotortimeout''
|-
|bowharmonicseries
|bhs
|[series]
|Sets the ''current harmonic series''
|-
|bowharmonicserieslist
|bhsl
|[(set only) series]:[(set only) name]:[ratios]
|Sets all ''ratios'' and the ''name'' of the ''harmonic list'' in the given ''series''. There can be any number of ''ratio''-parameters and this effectively sets the number of ''harmonics'' per octave. If required, empty ''harmonic lists'' will be added until ''slot'' is a valid number. On return, only returns ''ratios'' of the ''current harmonic list'' (takes no ''parameters'')
|-
|bowharmonicseriesratio
|bhsr
|[harmonic]:[ratio]
|Sets the ''ratio'' of the given ''harmonic number'' in the ''current harmonic series''. Will increase the number of ratios in the series if needed
|-
|bowharmonicseriesratioremove
|bhsrr
|[ratio]
|Removes the ''ratio'' given, will move all ''ratios'' with a higher ''harmonic number'' in the series. Cannot remove all ''ratios''
|-
|bowharmonicseriescount
|bhsc
|none
|Returns the number of ''harmonic series'' and their ''names'' in the format ''ratios:name1:name2 [etc]''
|-
|bowharmonicseriessave
|bhss
|[name]:[series]
|Saves the current ''harmonic series'' into the slot given by the second ''parameter'' with the name give in the first ''parameter''. Note that this ''command'' does not save it into flash memory
|-
|bowharmonicseriesremove
|bhsrm
|[series]
|Removes the ''harmonic series'' given in the ''parameter''. Shifts all ''series''' with a higher ''series'' number
|-
|bowstatus
|bs
|none
|Outputs debugging data. Deprecated
|-
|pickupstringfrequency
|psf
|none
|Returns the fundamental frequency calculated from the current audio signal if, applicable
|-
|pickupaudiopeak
|pap
|none
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
|none
|Returns the [[wikipedia:Root_mean_square|RMS]] amplitude of the current audio signal
|-
|bowdebugmeasuretimetotarget
|bdmtt
|[frequency]
|Measure the time it takes to change from the current frequency to the target frequency, used to debug the ''PID''
|-
|bowhome
|bh
|none
|Homing bow, used at startup and in case of the bow loosing position
|-
|bowcalibrateall
|bca
|none
|Performs all calibration routines for a single bow available in the given firmware
|-
|bowcalibratespeed
|bcf
|none
|Performs a ''bowing speed calibration''
|-
|bowcalibratepressure
|bcp
|none
|Performs a ''pressure calibration''
|-
|bowmotorrun
|bmr
|<nowiki>[(0|1)]</nowiki>
|Sets the ''bow motor'' to off or on
|-
|bowmotordirectpwm
|bmdp
|[pwm (0 - 65535)]
|Sets the ''bow motor'' power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|bowmotortimeout
|bmt
|[ms (0 - 65535)]
|Sets the ''bow motor'' shutdown timeout after bow having been put into the rest position, given in milli-seconds
|-
|bowmotorspeedmax
|bmsx
|[pwm (0 - 65535)]
|Sets ''bow motor'' maximum speed in 16-bit PWM
|-
|bowmotorspeedmin
|bmsi
|[pwm (0 - 65535)]
|Sets ''bow motor'' minimum speed in 16-bit PWM
|-
|bowmotorvoltage
|bmv
|[voltage (1.2 - 9)]
|Sets the ''bow motor'' voltage
|-
|bowmotorfrequency
|bmf
|none
|Returns the last read ''bow motor frequency''
|-
|bowmotorcurrent
|bmc
|none
|Returns the last read current usage of the ''bowing motor''
|-
|bowmotorcurrentlimit
|bmcl
|[current]
|Sets the current limit of the ''bowing motor'' in ''amperes'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorpowerlimit
|bmpl
|[power]
|Sets the power limit of the ''bowing motor'' in ''watts'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorfaultcommands
|bmfc
|[command string]
|Sets the ''commands'' to execute when a motor fault is tripped, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotoroverpowercommands
|bmopc
|[command string]
|Sets the ''commands'' to execute when the ''bowing motor'' is over the power limit, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowpressurebaseline
|bpb
|[pressure (0 - 65535)]
|Sets the ''pressure baseline'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressuremodifier
|bpm
|[pressure (0 - 65535)]
|Sets the ''pressure modifier'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressurerest
|bpr
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''rest position''
|-
|bowpressureengage
|bpe
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''engage position''
|-
|bowpressurepositionmax
|bppx
|[value (0 - 65535)]
|Sets the maximum hardware position of the ''bowing jack''
|-
|bowpressurepositionengage
|bppe
|[value (0 - 65535)]
|Sets the ''engage'' ''position'' hardware position of the ''bowing jack''
|-
|bowpressurepositionrest
|bppr
|[value (0 - 65535)]
|Sets the ''rest position'' hardware position of the ''bowing jack''
|-
|bowpressureengagespeed
|bpes
|[speed (0 - 100)]
|Sets the speed of the ''pressure motor'' in RPM when going from ''rest'' to ''engage'' or vice versa. Setting this value too high will result in the ''pressure motor'' loosing track and the instrument malfunctioning as a result. Setting this value too low will result in the instrument getting increased ''latency'' and feeling sluggish.
|-
|bowpressuremodulationspeed
|bpms
|[speed (0.1 - ''bpes'')]
|Sets the speed of the ''pressure motor'' in RPM when at ''engage'' and modulating the pressure. The main purpose of this setting is to avoid the ''bowing motor'' slowing down too much when modulating the ''pressure'', resulting in audible artifacts
|-
|bowpressurehold
|bph
|<nowiki>[(0|1)]</nowiki>
|Sets ''bow hold'' off or on. If ''bow hold'' is on, any ''bowpressurerest''-command will be ignored until ''bowpressurehold'' is set to off. Analog to the concept of ''infinite sustain''
|-
|solenoid
|so
|[('0')]
|Sets the ''current solenoid''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''solenoid'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|solenoidengage
|se
|[force (0 - 65535)]
|Engages the ''current solenoid'' with the ''force'' given, the ''force'' is mutiplied by the ''force multiplier'' as set by ''solenoidforcemultiplier''. The ''force'' is scaled according to the ''solenoidmaxforce'' and ''solenoidminforce'' parameters, a ''force'' of ''0'' always means to not engage. Also see ''solenoidengageduration''
|-
|solenoiddisengage
|sd
|<nowiki>[conditional (0|1)]</nowiki>
|Disengages the ''solenoid''
|-
|solenoidmaxforce
|sxf
|[value (0 - 65535)]
|Sets the maximum hardware force used
|-
|solenoidminforce
|sif
|[value (0 - 65535)]
|Sets the minimum hardware force used
|-
|solenoidforcemultiplier
|sfm
|[value (0 - 1)]
|Sets the value of the ''force multiplier''
|-
|solenoidengageduration
|sed
|[duration (0 - 65535)]
|Sets the duration of the ''solenoid engagement'' in ɥS. if a value of ''0'' is set the ''solenoid'' will not disengage until a ''solenoiddisengage-''command has been given. This latter behavior is not encouraged as it '''can ruin the instrument if improperly used'''
|-
|mutesetposition
|msp
|[position (0 - 65535)]
|Sets the ''mute position'', scaled by the ''mutefullmuteposition'' and ''muterestposition''
|-
|mutefullmute
|mfm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''full mute position''
|-
|mutehalfmute
|mhm
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''half mute position''
|-
|muterest
|mr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute'' in the ''mute rest position''
|-
|mutesavefull
|msf
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''full mute position'' to be equal to the current ''mute position''
|-
|mutesavehalf
|msh
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''half mute position'' to be equal to the current ''mute position''
|-
|mutesaverest
|msr
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute rest position'' to be equal to the current ''mute position''
|-
|mutefullmuteposition
|mfmp
|[value (0 - 65535)]
|Sets the ''full mute position'' to ''value''
|-
|mutehalfmuteposition
|mhmp
|[value (0 - 65535)]
|Sets the ''half mute position'' to ''value''
|-
|muterestposition
|mrp
|[value (0 - 65535)]
|Sets the ''mute rest position'' to ''value''
|-
|mutesustain
|ms
|<nowiki>[conditional (0|1)]</nowiki>
|Sets the ''mute sustain'' to ''off'' or ''on''. When ''mute sustain'' is ''on'', any ''mutefullmute-''commands sent will be ignored until ''mute sustain'' is set to ''off''
|-
|mutebackoff
|mbo
|[backoff (0 - 65535)]
|Sets the ''mute backoff'' to ''backoff'', given in mS. The ''mute backoff'' sets the time that the ''mute'' stays in the ''mutefullmute'' position before automatically going to the ''rest position''
|-
|mutehome
|mh
|none
|Homing the ''mute''
|-
|mutecalibrate
|mca
|none
|Runs the ''mute calibration''
|-
|bowactuatoradd
|baa
|none
|Add new bow ''actuator''
|-
|bowacutatorremove
|bar
|[actuator]
|Removes the ''actuator'' given in the ''parameter''
|-
|bowactuatorset
|bas
|[actuator]
|Sets the ''current actuator'' to the number given in the ''parameter''
|-
|bowactuatorload
|bal
|none
|Loads data from the ''current actuator''
|-
|bowactuatorsave
|bas
|none
|Saves the ''bow pressure position rest, bow pressure position engage'' and ''bow pressure position max'' into the ''current actuator''
|-
|bowactuatordata
|bad
|[actuator]:[engage]:[max]:[rest]:[name]
|Sets the ''bow pressure position engage, bow pressure position max, bow pressure position rest'' and ''actuator name'' of the ''actuator'' given by the first ''parameter''
|-
|bowactuatorcount
|bac
|none
|Returns the number of saved ''actuators''
|-
|s
|
|
|
|}
a{{docnav
|[[The Ekdahl FAR - Command langue|Command language]]
|[[The Ekdahl FAR - Specifications|Specifications]]
}}

The Ekdahl FAR - Command reference

2025-01-26T22:50:18Z

Knaadmin:

== Introduction ==
The ''commands'' in the Ekdahl FAR are using a certain ''naming convention'' to make it more clear which parts of the instrument a certain ''command'' is dealing with. Furthermore commands can be global or local, global commands change settings that will affect the entire instrument, local commands change settings depending on previously set commands. The idea of local commands is a future-proofing of the Ekdahl FAR firmware and can generally be ignored for the time being. The first part of many ''command''-names are a prefix that denotes category, the ''global'' categories as of this writing (2025-01-26) are:

* ''global*'' - commands that have a global reach
* ''midi*'' - commands that deal with ''MIDI''
* ''adc*'' - commands that deal with the ''Control box'' and its ''analog-to-digital converter''
* ''expressionparser'' - commands that deal with how ''commands'' are interpreted and parsed, mainly used for debugging
* ''test''* - commands made for testing and debugging

The ''global'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|requestinfo
|rqi
|[command]:[optional parameters]
|Uses a ''command''-name to retrieve rather than set information associated with it, some commands have no information associated and will return nothing. Some commands require the use of optional ''parameters'' to specify which information that is to be retrieved.
|-
|module
|m
|[module number (0)]
|Sets the current ''module''. This command is intended for future versions of the Ekdahl FAR that may have more than one ''string module.'' Currently '0' is the only valid ''parameter''
|-
|modulecount
|mc
|none
|Returns the number of ''modules'' in the Ekdahl FAR. Currently always returns '1'
|-
|debugprint
|dp
|<nowiki>[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]</nowiki>
|Used to turn on or off whether the instrument will return certain information over ''USB-Serial''. The first ''parameter'' is the category, the second ''parameter'' is a boolean value.
|-
|version
|ver
|none
|Returns the current ''firmware'' version
|-
|globalsaveallparameters
|gsap
|none
|Saves all current data into the internal flash memory
|-
|globalloadallparameters
|glap
|none
|Loads all data saved into flash, effectively overwriting any changed parameters included in the last save
|-
|globalresetparameters
|grap
|none
|Resets all saved data in the flash memory, requires a immediate reset to be enacted
|-
|globaluservariable
|guv
|[variable number (0-9)]:[value (float)]
|Sets or returns the user variable defined in the first ''parameter,'' if used to set the variable, the second ''parameter'' is the value.
|-
|midiconfiguration
|mcf
|[config (0-9)]
|Sets or returns the ''current MIDI configuration''
|-
|midiconfigurationadd
|mcfa
|none
|Adds a new ''MIDI configuration''
|-
|midiconfigurationremove
|mcfr
|[config (0-9)]
|Removes the ''MIDI configuration'' denoted by the ''parameter'' passed. If there are ''MIDI configurations'' with a higher number, these are moved down the list. The ''current configuration'' may be changed during the execution of this ''command''
|-
|midiconfigurationcount
|mcfc
|none
|Returns the number of ''MIDI configurations'' available
|-
|midiconfigurationname
|mcfn
|<nowiki>[config|name]</nowiki>
|When used as a 'set'-command, the first ''parameter'' sets the name of the ''current MIDI configuration''. When used to retrieve information, the first ''parameter'' sets which ''MIDI configuration'' to return the name for
|-
|midieventhandler
|mev
|<nowiki>[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]</nowiki>
|Used to set the ''command string'' executed when a certain ''MIDI event'' occurs. The first ''parameter'' is the type of ''MIDI event.'' With exception for the ''<nowiki/>'cc' MIDI event'' the second ''parameter'' is the ''command string''. For ''<nowiki/>'cc''' the second ''parameter'' is the ''controller number'' and the third ''parameter'' is the ''command string''
|-
|midiconfigurationdefaults
|mcfd
|none
|Reverts all settings of the ''current MIDI configuration'' to default values and remove any added ''continuous controllers''
|-
|midireceivechannel
|mrc
|[channel (0-16)]
|Sets which ''MIDI channel'' the instrument will respond to. 1-16 sets the ''MIDI channel'' while all other values sets the instrument to ''<nowiki/>'Omni''' (the instrument responding to all channels)
|-
|midiallnotesoff
|mano
|<nowiki>[conditional (0|1)]</nowiki>
|Clears the entire ''MIDI'' buffer of notes held and turns off any bowing
|-
|adccommandmap
|acm
|[channel]:[command string]
|Sets the ''command string'' associated with the ''analog-to-digital converter channel'' of the ''Control box''
|-
|adcdefaults
|acd
|none
|Sets all ''command strings'' associated with all ''analog-to-digital converter channels'' to their default values
|-
|adcread
|adcr
|[channel]:[return only: value]
|Returns the last value read by the ''analog-to-digital converter'' of the ''Command box'' on the ''channel'' given. This value is sent automatically any time a change in data is read
|-
|adcsettings
|adcs
|[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]
|Sets the settings for the ''averager'' used for the given ''Control box analog-to-digital channel''. ''Averages'' denote number of values read and averaged, ''interrupterrorthreshold'' sets the value change required for the ''Control box'' to report a new value. The ''continuouserrorthreshold'' and ''continuoustimeout'' are used to allow for ''continuous'' changes. See the ''firmware'' for more information
|-
|expressionparserevaluate
|epev
|[expression]
|Evaluates the given ''expression'' and returns the calculated value. Used for debugging
|-
|testadclatency
|tal
|[value (0 - 65535)]
|Debugging command to test ADC latency
|-
|testadclatencyreturn
|talr
|none
|Stops ADC latency testing started with ''tal''
|-
|testadcminmac
|tamm
|[channel]
|Debugging command to test the min/max value for a given ''channel''
|}
The ''local'' commands as of this writing (2025-01-26) are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|bow
|bow
|[bow (0)]
|Sets the ''current bow.'' This command is intended for future versions of the Ekdahl FAR that may have more than one ''bow'' per ''string module.'' Currently '0' is the only valid ''parameter''
|-
|bowpid
|bpid
|<nowiki>[conditional (0|1)]</nowiki>
|Sets whether the [[wikipedia:Proportional–integral–derivative_controller|Proprtional-Integral-Deriviate controller]] is on or off. For all normal operation, the ''PID'' should be turned on. If it is turned off the instrument will not be able to play specific frequencies, but will only respond to ''bowmotordirectpwm''-commands
|-
|bowpidki
|bpki
|[float]
|Sets the ''ki''-value of the ''PID''
|-
|bowpidkp
|bpkp
|[float]
|Sets the ''kp-''value of the ''PID''
|-
|bowpidkd
|bpkd
|[float]
|Sets the ''kd''-value of the ''PID''
|-
|bowpidintegratorerror
|bpie
|[float]
|Sets the minimum ''error value'' required in between the ''set point'' and the ''process variable'' for the integrator part of the ''PID'' to initiate correction
|-
|bowpidmaxerror
|bpme
|[float]
|Sets the maximum error correction attempted in each call to the ''PID loop''
|-
|bowpidr
|bpir
|none
|Resets all data stored by the ''PID''
|-
|bowpidpeakerror
|bpperr
|none
|Returns the last ''error value'' measured in between the ''set point'' and the ''process variable''
|-
|bowcontrolfrequecy
|bcf
|[float]
|Sets the frequency (in Hertz) that the ''bowing motor'' should attempt to run at
|-
|bowcontrolfundamental
|bcu
|[float]
|Sets the ''fundamental frequency'' that all ''harmonics'' are using as its base for calculations
|-
|bowcontrolharmonic
|bch
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed''. See ''bowcontrolharmonicadd'' and ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicadd
|bcha
|[float]
|Sets the number of ''harmonic numbers'' to add or remove to the value given in ''bowcontrolharmonic'' and ''bowcontrolharmonicbase''. Can be negative values
|-
|bowcontrolharmonicbase
|bchb
|[float]
|Sets the ''harmonic number'' to use to calculate the ''motor speed'' but uses the value set by ''bowcontrolharmonicbasenote'' as its base. Includes any value set by ''bowcontrolharmonicadd'' and overwrites any value set by ''bowcontrolharmonic''
|-
|bowcontrolharmonicbasenote
|bchbn
|[midi key (0-127)]
|Sets the ''MIDI'' key to use as the base for ''bowcontrolharmonicbase''
|-
|bowcontrolharmonicshift
|bchsh
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. The ''harmonic shift'' is dependent on the range set by ''bowcontrolharmonicshiftrange''. Also see ''bowcontrolharmonicshift5''
|-
|bowcontrolharmonicshiftrange
|bchsr
|[harmonics (0-36)]
|Sets the range of the ''bowcontrolharmonicshift''-command. The ''parameter'' given denotes how many ''harmonic numbers'' to shift from the current ''harmonic number'' when the maximum ''harmonic shift'' has been set.
|-
|bowcontrolharmonicshift5
|bchs5
|[value (-32767 - 32767)]
|Sets how much to shift the ''motor speed'' away from the ''harmonic number'' set by ''bowcontrolharmonic'' or ''bowcontrolharmonicbase''. Unlike ''bowcontrolharmonicshift'' this value is always calculated on a range of 5 octaves, meaning a maximum ''harmonic shift'' will equal 5 times the amount of ''harmonic ratios'' in the current ''harmonic table''. This value is added to the ''harmonic shift'' set by ''bowcontrolharmonicshift''
|-
|bowcontrolspeedmode
|bcsm
|<nowiki>[mode (0|1)]</nowiki>
|Sets the ''speed mode'' where ''0 = Automatic'' and ''1 = Manual''. The only difference in between these two modes is that ''Automatic'' will automatically turn off the motor when the bow has been set in its ''rest position'' and no frequency changing ''commands'' have been sent within the time period given by ''bowmotortimeout''
|-
|bowharmonicseries
|bhs
|[series]
|Sets the ''current harmonic series''
|-
|bowharmonicserieslist
|bhsl
|[(set only) series]:[(set only) name]:[ratios]
|Sets all ''ratios'' and the ''name'' of the ''harmonic list'' in the given ''series''. There can be any number of ''ratio''-parameters and this effectively sets the number of ''harmonics'' per octave. If required, empty ''harmonic lists'' will be added until ''slot'' is a valid number. On return, only returns ''ratios'' of the ''current harmonic list'' (takes no ''parameters'')
|-
|bowharmonicseriesratio
|bhsr
|[harmonic]:[ratio]
|Sets the ''ratio'' of the given ''harmonic number'' in the ''current harmonic series''. Will increase the number of ratios in the series if needed
|-
|bowharmonicseriesratioremove
|bhsrr
|[ratio]
|Removes the ''ratio'' given, will move all ''ratios'' with a higher ''harmonic number'' in the series. Cannot remove all ''ratios''
|-
|bowharmonicseriescount
|bhsc
|none
|Returns the number of ''harmonic series'' and their ''names'' in the format ''ratios:name1:name2 [etc]''
|-
|bowharmonicseriessave
|bhss
|[name]:[series]
|Saves the current ''harmonic series'' into the slot given by the second ''parameter'' with the name give in the first ''parameter''. Note that this ''command'' does not save it into flash memory
|-
|bowharmonicseriesremove
|bhsrm
|[series]
|Removes the ''harmonic series'' given in the ''parameter''. Shifts all ''series''' with a higher ''series'' number
|-
|bowstatus
|bs
|none
|Outputs debugging data. Deprecated
|-
|pickupstringfrequency
|psf
|none
|Returns the fundamental frequency calculated from the current audio signal if, applicable
|-
|pickupaudiopeak
|pap
|none
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
|none
|Returns the [[wikipedia:Root_mean_square|RMS]] amplitude of the current audio signal
|-
|bowdebugmeasuretimetotarget
|bdmtt
|[frequency]
|Measure the time it takes to change from the current frequency to the target frequency, used to debug the ''PID''
|-
|bowhome
|bh
|none
|Homing bow, used at startup and in case of the bow loosing position
|-
|bowcalibrateall
|bca
|none
|Performs all calibration routines for a single bow available in the given firmware
|-
|bowcalibratespeed
|bcf
|none
|Performs a ''bowing speed calibration''
|-
|bowcalibratepressure
|bcp
|none
|Performs a ''pressure calibration''
|-
|bowmotorrun
|bmr
|<nowiki>[(0|1)]</nowiki>
|Sets the ''bow motor'' to off or on
|-
|bowmotordirectpwm
|bmdp
|[pwm (0 - 65535)]
|Sets the ''bow motor'' power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|bowmotortimeout
|bmt
|[ms (0 - 65535)]
|Sets the ''bow motor'' shutdown timeout after bow having been put into the rest position, given in milli-seconds
|-
|bowmotorspeedmax
|bmsx
|[pwm (0 - 65535)]
|Sets ''bow motor'' maximum speed in 16-bit PWM
|-
|bowmotorspeedmin
|bmsi
|[pwm (0 - 65535)]
|Sets ''bow motor'' minimum speed in 16-bit PWM
|-
|bowmotorvoltage
|bmv
|[voltage (1.2 - 9)]
|Sets the ''bow motor'' voltage
|-
|bowmotorfrequency
|bmf
|none
|Returns the last read ''bow motor frequency''
|-
|bowmotorcurrent
|bmc
|none
|Returns the last read current usage of the ''bowing motor''
|-
|bowmotorcurrentlimit
|bmcl
|[current]
|Sets the current limit of the ''bowing motor'' in ''amperes'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorpowerlimit
|bmpl
|[power]
|Sets the power limit of the ''bowing motor'' in ''watts'', used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotorfaultcommands
|bmfc
|[command string]
|Sets the ''commands'' to execute when a motor fault is tripped, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowmotoroverpowercommands
|bmopc
|[command string]
|Sets the ''commands'' to execute when the ''bowing motor'' is over the power limit, used to safeguard the motor, '''can ruin the instrument if improperly set'''
|-
|bowpressurebaseline
|bpb
|[pressure (0 - 65535)]
|Sets the ''pressure baseline'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressuremodifier
|bpm
|[pressure (0 - 65535)]
|Sets the ''pressure modifier'' value, scaled by the ''bowpressurepositionengage'' and ''bowpressurepositionmax'' parameters. The ''pressure baseline'' and ''pressure modifier'' forms the total ''pressure position''.
|-
|bowpressurerest
|bpr
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''rest position''
|-
|bowpressureengage
|bpe
|<nowiki>[conditional (0|1)]</nowiki>
|Puts the bow pressure in the ''engage position''
|-
|bowpressurepositionmax
|bppx
|[value (0 - 65535)]
|Sets the maximum hardware position of the ''bowing jack''
|-
|bowpressurepositionengage
|bppe
|[value (0 - 65535)]
|Sets the ''engage'' ''position'' hardware position of the ''bowing jack''
|-
|bowpressurepositionrest
|bppr
|[value (0 - 65535)]
|Sets the ''rest position'' hardware position of the ''bowing jack''
|-
|bowpressureengagespeed
|bpes
|[speed (0 - 100)]
|Sets the speed of the ''pressure motor'' in RPM when going from ''rest'' to ''engage'' or vice versa. Setting this value too high will result in the ''pressure motor'' loosing track and the instrument malfunctioning as a result. Setting this value too low will result in the instrument getting increased ''latency'' and feeling sluggish.
|-
|bowpressuremodulationspeed
|bpms
|[speed (0.1 - ''bpes'')]
|Sets the speed of the ''pressure motor'' in RPM when at ''engage'' and modulating the pressure. The main purpose of this setting is to avoid the ''bowing motor'' slowing down too much when modulating the ''pressure'', resulting in audible artifacts
|-
|sad
|
|
|
|}
a{{docnav
|[[The Ekdahl FAR - Command langue|Command language]]
|[[The Ekdahl FAR - Specifications|Specifications]]
}}

The Ekdahl FAR - Command reference

2025-01-26T21:38:42Z

Knaadmin:

The Ekdahl FAR - Command reference

2025-01-26T21:16:39Z

Knaadmin:

The Ekdahl FAR - Command reference

2025-01-26T20:07:30Z

Knaadmin:

The Ekdahl FAR - Command reference

2025-01-26T19:42:59Z

Knaadmin:

The Ekdahl FAR - Command reference

2025-01-26T19:03:49Z

Knaadmin:

The Ekdahl FAR - Command reference

2025-01-26T17:57:09Z

Knaadmin:

The Ekdahl FAR - Configuration utility - Concept and Installation

2025-01-26T17:09:29Z

Knaadmin:

== The concept of the Configuration Utility ==
[[File:The Configuration utility.png|thumb|The Configuration utility]]
The ''configuration utility'' is a software that will connect to the Ekdahl FAR and reconfigure its internal parameters. It's important to realize that the ''configuration utility'' itself does not have any features that aren't already built in to the Ekdahl FAR, but rather it is just an interface for easily controlling its built-in parameters and commands. The reason that this needs to be pointed out is because everything that can be done with the ''configuration utility'' can be done either by manually sending the Ekdahl FAR various commands or invoking them through MIDI or CV mapping. For instance, in order to change the fundamental tuning of the Ekdahl FAR you don't '''have''' to use the ''configuration utility'', but you could map a slider on a MIDI Controller to send the appropriate commands. This means that a custom interface for the Ekdahl FAR, whether hardware or software, can be made and configured very quickly and easily. When settings are saved in the ''configuration utility'', these are saved into the instrument itself, thus the next time the Ekdahl FAR is powered on the same settings will be recalled whether it is connected to a computer or not.

== Software design choices ==
The ''configuration utility'' is not considered a primary part of the Ekdahl FAR since it isn't strictly needed, but being able to easily change parameters in the instrument is clearly beneficial. The software is ''open source'' and has been written with portability in mind, having a single software that can run on multiple different systems (Linux, MacOS, Windows etc.) is key both in terms of user access and due to the fact that Knas has no possibility of maintaining several different software variations for different systems. Since even maintaining a single software can be challenging for a single individual, and because capitalism is the greatest of evils, the choice was made to make the software ''open source'' so anyone with the skills required can help make it better. For these reasons the software is written in Python using QT as the graphical interface, this means that any system wanting to run the software has to be able to install these frameworks of the appropriate versions.

== Installation ==
The ''configuration utility'' is currently considered to be in beta development stage (2025-01-20) and will be so until Knas has gotten enough satisfiable user feedback. For this reason no binary releases of the software has yet to be made and the user will have to invoke the install scripts appropriate for their system manually.

The first step in the installation process is to download the software from its GitHub page 
https://github.com/Knaster/EkdahlFarConfig

On the page there's a green button with the caption "code", pressing this will reveal a drop-down menu with the option "Download ZIP" at the bottom. Download and extract the .ZIP file into any directory.

== Dependencies ==

All systems will need to have Python v3.10 or later and Qt6 / PySide6 installed, some of the below scripts will try to attempt to find out if these are installed and may launch an installer if not. It is recommended that these be installed before attempting to install the ''Configuration utility'' however.

https://www.python.org/

https://www.qt.io/download-qt-installer-oss

Furthermore the following python packages are required
<pre>
pyside6, pyserial, mido, python-rtmidi, sympy, pyqt6-charts
</pre>

== Installing on Linux ==
Open a Terminal in the folder where you extracted the .zip file to and install Python

<syntaxhighlight lang="bash">
sudo apt update
apt install python
</syntaxhighlight>
Make sure that apt is installing Python version 3.10 or later.

It is suggested that the dependencies are installed in a specific python environment
<syntaxhighlight lang="bash">
python3 -m venv ./venv
./venv/bin/pip3 install pyside6 pyserial mido python-rtmidi sympy pyqt6-charts
</syntaxhighlight>
To run
<syntaxhighlight lang="bash">
./run_linux.sh
</syntaxhighlight>

== Installing on Windows ==
{{mbox|text=Windows 11 will by default block the running of the setup file, in order to unblock it left-click on 'setup_win.bat' in the directory where the files have been extracted, then right-click on it and choose 'properties'. On the bottom right check the 'unblock' box and press OK. }}

Right-click on 'setup_win.bat' and choose 'run as administrator' and click 'yes'.

If Python is not installed, this will launch the Python installer and exit and you have to run it again

The batch script will first install all python depencies and then it will copy the program files to
'C:\Program Files\Ekdahl FAR Configuration Utility' and create an icon in the start menu.

== Installing on MacOS ==

{{mbox|text=As of this writing (2025-01-20) the software has only been successfully installed on MacOS Ventura (13) and Sequoia (15)}} 
{{mbox|text=MacOS 12 requires XCode to be installed, the latest version that works on MacOS 12 is XCode 14.2 which can be downloaded from https://archive.org/details/xcode-14.2. By downloading this, extracting it and dragging it into the Applications folder, the Configuration utility has been successfully installed. If the installer still complains you may have to start a terminal, go to the folder where the Configuration utility has been downloaded and run
<syntaxhighlight lang="bash"> sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
./setup_mac.command</syntaxhighlight>
}}

 
{{mbox|text=MacOS Sequoia (15) will give you the warning "'setup_mac.command' was not opened" and some crap about malware. This is due to apples forever gatekeeping against independent and not-for-profit software development. To circumvent this, if you have tried to run the file once you can go to the apple menu at the top left and choose "system settings", here scroll down to "privacy & security" and it will say "'setup_mac.command' was blocked to protect your mac' - press "Open Anyway" to continue the installation }}
 
run 'setup_mac.command' from finder

The script will install Handbrake (if not present) which in turn will install Python 3.10 or later and the required python dependencies.
It will also copy the program files to '/Applications/Ekdahl FAR Configuration Utility' and create a launcher icon

{{docnav
|[[The Ekdahl FAR - Hammer|The hammer]]
|[[The Ekdahl FAR - Configuration utility - Overview|Configuration utility - Overview]]
}}

The Ekdahl FAR - Configuration utility - Concept and Installation

2025-01-26T17:06:55Z

Knaadmin:

== The concept of the Configuration Utility ==
[[File:The Configuration utility.png|thumb|The Configuration utility]]
The ''configuration utility'' is a software that will connect to the Ekdahl FAR and reconfigure its internal parameters. It's important to realize that the ''configuration utility'' itself does not have any features that aren't already built in to the Ekdahl FAR, but rather it is just an interface for easily controlling its built-in parameters and commands. The reason that this needs to be pointed out is because everything that can be done with the ''configuration utility'' can be done either by manually sending the Ekdahl FAR various commands or invoking them through MIDI or CV mapping. For instance, in order to change the fundamental tuning of the Ekdahl FAR you don't '''have''' to use the ''configuration utility'', but you could map a slider on a MIDI Controller to send the appropriate commands. This means that a custom interface for the Ekdahl FAR, whether hardware or software, can be made and configured very quickly and easily. When settings are saved in the ''configuration utility'', these are saved into the instrument itself, thus the next time the Ekdahl FAR is powered on the same settings will be recalled whether it is connected to a computer or not.

== Software design choices ==
The ''configuration utility'' is not considered a primary part of the Ekdahl FAR since it isn't strictly needed, but being able to easily change parameters in the instrument is clearly beneficial. The software is ''open source'' and has been written with portability in mind, having a single software that can run on multiple different systems (Linux, MacOS, Windows etc.) is key both in terms of user access and due to the fact that Knas has no possibility of maintaining several different software variations for different systems. Since even maintaining a single software can be challenging for a single individual, and because capitalism is the greatest of evils, the choice was made to make the software ''open source'' so anyone with the skills required can help make it better. For these reasons the software is written in Python using QT as the graphical interface, this means that any system wanting to run the software has to be able to install these frameworks of the appropriate versions.

== Installation ==
The ''configuration utility'' is currently considered to be in beta development stage (2025-01-20) and will be so until Knas has gotten enough satisfiable user feedback. For this reason no binary releases of the software has yet to be made and the user will have to invoke the install scripts appropriate for their system manually.

The first step in the installation process is to download the software from its GitHub page 
https://github.com/Knaster/EkdahlFarConfig

On the page there's a green button with the caption "code", pressing this will reveal a drop-down menu with the option "Download ZIP" at the bottom. Download and extract the .ZIP file into any directory.

== Dependencies ==

All systems will need to have Python v3.10 or later and Qt6 / PySide6 installed, some of the below scripts will try to attempt to find out if these are installed and may launch an installer if not. It is recommended that these be installed before attempting to install the ''Configuration utility'' however.

https://www.python.org/

https://www.qt.io/download-qt-installer-oss

Furthermore the following python packages are required
<pre>
pyside6, pyserial, mido, python-rtmidi, sympy, pyqt6-charts
</pre>

== Installing on Linux ==
Open a Terminal in the folder where you extracted the .zip file to and install Python

<syntaxhighlight lang="bash">
sudo apt update
apt install python
</syntaxhighlight>
Make sure that apt is installing Python version 3.10 or later.

It is suggested that the dependencies are installed in a specific python environment
<syntaxhighlight lang="bash">
python3 -m venv ./venv
./venv/bin/pip3 install pyside6 pyserial mido python-rtmidi sympy pyqt6-charts
</syntaxhighlight>
To run
<syntaxhighlight lang="bash">
./run_linux.sh
</syntaxhighlight>

== Installing on Windows ==
{{mbox|text=Windows 11 will by default block the running of the setup file, in order to unblock it left-click on 'setup_win.bat' in the directory where the files have been extracted, then right-click on it and choose 'properties'. On the bottom right check the 'unblock' box and press OK. }}

Right-click on 'setup_win.bat' and choose 'run as administrator' and click 'yes'.

If Python is not installed, this will launch the Python installer and exit and you have to run it again

The batch script will first install all python depencies and then it will copy the program files to
'C:\Program Files\Ekdahl FAR Configuration Utility' and create an icon in the start menu.

== Installing on MacOS ==

{{mbox|text=As of this writing (2025-01-20) the software has only been successfully installed on MacOS Ventura (13) and Sequoia (15)}} 
{{mbox|text=MacOS 12 requires XCode to be installed, the latest version that works on MacOS 12 is XCode 14.2 which can be downloaded from the Internet Archive. By downloading this, extracting it and draggin it into the Applications folder, the Configuration utility has been successfully installed. If the installer still complains you may have to start a terminal, go to the folder where the Configuration utility has been downloaded and run
<syntaxhighlight lang="bash">
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
./setup_mac.command
</syntaxhighlight>
}}
 
{{mbox|text=MacOS Sequoia (15) will give you the warning "'setup_mac.command' was not opened" and some crap about malware. This is due to apples forever gatekeeping against independent and not-for-profit software development. To circumvent this, if you have tried to run the file once you can go to the apple menu at the top left and choose "system settings", here scroll down to "privacy & security" and it will say "'setup_mac.command' was blocked to protect your mac' - press "Open Anyway" to continue the installation }}
 
run 'setup_mac.command' from finder

The script will install Handbrake (if not present) which in turn will install Python 3.10 or later and the required python dependencies.
It will also copy the program files to '/Applications/Ekdahl FAR Configuration Utility' and create a launcher icon

{{docnav
|[[The Ekdahl FAR - Hammer|The hammer]]
|[[The Ekdahl FAR - Configuration utility - Overview|Configuration utility - Overview]]
}}

MediaWiki:Sidebar

2025-01-25T01:56:21Z

Knaadmin:

* navigation
** https://www.knasmusic.com|Knas website
** https://www.knasmusic.com/forum|Forum
* The Ekdahl FAR
** The Ekdahl FAR|- Introduction
** The_Ekdahl_FAR_-_Getting_started|- Getting started
** The Ekdahl FAR - The Control box|- The Control box
** The Ekdahl FAR - Basic MIDI Setup|- Basic MIDI Setup
** The Ekdahl FAR - Tuning|- Tuning
** The Ekdahl FAR - Limits|- Limits
** The Ekdahl FAR - Calibrations|- Calibrations
** The Ekdahl FAR - Changing the string|- Changing the string
** The Ekdahl FAR - Bowing wheels|- Bowing wheels
** The Ekdahl FAR - Bowing jack|- The bowing jack
** The Ekdahl FAR - Mute|- The mute
** The Ekdahl FAR - Hammer|- The hammer
** The Ekdahl FAR - Pickup|- The pickup
** The Ekdahl FAR - Configuration utility - Concept and Installation|Configuration utility
** The Ekdahl FAR - Configuration utility - Overview|- Overview
** The Ekdahl FAR - Configuration utility - Tuning tab|- The Tuning tab
** The Ekdahl FAR - Configuration utility - Midi tab|- The MIDI tab
** The Ekdahl FAR - Configuration utility - CV tab|- The CV tab
** The Ekdahl FAR - Configuration utility - Advanced tab|- The Advanced tab
** The Ekdahl FAR - Configuration utility - Statistics tab|- The Statistics tab
** The Ekdahl FAR - Configuration utility - Software tab|- The Software tab
** The Ekdahl FAR - Command langue|Command language
** The Ekdahl FAR - Command reference|Command reference
** The Ekdahl FAR - Specifications|Specifications
* SEARCH
* TOOLBOX
* LANGUAGES

The Ekdahl FAR - Pickup

2025-01-24T23:58:14Z

Knaadmin:

== The Pickup ==
[[File:Pickup.png|thumb|Pickup details]]
The ''pickup'' in the Ekdahl FAR is an ''[[wikipedia:Pickup_(music_technology)#Active_and_passive_pickups|active electromagnetic pickup]]'', it works on the principle of a steel object (the string in this case) inducing a signal into a coil (the ''pickup''). For this reason the Ekdahl FAR will only work with strings that are made of steel and other [[wikipedia:Ferromagnetism|ferromagnetic]] materials.

All ''electromagnetic pickups'' are sensitive to [[wikipedia:Electromagnetic_interference|electromagnetic interference]], the Ekdahl FAR tries to minimize this issue by incorporating a ''shield'' that blocks out [[wikipedia:Electromagnetic_interference|EMI]] and directing sound pickup straight upwards. The ''pickup housing'' also contains an ''active amplifier''.

In order to minimize noise, the pickup needs to be as close to the string as possible without touching it when struck with the ''hammer'' or starting to resonate.

To move the the pickup use a 3mm [[wikipedia:Hex_key|hex key]] to loosen the ''pickup screw'', this can be done even when the case is on. The ''pickup housing'' may stick a little bit to the holding plate, you can press lightly with your thumb to loosen it up. If you don't remove the [[wikipedia:Hex_key|hex key]] from the screw head you can use it to push the ''pickup'' into position and then fasten it. Do not over-tighten .

The pickup screw has a ''grounding wire'' connected to the ''pickup'' amplifier, if the ''pickup'' is "buzzing" after having moved it, is possible that the ''pickup screw'' isn't making proper contact with the holding plate. Just loosen the pickup screw and re-fasten.{{docnav
|[[The Ekdahl FAR - Hammer|The hammer]]
|[[The Ekdahl FAR - Configuration utility - Concept and Installation|Configuration utility]]
}}

File:Pickup.png

2025-01-24T22:50:30Z

Knaadmin:

Pickup details

The Ekdahl FAR - Specifications

2025-01-24T20:44:03Z

Knaadmin:

== Main unit ==

* Dimensions: 117mm x 57mm x 158mm / 46" x 2¼" x 6¼" (max)
* Weight: 3.6Kg / 8lb
* Power supply: 12V DC, 2A center positive barrel plug
* Audio output: 1Vpp max
* USB: Micro-B connector @ USB 2, presents a USB-SERIAL and USB-MIDI device
* MIDI: TRS 3.5mm Type A, MIDI In only
* Bowing range / Motor frequency range: ~30 Hz - 650 Hz<ref name="specs">This is an approximate range for the first generation of ''bowing motor''s</ref>
* Max string length:

== Control box ==

* Dimensions: 136 x 153 x 42mm / 5⅜" x 6" x 1⅝" stand alone (max), 22HP x 25mm deep when mounted as euro rack
* Weight: 500g / 8oz
* Max CV/Gate voltage in recommended: 12V
* Voltage range for each CV input:
** Harmonic V/Oct (A0) - 0 - 4V / 4 octaves (1327.716/V) (''Harmonic'' knob turned to ''0'')
** Harmonic shift (A1) - +/-2.425 (No attenuation)
** Pressure (A3), Hammer (A4) & Mute (A7) - 0 - 3.6V (No attenuation)
** Gate (A5) - 0 - 3.3V
* ADC resolution: A0 - A3 @ 16-bits, A4 - A7 @ 12-bits
* Input configuration: A4 and A5 configured as ''trigger''-inputs which reads new data once when the input voltage has passed a certain ''threshold'', all voltages under the ''threshold'' are recorded as ''0''. All other inputs are configured as regular inputs that are continuously read and their values recorded.
* CV input ring voltage/current for expression pedals: 5V @ 5mA / jack
* Audio output: 10Vpp (+/-5V)

{{docnav
|[[The Ekdahl FAR - Command reference|Command reference]]
|
}}

== Notes ==
<references/>

The Ekdahl FAR - Specifications

2025-01-24T20:35:50Z

Knaadmin:

== Main unit ==

* Dimensions: 117mm x 57mm x 158mm / 46" x 2¼" x 6¼" (max)
* Weight: 3.6Kg / 8lb
* Power supply: 12V DC, 2A center positive barrel plug
* Audio output: 1Vpp max
* USB: Micro-B connector @ USB 2, presents a USB-SERIAL and USB-MIDI device
* MIDI: TRS 3.5mm Type A, MIDI In only
* Bowing range / Motor frequency range: ~30 Hz - 650 Hz<ref name="specs">This is an approximate range for the first generation of ''bowing motor''s</ref>
* Max string length:

== Control box ==

* Dimensions: 136 x 153 x 42mm / 5⅜" x 6" x 1⅝" stand alone (max), 22HP x 25mm deep when mounted as euro rack
* Weight: 500g / 8oz
* Max CV/Gate voltage in recommended: 12V
* Voltage range for each CV input:
** Harmonic V/Oct (A0) - 0 - 4.9V / 49 Notes / ~5 octaves / 1327.716/V (''Harmonic'' knob turned to ''0'')
** Harmonic shift (A1) - +/-2.425 (No attenuation)
** Pressure (A3), Hammer (A4) & Mute (A7) - 0 - 3.6V (No attenuation)
** Gate (A5) - 0 - 3.3V
* ADC resolution: A0 - A3 @ 16-bits, A4 - A7 @ 12-bits
* Input configuration: A4 and A5 configured as ''trigger''-inputs which reads new data once when the input voltage has passed a certain ''threshold'', all voltages under the ''threshold'' are recorded as ''0''. All other inputs are configured as regular inputs that are continuously read and their values recorded.
* CV input ring voltage/current for expression pedals: 5V @ 5mA / jack
* Audio output: 10Vpp (+/-5V)

{{docnav
|[[The Ekdahl FAR - Command reference|Command reference]]
|
}}

== Notes ==
<references/>

The Ekdahl FAR - Specifications

2025-01-24T20:35:29Z

Knaadmin:

== Main unit ==

* Dimensions: 117mm x 57mm x 158mm / 46" x 2¼" x 6¼" (max)
* Weight: 3.6Kg / 8lb
* Power supply: 12V DC, 2A center positive barrel plug
* Audio output: 1Vpp max
* USB: Micro-B connector @ USB 2, presents a USB-SERIAL and USB-MIDI device
* MIDI: TRS 3.5mm Type A, MIDI In only
* Bowing range / Motor frequency range: ~30 Hz - 650 Hz<ref name="specs">This is an approximate range for the first generation of ''bowing motor''s</ref>
* Max string length:

== Control box ==

* Dimensions: 136 x 153 x 42mm / 5⅜" x 6" x 1⅝" stand alone (max), 22HP mounted as euro rack x 25mm deep
* Weight: 500g / 8oz
* Max CV/Gate voltage in recommended: 12V
* Voltage range for each CV input:
** Harmonic V/Oct (A0) - 0 - 4.9V / 49 Notes / ~5 octaves / 1327.716/V (''Harmonic'' knob turned to ''0'')
** Harmonic shift (A1) - +/-2.425 (No attenuation)
** Pressure (A3), Hammer (A4) & Mute (A7) - 0 - 3.6V (No attenuation)
** Gate (A5) - 0 - 3.3V
* ADC resolution: A0 - A3 @ 16-bits, A4 - A7 @ 12-bits
* Input configuration: A4 and A5 configured as ''trigger''-inputs which reads new data once when the input voltage has passed a certain ''threshold'', all voltages under the ''threshold'' are recorded as ''0''. All other inputs are configured as regular inputs that are continuously read and their values recorded.
* CV input ring voltage/current for expression pedals: 5V @ 5mA / jack
* Audio output: 10Vpp (+/-5V)

{{docnav
|[[The Ekdahl FAR - Command reference|Command reference]]
|
}}

== Notes ==
<references/>

The Ekdahl FAR - Specifications

2025-01-24T20:34:21Z

Knaadmin:

== Main unit ==

* Dimensions: 117mm x 57mm x 158mm / 46" x 2¼" x 6¼" (max)
* Weight: 3.6Kg / 8lb
* Power supply: 12V DC, 2A center positive barrel plug
* Audio output: 1Vpp max
* USB: Micro-B connector @ USB 2, presents a USB-SERIAL and USB-MIDI device
* MIDI: TRS 3.5mm Type A, MIDI In only
* Bowing range / Motor frequency range: ~30 Hz - 650 Hz<ref name="specs">This is an approximate range for the first generation of ''bowing motor''s</ref>
* Max string length:

== Control box ==

* Dimensions: 136 x 153 x 42mm / 5⅜" x 6" x 1⅝" stand alone (max), 22HP mounted as euro rack x 25mm deep
* Weight: 500g / 8oz
* Max CV/Gate voltage in recommended: 12V
* Voltage range for each CV input:
** Harmonic V/Oct (ADC0) - 0 - 4.9V / 49 Notes / ~5 octaves / 1327.716/V (''Harmonic'' knob turned to ''0'')
** Harmonic shift (ADC1) - +/-2.425 (No attenuation)
** Pressure (ADC3), Hammer (ADC4) & Mute (ADC7) - 0 - 3.6V (No attenuation)
** Gate (ADC5) - 0 - 3.3V
* ADC resolution: A0 - A3 @ 16-bits, A4 - A7 @ 12-bits
* Input configuration: A4 and A5 configured as ''trigger''-inputs which reads new data once when the input voltage has passed a certain ''threshold'', all voltages under the ''threshold'' are recorded as ''0''. All other inputs are configured as regular inputs that are continuously read and their values recorded.
* CV input ring voltage/current for expression pedals: 5V @ 5mA / jack
* Audio output: 10Vpp (+/-5V)

{{docnav
|[[The Ekdahl FAR - Command reference|Command reference]]
|
}}

== Notes ==
<references/>

The Ekdahl FAR - Specifications

2025-01-24T20:32:43Z

Knaadmin:

== Main unit ==

* Dimensions: 117mm x 57mm x 158mm / 46" x 2¼" x 6¼" (max)
* Weight: 3.6Kg / 8lb
* Power supply: 12V DC, 2A center positive barrel plug
* Audio output: 1Vpp max
* USB: Micro-B connector @ USB 2, presents a USB-SERIAL and USB-MIDI device
* MIDI: TRS 3.5mm Type A, MIDI In only
* Bowing range / Motor frequency range: ~30 Hz - 650 Hz<ref name="specs">This is an approximate range for the first generation of ''bowing motor''s</ref>
* Max string length:

== Control box ==

* Dimensions: 136 x 153 x 42mm / 5⅜" x 6" x 1⅝" stand alone (max), 22HP mounted as euro rack x 25mm deep
* Weight: 500g / 8oz
* Max CV/Gate voltage in recommended: 12V
* Voltage range for each CV input:
** Harmonic V/Oct (ADC0) - 0-4.9V (''Harmonic'' knob turned to ''0'') / 49 Notes / ~5 octaves / 1327.716/V
** Harmonic shift (ADC1) - +/-2.425 (No attenuation)
** Pressure (ADC3), Hammer (ADC4) & Mute (ADC7) - 0-3.6V (No attenuation)
** Gate (ADC5) - 0 - 3.3V
* ADC resolution: A0-A3 @ 16-bits, A4-A7 @ 12-bits
* Input configuration: A4 and A5 configured as ''trigger''-inputs which reads new data once when the input voltage has passed a certain ''threshold'', all voltages under the ''threshold'' are recorded as ''0''. All other inputs are configured as regular inputs that are continuously read and their values recorded.
* CV input ring voltage/current for expression pedals: 5V @ 5mA / jack
* Audio output: 10Vpp (+/-5V)

{{docnav
|[[The Ekdahl FAR - Command reference|Command reference]]
|
}}

== Notes ==
<references/>

The Ekdahl FAR - Mute

2025-01-24T18:47:48Z

Knaadmin:

[[File:Mute technical.png|thumb|Mute technical details]]

== Overview ==
The mute consists of two parts, the ''upper mute'' and the ''lower mute''. For the string to be completely muted, the string needs to be clamped in between these two mutes. By lowering the ''lower mute'' to a position where the string is not entirely muted through clamping, various other effects can be obtained. Placing it just below the string can for instance inhibit the string from doing wide swings, in general the ''fundamental'' has the widest swings and thus the fundamental can be suppressed while not affecting the higher harmonics. It can also be used to do pinch harmonics and other things.

The mute may have to be adjusted at times, especially when changing into a string of a different size.

Mechanically the ''lower mute'' works much the same as the [[The Ekdahl FAR - Bowing jack|bowing jack]].

== Adjusting the mute ==
To adjust the ''upper mute'', take a 2.7mm [[wikipedia:Hex_key|hex key]] and loosen the ''upper mute screw''. Move the ''upper mute'' so that it's ~1mm above the string. This measurement is very approximate and depends on the maximum swing of the string, if the ''upper mute'' is too close to the string it may accidentally mute the string at full resonance. If the ''upper mute'' is too far away the ''lower mute'' may not be able to clamp the string hard enough against the ''upper mute'', and if the string bends too much when muting an audible change in pitch may occur.

The ''lower mute'' uses the same concept of ''carriage screws'' as the bowing jack and is adjusted in the same way, remember that the same precautions must be taken. The distance in between the ''lower mute'' and the string follows the same rules as those for the ''upper mute''. {{docnav
|[[The Ekdahl FAR - Bowing jack|The bowing jack]]
|[[The Ekdahl FAR - Hammer|The hammer]]
}}

The Ekdahl FAR - Mute

2025-01-24T18:47:07Z

Knaadmin:

[[File:Mute technical.png|thumb|Mute technical details]]

== Overview ==
The mute consists of two parts, the ''upper mute'' and the ''lower mute''. For the string to be completely muted, the string needs to be clamped in between these two mutes. By lowering the ''lower mute'' to a position where the string is not entirely muted through clamping, various other effects can be obtained. Placing it just below the string can for instance inhibit the string from doing wide swings, in general the ''fundamental'' has the widest swings and thus the fundamental can be suppressed while not affecting the higher harmonics. It can also be used to do pinch harmonics and other things.

The mute may have to be adjusted at times, especially when changing into a string of a different size.

Mechanically the ''lower mute'' works much the same as the [[The Ekdahl FAR - Bowing jack|bowing jack]].

== Adjusting the mute ==
To adjust the ''upper mute'', take a 2.7mm [[wikipedia:Hex_key|hex key]] and loosen the ''upper mute screw''. Move the ''upper mute'' so that it's ~1mm above the string. This measurement is very approximate and depends on the maximum swing of the string, if the ''upper mute'' is too close to the string it may accidentally mute the string at full resonance. If the ''upper mute'' is too far away the ''lower mute'' may not be able to clamp the string hard enough against the ''upper mute'', and if the string bends too much an audible change in pitch may occur.

The ''lower mute'' uses the same concept of ''carriage screws'' as the bowing jack and is adjusted in the same way, remember that the same precautions must be taken. The distance in between the ''lower mute'' and the string follows the same rules as those for the ''upper mute''. {{docnav
|[[The Ekdahl FAR - Bowing jack|The bowing jack]]
|[[The Ekdahl FAR - Hammer|The hammer]]
}}

The Ekdahl FAR - Hammer

2025-01-24T18:13:57Z

Knaadmin:

== Technical details ==
[[File:The Ekdahl FAR - Hammer.png|thumb|Hammer technical details]]
The hammer on the Ekdahl FAR generally doesn't need adjustment and the mechanism is quite straight forward, however for completion and to be thorough this information is included.

The hammer on the Ekdahl FAR is actuated through the use of a [[wikipedia:Solenoid_(engineering)|solenoid]]. The ''solenoid'' being an electromagnetic device, it is encased in a ''shield'' in order to avoid [[wikipedia:Electromagnetic_interference|electromagnetic interference]] traveling into the [[The Ekdahl FAR - Pickup|pickup]] creating audible clicks and pops.

The ''solenoid'' and ''shield'' can be moved sideways by loosening two screws, this sets the amount of travel that the ''hammer'' has from its resting position until it touches the string. Increasing the travel of the ''hammer'' increases the force of the hammer hit against the string as the hammer has more time to accelerate, however it also increases the time from ''solenoid'' activation to the ''hammer'' hitting the string, effectively increasing ''mechanical latency''.

Most musicians that have dealt with digital recording recognize the concept of ''latency'' as being a "lag" when for instance playing a ''MIDI'' keyboard with a software synth; at times there can be a noticeable delay in between key press and sound.

The concept of ''mechanical latency'' is that when for instance playing a key on a piano, it will indeed take a moment from key press to the hammer hitting the string. Even tho this makes physical sense, the concept of ''mechanical latency'' came as a bit of a surprise in being an issue with the Ekdahl FAR. To make matters worse, the ''mechanical latency'' of the ''hammer'' is dependent on the force of the hammer hit - higher force means faster speed of the ''hammer'' resulting in the delay in between the ''solenoid'' activation and sound produced being reduced. For this reason, quieter ''hammer'' hits always have higher ''mechanical latency'' than louder ones. This may sound like a bad thing but in reality this would be the case for any acoustic piano as well (for instance).

In order for the user to be able to change both the velocity and ''latency'' of the ''hammer'', the ''hammer'' is adjustable. Certain strings, namely thinner ones, can produce heavy distortion if hit too hard.

The Ekdahl FAR - Hammer

2025-01-24T17:08:05Z

Knaadmin:

== Technical details ==
[[File:The Ekdahl FAR - Hammer.png|thumb|Hammer technical details]]
The hammer on the Ekdahl FAR generally doesn't need adjustment and the mechanism is quite straight forward, however for completion and to be thorough this information is included.

The hammer on the Ekdahl FAR is actuated through the use of a [[wikipedia:Solenoid_(engineering)|solenoid]]. The ''solenoid'' being an electromagnetic device, it is encased in a ''shield'' in order to avoid [[wikipedia:Electromagnetic_interference|electromagnetic interference]] traveling into the [[The Ekdahl FAR - Pickup|pickup]] creating audible clicks and pops.

The ''solenoid'' and ''shield'' can be moved sideways by loosening two screws, this sets the amount of travel that the ''hammer'' has from its resting position until it touches the string. Increasing the travel of the ''hammer'' increases the force of the hammer hit against the string as the hammer has more time to accelerate, however it also increases the time from ''solenoid'' activation to the ''hammer'' hitting the string, effectively increasing ''mechanical latency''.

Most musicians that have dealt with digital recording recognize the concept of ''latency'' as being a "lag" when for instance playing a ''MIDI'' keyboard with a software synth; at times there can be a noticeable delay in between key press and sound.

The concept of ''mechanical latency'' is that when for instance playing a key on a piano, it will indeed take a moment from key press to the hammer hitting the string. Even tho this makes physical sense, the concept of ''mechanical latency'' came as a bit of a surprise in being an issue with the Ekdahl FAR. To make matters worse, the ''mechanical latency'' of the ''hammer'' is dependent on the force of the hammer hit - higher force means faster speed of the ''hammer'' resulting in the delay in between the ''solenoid'' activation and sound produced being reduced. For this reason, quieter ''hammer'' hits always have higher ''mechanical latency'' than louder ones. This may sound like a bad thing but in reality this would be the case for any acoustic piano as well (for instance).

In order for the user to be able to change both the velocity and ''latency'' of the ''hammer'', the ''hammer'' was made adjustable. Certain strings, namely thinner ones, can produce heavy distortion if hit too hard.

File:The Ekdahl FAR - Hammer.png

2025-01-24T16:07:31Z

Knaadmin:

Hammer technical details