KNAS Wiki - User contributions [en]

The Ekdahl FAR - Command reference V1.1

2026-06-17T12:04:40Z

Knaadmin:

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The bowing wheel-''module'' ("bowingwheel" / "bw") ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The bow pressure-''module'' ("bowpressure" / "bp") ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The actuator handler-''module'' ("actuatorhandler" / "ah") ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The actuator-''module'' ("actuator" / "ac") ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The DC motor-''module'' ("dcmotor" / "dcm") ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The PID controller-''module'' ("pid") ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The harmonic series handler"-''module'' ("harmonicserieshandler" / "hsh") ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The harmonic series-''module'' ("harmonicseries" / "hs") ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The mute-''module'' ("mute" / "mu") ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The solenoid-''module'' ("solenoid" / "so") ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The control box-''module'' ("controlbox" / "cb") ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The midi configuration handler-''module'' ("midiconfigurationhandler" / "mcf") ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The midi configuration-''module'' ("midiconfiguration" / "mc") ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The plugin handler-''module'' ("pluginhandler" / "ph") ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The lfo-''plugin module'' ("lfo") ==
The "lfo"-''plugin module'' works like regular [[wikipedia:Low-frequency_oscillation|low frequency oscillator]] in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the ''target'' to "bowingwheel.harmonicserieshandler.shift:lfoout".

The output of the LFO is always given in the variable "lfoout", our ''target'' is set to "bowingwheel.harmonicserieshandler.shift" which controls the ''harmonic shift'' (pitchbend basically) of the ''bowing wheel''.

Since our update rate is set to every 10 milliseconds and our frequency is 1 Hertz the instrument will internally send 100 updates per second to the ''harmonic shift.'' Our amplitude is set to the maximum value and depending on the "harmonicserieshandler.shiftrange" this could give a smooth vibrato like sound or more of an experimental one with a wider range. If the modulation is too deep we can just adjust the amplitude of the LFO.
The "lfo"-''plugin modules commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the LFO
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target'' ''commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|waveform
|wf
|<nowiki>sine|triangle|square|saw</nowiki>
|Sets the LFO waveform
|-
|frequency
|fq
|Hertz
|Sets the LFO frequency
|-
|amplitude
|amp
|0-65535
|Sets the LFO amplitude
|-
|delay
|dl
|0-65535 milliseconds
|Ramps up the amplitude of the output waveform from zero to full amplitude in the given time span
|-
|resetdelay
|rd
| -
|Resets the delay and starts the ramping of the waveform
|-
|resetwave
|rw
| -
|Resets the waveform from the start (sync)
|-
|bipolar
|bp
|<nowiki>0|1</nowiki>
|Sets whether the waveform is bipolar (default) or positive only
|}

== The ahdsr-''plugin module'' ("ahdsr") ==
The "ahdsr"-''plugin module'' works like a standard [[wikipedia:ADSR|ADSR]] with the addition of a "hold"-period in between the "attack" and "decay" phase. The FAR specific items are the same as outlined in the "lfo"-''plugin module'' with the exception of the "releasetarget" which triggers once the AHDSR reaches zero. This is useful for doing things like automatically putting the ''bowing jack'' in the ''rest''-position when used on the ''pressure'' for instance. The ''commands'' for the "ahdsr"-''plugin module'' are
{| class="wikitable"
|+
!Long command
!Short command
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the AHDSR
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|gate
|gt
|<nowiki>0|1</nowiki>
|Gate signal, [1] initiates the ''attack'' phase and if it reaches its maximum value, ''holds'' for the time given. It then continues through the ''decay'' down to the ''sustain'' point. A [0] initiates the ''release'' from whatever point the ADSR is at
|-
|attack
|at
|milliseconds
|Attack time in milliseconds
|-
|hold
|hd
|milliseconds
|Hold time in milliseconds
|-
|decay
|dc
|milliseconds
|Decay time in milliseconds
|-
|sustain
|su
|0-65535
|Sustain point in amplitude units
|-
|release
|re
|milliseconds
|Release time in milliseconds
|-
|releasetarget
|rt
|''commands''
|''Commands'' to execute once the release has hit zero
|-
|amplitude
|amp
|0-65535
|Output amplitude
|-
|invert
|inv
|<nowiki>0|1</nowiki>
|Inverts the results and gives negative values
|}

== The number map-''plugin module'' ("numbermap" / "nm") ==
The "numbermap"-''plugin module'' is used to "map" a incoming number to a different outgoing number. The idea of the ''Number Map'' is for instance to scale the volume of different overtones to be more even by modifying the ''bow pressure'' depending on what ''harmonic'' is being played. Another use case would be to group certain ''MIDI'' keys to address a certain string, and other ''MIDI'' keys addressing another, depending on the how well different strings can render certain tones / harmonics.

The ''Number Map'' first needs a data set of several points where each point contains "an input of x outputs y". The ''Number Map'' is then ''triggered'' with a value of ''x''. When this happens it looks in its database for anything mapped to ''x'', if it finds it it outputs the ''commands'' set by the ''target'' but first replaces any occurances of the word "nmout" in the ''command string'' with the value of ''y''.

The "numbermap"-''plugin modules'' commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the numbermap
|-
|target
|tg
|''commands''
|Sets the ''commands'' to execute whenever the "numbermap"-''plugin modules'' is triggered with a mapped value
|-
|data
|da
|(in:out)*
|Set the map data in any number of pairs of [in] returns [out]
|-
|remove
|rm
|in
|Removes the map with [in] if it exists
|-
|scale
|sc
|?
|Sets the overall scale of the Number Map
|-
|trigger
|tr
|in
|Triggers the ''targets'' with the ''out'' number mapped to ''in'' if found
|}

The Ekdahl FAR - Command reference V1.1

2026-06-17T12:03:11Z

Knaadmin: /* The "bowingwheel"-module */

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The bowing wheel-''module'' ("bowingwheel" / "bw") ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The bow pressure-''module'' ("bowpressure" / "bp") ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The actuator handler-''module'' ("actuatorhandler" / "ah") ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The actuator-''module'' ("actuator" / "ac") ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The DC motor-''module'' ("dcmotor" / "dcm") ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The PID controller-''module'' ("pid") ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The harmonic series handler"-''module'' ("harmonicserieshandler" / "hsh") ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The harmonic series-''module'' ("harmonicseries" / "hs") ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The mute-''module'' ("mute" / "mu") ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The solenoid-''module'' ("solenoid" / "so") ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The control box-''module'' ("controlbox" / "cb") ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The midi configuration handler-''module'' ("midiconfigurationhandler" / "mcf") ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==
The "lfo"-''plugin module'' works like regular [[wikipedia:Low-frequency_oscillation|low frequency oscillator]] in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the ''target'' to "bowingwheel.harmonicserieshandler.shift:lfoout".

The output of the LFO is always given in the variable "lfoout", our ''target'' is set to "bowingwheel.harmonicserieshandler.shift" which controls the ''harmonic shift'' (pitchbend basically) of the ''bowing wheel''.

Since our update rate is set to every 10 milliseconds and our frequency is 1 Hertz the instrument will internally send 100 updates per second to the ''harmonic shift.'' Our amplitude is set to the maximum value and depending on the "harmonicserieshandler.shiftrange" this could give a smooth vibrato like sound or more of an experimental one with a wider range. If the modulation is too deep we can just adjust the amplitude of the LFO.
The "lfo"-''plugin modules commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the LFO
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target'' ''commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|waveform
|wf
|<nowiki>sine|triangle|square|saw</nowiki>
|Sets the LFO waveform
|-
|frequency
|fq
|Hertz
|Sets the LFO frequency
|-
|amplitude
|amp
|0-65535
|Sets the LFO amplitude
|-
|delay
|dl
|0-65535 milliseconds
|Ramps up the amplitude of the output waveform from zero to full amplitude in the given time span
|-
|resetdelay
|rd
| -
|Resets the delay and starts the ramping of the waveform
|-
|resetwave
|rw
| -
|Resets the waveform from the start (sync)
|-
|bipolar
|bp
|<nowiki>0|1</nowiki>
|Sets whether the waveform is bipolar (default) or positive only
|}

== The "ahdsr"-''plugin module'' ==
The "ahdsr"-''plugin module'' works like a standard [[wikipedia:ADSR|ADSR]] with the addition of a "hold"-period in between the "attack" and "decay" phase. The FAR specific items are the same as outlined in the "lfo"-''plugin module'' with the exception of the "releasetarget" which triggers once the AHDSR reaches zero. This is useful for doing things like automatically putting the ''bowing jack'' in the ''rest''-position when used on the ''pressure'' for instance. The ''commands'' for the "ahdsr"-''plugin module'' are
{| class="wikitable"
|+
!Long command
!Short command
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the AHDSR
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|gate
|gt
|<nowiki>0|1</nowiki>
|Gate signal, [1] initiates the ''attack'' phase and if it reaches its maximum value, ''holds'' for the time given. It then continues through the ''decay'' down to the ''sustain'' point. A [0] initiates the ''release'' from whatever point the ADSR is at
|-
|attack
|at
|milliseconds
|Attack time in milliseconds
|-
|hold
|hd
|milliseconds
|Hold time in milliseconds
|-
|decay
|dc
|milliseconds
|Decay time in milliseconds
|-
|sustain
|su
|0-65535
|Sustain point in amplitude units
|-
|release
|re
|milliseconds
|Release time in milliseconds
|-
|releasetarget
|rt
|''commands''
|''Commands'' to execute once the release has hit zero
|-
|amplitude
|amp
|0-65535
|Output amplitude
|-
|invert
|inv
|<nowiki>0|1</nowiki>
|Inverts the results and gives negative values
|}

== The "numbermap"-''plugin module'' ==
The "numbermap"-''plugin module'' is used to "map" a incoming number to a different outgoing number. The idea of the ''Number Map'' is for instance to scale the volume of different overtones to be more even by modifying the ''bow pressure'' depending on what ''harmonic'' is being played. Another use case would be to group certain ''MIDI'' keys to address a certain string, and other ''MIDI'' keys addressing another, depending on the how well different strings can render certain tones / harmonics.

The ''Number Map'' first needs a data set of several points where each point contains "an input of x outputs y". The ''Number Map'' is then ''triggered'' with a value of ''x''. When this happens it looks in its database for anything mapped to ''x'', if it finds it it outputs the ''commands'' set by the ''target'' but first replaces any occurances of the word "nmout" in the ''command string'' with the value of ''y''.

The "numbermap"-''plugin modules'' commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the numbermap
|-
|target
|tg
|''commands''
|Sets the ''commands'' to execute whenever the "numbermap"-''plugin modules'' is triggered with a mapped value
|-
|data
|da
|(in:out)*
|Set the map data in any number of pairs of [in] returns [out]
|-
|remove
|rm
|in
|Removes the map with [in] if it exists
|-
|scale
|sc
|?
|Sets the overall scale of the Number Map
|-
|trigger
|tr
|in
|Triggers the ''targets'' with the ''out'' number mapped to ''in'' if found
|}

The Ekdahl FAR - Command reference V1.1

2026-06-14T13:40:13Z

Knaadmin: /* The "numbermap"-plugin module */

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==
The "lfo"-''plugin module'' works like regular [[wikipedia:Low-frequency_oscillation|low frequency oscillator]] in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the ''target'' to "bowingwheel.harmonicserieshandler.shift:lfoout".

The output of the LFO is always given in the variable "lfoout", our ''target'' is set to "bowingwheel.harmonicserieshandler.shift" which controls the ''harmonic shift'' (pitchbend basically) of the ''bowing wheel''.

Since our update rate is set to every 10 milliseconds and our frequency is 1 Hertz the instrument will internally send 100 updates per second to the ''harmonic shift.'' Our amplitude is set to the maximum value and depending on the "harmonicserieshandler.shiftrange" this could give a smooth vibrato like sound or more of an experimental one with a wider range. If the modulation is too deep we can just adjust the amplitude of the LFO.
The "lfo"-''plugin modules commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the LFO
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target'' ''commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|waveform
|wf
|<nowiki>sine|triangle|square|saw</nowiki>
|Sets the LFO waveform
|-
|frequency
|fq
|Hertz
|Sets the LFO frequency
|-
|amplitude
|amp
|0-65535
|Sets the LFO amplitude
|-
|delay
|dl
|0-65535 milliseconds
|Ramps up the amplitude of the output waveform from zero to full amplitude in the given time span
|-
|resetdelay
|rd
| -
|Resets the delay and starts the ramping of the waveform
|-
|resetwave
|rw
| -
|Resets the waveform from the start (sync)
|-
|bipolar
|bp
|<nowiki>0|1</nowiki>
|Sets whether the waveform is bipolar (default) or positive only
|}

== The "ahdsr"-''plugin module'' ==
The "ahdsr"-''plugin module'' works like a standard [[wikipedia:ADSR|ADSR]] with the addition of a "hold"-period in between the "attack" and "decay" phase. The FAR specific items are the same as outlined in the "lfo"-''plugin module'' with the exception of the "releasetarget" which triggers once the AHDSR reaches zero. This is useful for doing things like automatically putting the ''bowing jack'' in the ''rest''-position when used on the ''pressure'' for instance. The ''commands'' for the "ahdsr"-''plugin module'' are
{| class="wikitable"
|+
!Long command
!Short command
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the AHDSR
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|gate
|gt
|<nowiki>0|1</nowiki>
|Gate signal, [1] initiates the ''attack'' phase and if it reaches its maximum value, ''holds'' for the time given. It then continues through the ''decay'' down to the ''sustain'' point. A [0] initiates the ''release'' from whatever point the ADSR is at
|-
|attack
|at
|milliseconds
|Attack time in milliseconds
|-
|hold
|hd
|milliseconds
|Hold time in milliseconds
|-
|decay
|dc
|milliseconds
|Decay time in milliseconds
|-
|sustain
|su
|0-65535
|Sustain point in amplitude units
|-
|release
|re
|milliseconds
|Release time in milliseconds
|-
|releasetarget
|rt
|''commands''
|''Commands'' to execute once the release has hit zero
|-
|amplitude
|amp
|0-65535
|Output amplitude
|-
|invert
|inv
|<nowiki>0|1</nowiki>
|Inverts the results and gives negative values
|}

== The "numbermap"-''plugin module'' ==
The "numbermap"-''plugin module'' is used to "map" a incoming number to a different outgoing number. The idea of the ''Number Map'' is for instance to scale the volume of different overtones to be more even by modifying the ''bow pressure'' depending on what ''harmonic'' is being played. Another use case would be to group certain ''MIDI'' keys to address a certain string, and other ''MIDI'' keys addressing another, depending on the how well different strings can render certain tones / harmonics.

The ''Number Map'' first needs a data set of several points where each point contains "an input of x outputs y". The ''Number Map'' is then ''triggered'' with a value of ''x''. When this happens it looks in its database for anything mapped to ''x'', if it finds it it outputs the ''commands'' set by the ''target'' but first replaces any occurances of the word "nmout" in the ''command string'' with the value of ''y''.

The "numbermap"-''plugin modules'' commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the numbermap
|-
|target
|tg
|''commands''
|Sets the ''commands'' to execute whenever the "numbermap"-''plugin modules'' is triggered with a mapped value
|-
|data
|da
|(in:out)*
|Set the map data in any number of pairs of [in] returns [out]
|-
|remove
|rm
|in
|Removes the map with [in] if it exists
|-
|scale
|sc
|?
|Sets the overall scale of the Number Map
|-
|trigger
|tr
|in
|Triggers the ''targets'' with the ''out'' number mapped to ''in'' if found
|}

The Ekdahl FAR - Command reference V1.1

2026-06-14T13:34:32Z

Knaadmin: /* The "numbermap"-plugin module */

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==
The "lfo"-''plugin module'' works like regular [[wikipedia:Low-frequency_oscillation|low frequency oscillator]] in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the ''target'' to "bowingwheel.harmonicserieshandler.shift:lfoout".

The output of the LFO is always given in the variable "lfoout", our ''target'' is set to "bowingwheel.harmonicserieshandler.shift" which controls the ''harmonic shift'' (pitchbend basically) of the ''bowing wheel''.

Since our update rate is set to every 10 milliseconds and our frequency is 1 Hertz the instrument will internally send 100 updates per second to the ''harmonic shift.'' Our amplitude is set to the maximum value and depending on the "harmonicserieshandler.shiftrange" this could give a smooth vibrato like sound or more of an experimental one with a wider range. If the modulation is too deep we can just adjust the amplitude of the LFO.
The "lfo"-''plugin modules commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the LFO
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target'' ''commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|waveform
|wf
|<nowiki>sine|triangle|square|saw</nowiki>
|Sets the LFO waveform
|-
|frequency
|fq
|Hertz
|Sets the LFO frequency
|-
|amplitude
|amp
|0-65535
|Sets the LFO amplitude
|-
|delay
|dl
|0-65535 milliseconds
|Ramps up the amplitude of the output waveform from zero to full amplitude in the given time span
|-
|resetdelay
|rd
| -
|Resets the delay and starts the ramping of the waveform
|-
|resetwave
|rw
| -
|Resets the waveform from the start (sync)
|-
|bipolar
|bp
|<nowiki>0|1</nowiki>
|Sets whether the waveform is bipolar (default) or positive only
|}

== The "ahdsr"-''plugin module'' ==
The "ahdsr"-''plugin module'' works like a standard [[wikipedia:ADSR|ADSR]] with the addition of a "hold"-period in between the "attack" and "decay" phase. The FAR specific items are the same as outlined in the "lfo"-''plugin module'' with the exception of the "releasetarget" which triggers once the AHDSR reaches zero. This is useful for doing things like automatically putting the ''bowing jack'' in the ''rest''-position when used on the ''pressure'' for instance. The ''commands'' for the "ahdsr"-''plugin module'' are
{| class="wikitable"
|+
!Long command
!Short command
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the AHDSR
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|gate
|gt
|<nowiki>0|1</nowiki>
|Gate signal, [1] initiates the ''attack'' phase and if it reaches its maximum value, ''holds'' for the time given. It then continues through the ''decay'' down to the ''sustain'' point. A [0] initiates the ''release'' from whatever point the ADSR is at
|-
|attack
|at
|milliseconds
|Attack time in milliseconds
|-
|hold
|hd
|milliseconds
|Hold time in milliseconds
|-
|decay
|dc
|milliseconds
|Decay time in milliseconds
|-
|sustain
|su
|0-65535
|Sustain point in amplitude units
|-
|release
|re
|milliseconds
|Release time in milliseconds
|-
|releasetarget
|rt
|''commands''
|''Commands'' to execute once the release has hit zero
|-
|amplitude
|amp
|0-65535
|Output amplitude
|-
|invert
|inv
|<nowiki>0|1</nowiki>
|Inverts the results and gives negative values
|}

== The "numbermap"-''plugin module'' ==
The "numbermap"-''plugin module'' is used to "map" a incoming number to a different outgoing number. The idea of the ''Number Map'' is for instance to scale the volume of different overtones to be more even by modifying the ''bow pressure'' depending on what ''harmonic'' is being played. Another use case would be to group certain ''MIDI'' keys to address a certain string, and other ''MIDI'' keys addressing another, depending on the how well different strings can render certain tones / harmonics.

The ''Number Map'' first needs a data set of several points where each point contains "an input of x outputs y". The ''Number Map'' is then ''triggered'' with a value of ''x''. When this happens it looks in its database for anything mapped to ''x'', if it finds it it outputs the ''commands'' set by the ''target'' but first replaces any occurances of the word "nmout" in the ''command string'' with the value of ''y''.

The "numbermap"-''plugin modules'' commands

The Ekdahl FAR - Command reference V1.1

2026-06-14T13:20:48Z

Knaadmin: /* The "ahdsr"-plugin module */

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==
The "lfo"-''plugin module'' works like regular [[wikipedia:Low-frequency_oscillation|low frequency oscillator]] in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the ''target'' to "bowingwheel.harmonicserieshandler.shift:lfoout".

The output of the LFO is always given in the variable "lfoout", our ''target'' is set to "bowingwheel.harmonicserieshandler.shift" which controls the ''harmonic shift'' (pitchbend basically) of the ''bowing wheel''.

Since our update rate is set to every 10 milliseconds and our frequency is 1 Hertz the instrument will internally send 100 updates per second to the ''harmonic shift.'' Our amplitude is set to the maximum value and depending on the "harmonicserieshandler.shiftrange" this could give a smooth vibrato like sound or more of an experimental one with a wider range. If the modulation is too deep we can just adjust the amplitude of the LFO.
The "lfo"-''plugin modules commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the LFO
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target'' ''commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|waveform
|wf
|<nowiki>sine|triangle|square|saw</nowiki>
|Sets the LFO waveform
|-
|frequency
|fq
|Hertz
|Sets the LFO frequency
|-
|amplitude
|amp
|0-65535
|Sets the LFO amplitude
|-
|delay
|dl
|0-65535 milliseconds
|Ramps up the amplitude of the output waveform from zero to full amplitude in the given time span
|-
|resetdelay
|rd
| -
|Resets the delay and starts the ramping of the waveform
|-
|resetwave
|rw
| -
|Resets the waveform from the start (sync)
|-
|bipolar
|bp
|<nowiki>0|1</nowiki>
|Sets whether the waveform is bipolar (default) or positive only
|}

== The "ahdsr"-''plugin module'' ==
The "ahdsr"-''plugin module'' works like a standard [[wikipedia:ADSR|ADSR]] with the addition of a "hold"-period in between the "attack" and "decay" phase. The FAR specific items are the same as outlined in the "lfo"-''plugin module'' with the exception of the "releasetarget" which triggers once the AHDSR reaches zero. This is useful for doing things like automatically putting the ''bowing jack'' in the ''rest''-position when used on the ''pressure'' for instance. The ''commands'' for the "ahdsr"-''plugin module'' are
{| class="wikitable"
|+
!Long command
!Short command
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the AHDSR
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|gate
|gt
|<nowiki>0|1</nowiki>
|Gate signal, [1] initiates the ''attack'' phase and if it reaches its maximum value, ''holds'' for the time given. It then continues through the ''decay'' down to the ''sustain'' point. A [0] initiates the ''release'' from whatever point the ADSR is at
|-
|attack
|at
|milliseconds
|Attack time in milliseconds
|-
|hold
|hd
|milliseconds
|Hold time in milliseconds
|-
|decay
|dc
|milliseconds
|Decay time in milliseconds
|-
|sustain
|su
|0-65535
|Sustain point in amplitude units
|-
|release
|re
|milliseconds
|Release time in milliseconds
|-
|releasetarget
|rt
|''commands''
|''Commands'' to execute once the release has hit zero
|-
|amplitude
|amp
|0-65535
|Output amplitude
|-
|invert
|inv
|<nowiki>0|1</nowiki>
|Inverts the results and gives negative values
|}

The Ekdahl FAR - Command reference V1.1

2026-06-14T12:42:29Z

Knaadmin: /* The "lfo"-plugin module */

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==
The "lfo"-''plugin module'' works like regular [[wikipedia:Low-frequency_oscillation|low frequency oscillator]] in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the ''target'' to "bowingwheel.harmonicserieshandler.shift:lfoout".

The output of the LFO is always given in the variable "lfoout", our ''target'' is set to "bowingwheel.harmonicserieshandler.shift" which controls the ''harmonic shift'' (pitchbend basically) of the ''bowing wheel''.

Since our update rate is set to every 10 milliseconds and our frequency is 1 Hertz the instrument will internally send 100 updates per second to the ''harmonic shift.'' Our amplitude is set to the maximum value and depending on the "harmonicserieshandler.shiftrange" this could give a smooth vibrato like sound or more of an experimental one with a wider range. If the modulation is too deep we can just adjust the amplitude of the LFO.
The "lfo"-''plugin modules commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the LFO
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target'' ''commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|waveform
|wf
|<nowiki>sine|triangle|square|saw</nowiki>
|Sets the LFO waveform
|-
|frequency
|fq
|Hertz
|Sets the LFO frequency
|-
|amplitude
|amp
|0-65535
|Sets the LFO amplitude
|-
|delay
|dl
|0-65535 milliseconds
|Ramps up the amplitude of the output waveform from zero to full amplitude in the given time span
|-
|resetdelay
|rd
| -
|Resets the delay and starts the ramping of the waveform
|-
|resetwave
|rw
| -
|Resets the waveform from the start (sync)
|-
|bipolar
|bp
|<nowiki>0|1</nowiki>
|Sets whether the waveform is bipolar (default) or positive only
|}

== The "ahdsr"-''plugin module'' ==
The "ahdsr"-''plugin module'' works like a standard [[wikipedia:ADSR|ADSR]] with the addition of a "hold"-period in between the "attack" and "decay" phase. The FAR specific items are the same as outlined in the [[The "lfo"-plugin module|"lfo"-''plugin module'']]. The ''commands'' for the "ahdsr"-''plugin module'' are
{| class="wikitable"
|+
!Long command
!Short command
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the AHDSR
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|gate
|gt
|<nowiki>0|1</nowiki>
|Gate signal, [1] initiates the ''attack'' phase and if it reaches its maximum value, ''holds'' for the time given. It then continues through the ''decay'' down to the ''sustain'' point. A [0] initiates the ''release'' from whatever point the ADSR is at
|-
|attack
|at
|milliseconds
|Attack time in milliseconds
|-
|hold
|hd
|milliseconds
|Hold time in milliseconds
|-
|decay
|dc
|milliseconds
|Decay time in milliseconds
|-
|sustain
|su
|0-65535
|Sustain point in amplitude units
|-
|release
|re
|milliseconds
|Release time in milliseconds
|-
|releasetarget
|rt
|''commands''
|''Commands'' to execute once the release has hit zero
|-
|amplitude
|amp
|0-65535
|Output amplitude
|-
|invert
|inv
|<nowiki>0|1</nowiki>
|Inverts the results and gives negative values
|}

The Ekdahl FAR - Command reference V1.1

2026-06-14T12:25:59Z

Knaadmin:

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==
The "lfo"-''plugin module'' works like regular [[wikipedia:Low-frequency_oscillation|low frequency oscillator]] in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the ''target'' to "bowingwheel.harmonicserieshandler.shift:lfoout".

The output of the LFO is always given in the variable "lfoout", our ''target'' is set to "bowingwheel.harmonicserieshandler.shift" which controls the ''harmonic shift'' (pitchbend basically) of the ''bowing wheel''.

Since our update rate is set to every 10 milliseconds and our frequency is 1 Hertz the instrument will internally send 100 updates per second to the ''harmonic shift.'' Our amplitude is set to the maximum value and depending on the "harmonicserieshandler.shiftrange" this could give a smooth vibrato like sound or more of an experimental one with a wider range. If the modulation is too deep we can just adjust the amplitude of the LFO.
The "lfo"-''plugin modules commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|name
|na
|string
|Sets the nickname of the LFO
|-
|enable
|en
|<nowiki>0|1</nowiki>
|Disables / Enables the output of the ''target'' ''commands''
|-
|target
|tg
|''commands''
|Sets the command string to execute each update cycle, the string [lfoout] will be replaced with the current value
|-
|updaterate
|ur
|milliseconds
|Sets the frequency with which the ''target commands'' are executed. Limited by the global maximum as set in the plugin handler
|-
|waveform
|wf
|<nowiki>sine|triangle|square|saw</nowiki>
|Sets the LFO waveform
|-
|frequency
|fq
|Hertz
|Sets the LFO frequency
|-
|amplitude
|amp
|0-65535
|Sets the LFO amplitude
|-
|delay
|dl
|0-65535 milliseconds
|Ramps up the amplitude of the output waveform from zero to full amplitude in the given time span
|-
|resetdelay
|rd
| -
|Resets the delay and starts the ramping of the waveform
|-
|resetwave
|rw
| -
|Resets the waveform from the start (sync)
|-
|bipolar
|bp
|<nowiki>0|1</nowiki>
|Sets whether the waveform is bipolar (default) or positive only
|}

The Ekdahl FAR - Command reference V1.1

2026-06-14T08:20:36Z

Knaadmin:

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==
The "lfo"-''plugin module'' works like regular [[wikipedia:Low-frequency_oscillation|low frequency oscillator]] in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the ''target'' to "bowingwheel.harmonicserieshandler.shift:lfoout".

The output of the LFO is always given in the variable "lfoout", our ''target'' is set to "bowingwheel.harmonicserieshandler.shift" which controls the ''harmonic shift'' (pitchbend basically) of the ''bowing wheel''.

Since our update rate is set to every 10 milliseconds and our frequency is 1 Hertz the instrument will internally send 100 updates per second to the ''harmonic shift.'' Our amplitude is set to the maximum value and depending on the "harmonicserieshandler.shiftrange" this could give a smooth vibrato like sound or more of an experimental one with a wider range. If the modulation is too deep we can just adjust the amplitude of the LFO.

The Ekdahl FAR - Command reference V1.1

2026-06-14T08:08:45Z

Knaadmin:

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==
The "lfo"-''plugin module'' works like regular low frequency oscillator in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
<pre>
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the target to "bw.hsh.sh:lfoout".
</pre>

The Ekdahl FAR - Command reference V1.1

2026-06-14T08:06:05Z

Knaadmin: /* The "lfo"-plugin module */

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==
The "lfo"-''plugin module'' works like regular low frequency oscillator in that it generates a given ''waveform'' with a given ''frequency'' at a certain ''amplitude''. In the Ekdahl FAR the distinguishing factors are that besides the common ''frequency, amplitude'' and ''waveform'' parameters, it also requires the use of a ''update rate'' and ''target'' parameter. The ''update rate'' sets how often the current position of the LFO is sampled (aka how often it peeks in on where the LFO is in its waveform transition at the moment), and each time that happens, the ''target commands'' are outputted to the instrument.

'''Example:'''
Lets set the ''waveform'' to "triangle", the ''amplitude'' to 65535 (max), the ''frequency'' to 1Hz (1 full waveform per second), the ''update rate'' to 10mS and the target to "bw.hsh.sh:lfoout".

The Ekdahl FAR - Command reference V1.1

2026-06-14T07:51:17Z

Knaadmin: /* The "pluginhandler"-module */

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==
The Ekdahl FAR allows for ''plugins''. These are ''modules'' that can trigger certain ''command strings'' to be executed either periodically or triggered by an incoming ''command''. Further explanation of the given ''plugins'' is given below. The various ''plugins'' are handled by the "pluginhandler"-''module'', the different ''plugin modules'' are identified by their own unique ''ID''. The "pluginhandler"-''module'' it has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|pluginid
|Add plugin with the given ID
|-
|remove
|rm
|pluginid:index
|Remove plugin with the given ID and index
|-
|count
|c
|(pluginid)
|Return the number of plugins of the given type, if none is given it returns all plugins
|}
The number of available ''plugins'' will differ from time to time as the ''plugin system'' has been purposefully designed to allow for anyone to write and add their own ''plugins''. As of the current writing (2026-06-14) the number of possible ''plugin modules'' that can exist under the "pluginhandler"-''module'' are
{| class="wikitable"
|+
!Long name
!Short name
|-
|lfo
|lfo
|-
|ahdsr
|ahdsr
|-
|numbermap
|map
|-
|multiple
|mlt
|}

== The "lfo"-''plugin module'' ==

The Ekdahl FAR - Command reference V1.1

2026-06-14T07:39:09Z

Knaadmin:

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}
The "actuatorhandler"-''module'' contains one or more of
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuator
|ac
|}

== The "actuator"-''module'' ==
The "actuator"-''module'' contains the following commands
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
|
|
|Selects the given actuator
|-
|name
|na
|string
|Sets the actuator name
|-
|data
|da
|name:rest:engage:stall
|Sets the actuator name, rest, engage and stall ''pressure''
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==

The Ekdahl FAR - Command reference V1.1

2026-06-14T06:53:39Z

Knaadmin:

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

The "bowpressure"-''module'' contains one or more of the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|actuatorhandler
|ah
|}

== The "actuatorhandler"-''module'' ==
The concept of "actuators" came up as it is possible to have ''bowing wheels'' of different sizes and wanting to be able to switch quickly in between them, perhaps during mid-performance. Because a differently sized wheel will require different values for the above mentioned "stall", "engage" and "reset"-''pressure'', each ''actuator'' stores these values. Instead of having to manually change the previously mentioned values, simply selecting a new ''actuator'' will automatically load the values. The "actuatorhandler"-''module'' is the handler of one or more "actuator"-''modules''.

The ''commands'' of the "acuatorhandler"-''module'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|add
|a
|(name):(rest:engage:stall)
|Add new actuator with the given name and parameters
|-
|remove
|rm
|actuatornumber
|Remove bow actuator [actuatornumber]
|-
|count
|c
| -
|Returns the amount of saved bow actuators
|}

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==

The Ekdahl FAR - Command reference V1.1

2026-06-14T06:37:20Z

Knaadmin:

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Ubiquitous commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}

== Base commands ==
B''ase commands'' are ''commands'' that always exist at the root in any implementation of the Ekdahl FAR.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|-
|programchange
|pc
|''commands''
|Sets the commands to execute at a MIDI Program change event
|-
|continuouscontrollerdata
|ccd
|controllernuber:''commands''
|Sets the commands to execute at a MIDI Continuous controller event with the given [''controllernumber'']
|-
|removecc
|rmc
|controllernuber
|Removes the entry associated with the MIDI continuous controller even ''controllernumber''
|-
|defaults
|d
| -
|Reverts the current configuration to default ''commands'', values and CCs
|-
|receivechannel
|rc
|channel
|Sets the MIDI receive channel of the current configuration. 1-16 sets specific channel, any other value for OMNI
|}

== The "pluginhandler"-''module'' ==

The Ekdahl FAR - Command reference V1.1

2026-06-12T16:23:11Z

Knaadmin:

== Introduction ==
The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]") and using ''ranges'' ("[3-6]"). ''Modules'' can be either ''internal'' or ''external'', meaning that they may all physically exist within a single hardware object, or they can be be remote-controlled devices. From a user perspective this however makes no difference as they will appear the same.

While all ''modules'' have their own set of ''commands'', there are certain ''commands'' that all ''modules'' must implement and can thus be accessed anywhere within the ''module hierarchy.'' There are also ''base commands'' that always exist within any given FAR ecosystem as well as product-specific ''base commands''.

== Basic commands ==
The ''module commands'' that are required to be implemented in all ''modules'' and that can thus be accessed from anywhere are

{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|list
|ls
|hidden/h:modules/m:commands/c:instances/i:instancecounts/ic:recursive/r
|Lists all ''commands'' and ''modules'' under the current module depending on the parameters given; 'hidden' includes normally hidden ''commands'', 'modules' includes any ''submodules'', 'commands' shows ''commands'', 'instances' shows data for each individual instance of a ''module'', 'instancecounts' includes number of instances of each ''module'', 'recursive' lists all child ''modules'' / ''commands''. No parameters defaults to showing all ''commands'' and ''modules'' recursively with instance counts. It doesn't show per-instance data or hidden commands.
|-
|help
|help
|recursive/r
|Shows a brief explanation of all ''commands'' and ''modules'', shows the help for all ''submodules'' as well if 'recursive'
|-
|dumpdata
|dump
|recursive/r
|Dumps all data saved for the current ''module'', will list the data of all ''submodules'' as well if 'recursive'
|}
The ''base commands'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|version
|ver
| -
|Gets the current firmware version
|-
|debugprint
|dp
|<nowiki>command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0</nowiki>
|Turns on or off serial feedback for the given item
|-
|requestinfo
|rqi
|command
|Retrives any data saved for a ''command'', if applicable
|-
|saveallparameters
|sap
| -
|Saves all avaliable parameters
|-
|loadallparameters
|lap
| -
|Loads all avaliable parameters
|-
|resetallparameters
|rap
| -
|Resets all saved parameters
|-
|reset
|rst
|<nowiki>1|0</nowiki>
|Resets the Ekdahl FAR, ''conditional''
|-
|nick
|nick
|name
|Sets the nickname of this unit
|-
|nooperation
|nop
| -
|Do absolutely, positively, nothing. Useful for testing and interfacing with computers, it's a good way to know that the unit is alive and responding since a "nop" is being returned as a response upon reception.
|-
|uservariable
|uv
|variable(0-9):value
|Set user variable 0-9 to 'value'
|-
|expressionparserevaluate
|epev
|expression
|Evaluates an arithmetric expression and sends back the output, all variables and functions that can be used in any ''command string'' can also be used here. Useful for testing expressions.
|-
|ifequal
|ife
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] EQUALS [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring].
|-
|ifgreater
|ifg
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] > [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|ifless
|ifl
|variable:comparator:truecommandstring:elsecommandstring
|Performs [IF [variable] < [comparator]] then add [truecommandstring] to the que if TRUE, otherwise add [elsecommandstring]
|-
|freeram
|ram
| -
|Shows free RAM memory
|}

The base also contains the following ''modules:''
{| class="wikitable"
|+
!Long name
!Short name
|-
|pluginhandler
|ph
|}

== The Ekdahl FAR stand alone single string unit ==
The Ekdahl FAR stand-alone single string unit offers these ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|calibrateall
|ca
| -
|Performs all calibration routines on the selected bow, see below for routines performed
|-
|calibratebowspeed
|cbs
| -
|Finds the minimum and maximum bow speed of the selected bow
|-
|calibratebowpressure
|cbp
| -
|Finds the minimum and maximum bow pressure of the selected bow
|-
|calibratemute
|cmu
| -
|Calibrate mute settings
|-
|pickupstringfrequency
|psf
| -
|Returns the fundamental tone calculated from the current audio signal if apliccable
|-
|pickupaudiopeak
|pap
| -
|Returns the peak amplitude of the current audio signal
|-
|pickupaudiorms
|par
| -
|Returns the RMS amplitude of the current audio signal
|}
The Ekdahl FAR also contains the following ''modules''
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowingwheel
|bw
|-
|mute
|mu
|-
|solenoid
|so
|-
|controlbox
|cb
|-
|midiconfigurationhandler
|mcf
|}

== The "bowingwheel"-''module'' ==

The "Bowingwheel"-''module'' contains everything needed to interface with a single ''bowing wheel''. Each ''bowing wheel'' has its own harmonic series, pressure actuators and direct hardware interface. It contains the following ''commands''.
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|speedmode
|sm
|<nowiki>0|1</nowiki>
|Bow motor speed mode, 0 = Automatic and 1 = Manual. Automatic mode means that the bowing wheel will automatically turn off after the ''motor timeout'' has been reached after being put into rest mode
|-
|motortimeout
|mt
|ms
|Bow motor shutdown timeout after bow having been put into the rest position
|-
|pidenable
|pe
|<nowiki>0|1</nowiki>
|Sets the bow PID on/off
|-
|motorfaultcommands
|mfc
|commands
|Commands to execute when a motor fault is tripped - !WARNING! Can ruin your instrument if changed
|-
|motoroverpowercommands
|moc
|commands
|Commands to execute when motor is over the power limit - !WARNING! Can ruin your instrument if changed
|}
The ''modules'' in the "Bowingwheel"-''module'' are as follows
{| class="wikitable"
|+
!Long name
!Short name
|-
|bowpressure
|bp
|-
|dcmotor
|dcm
|-
|pid
|pid
|-
|harmonicserieshandler
|hsh
|}

== The "bowpressure"-''module'' ==
The "bowpressure"-''module'' handles the ''pressure'' of the ''bowing wheel'' against the string. The "bowpressure"-''module'' has the following ''commands''
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|baseline
|ba
|0-65535
|Bow pressure baseline, modulation is added to this point upward. Typically this is set with a knob on the ''control box''
|-
|modifier
|mo
|0-65535
|Bow pressure modulation, added to the baseline
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''rest'' position, ''conditional''
|-
|engage
|en
|<nowiki>0|1</nowiki>
|Puts the bow pressure in the ''engage'' position, ''conditional''
|-
|stallpressure
|sp
|0-65535
|Bow pressure stall/maximum position, this parameter is set using ''hardware positioning'' and is used as the absolute maximum for baseline and modifier combiner
|-
|engagepressure
|ep
|0-65535
|Bow pressure touch/minimum position, this parameter is set using ''hardware position'' and is used as the starting point for when both the baseline and modifier is set to zero
|-
|restpressure
|rp
|0-65535
|Bow pressure rest position, this parameter is set using ''hardware positioning'' and is typically set to a point just below the string where it does not touch at all. The purpose of this is because while the actual hardware might be able to make the bow go even lower, that position might be far enough from the string that once ''engaged'' the bow may have so far to travel that there is perceptible ''latency''.
|-
|engagespeed
|es
|1- ~100
|Bow pressure movement speed when engaging or disengaging
|-
|modulationspeed
|ms
|0.1 - 10
|Bow pressure movement speed while engaged
|-
|hold
|hd
|<nowiki>0|1</nowiki>
|Sets bow hold (infinite sustain) on/off, ''conditional''
|-
|home
|hm
| -
|Homing bow, used at startup and in case of the bow loosing position
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}
Note that the "stall", "engage" and "rest"-pressure positions mention something called ''hardware position''. This means the entire available movement of the ''bowing jack''. Because the very bottom and top end of the movement might not be musically useful and may even harm the instrument, the "baseline" and "modifier" commands ''parameter''s are scaled depending on these settings.

The "engage" and "modulation"-speed settings sets how fast the stepper motor that drives the ''pressure'' moves depending on whether the ''bowing jack'' is set to ''engage'' or not. The idea here is that while wanting to be able to minimize ''latency'' by ''engaging'' and ''disengaging'' from the string as quickly as possible, dynamic changes in the ''pressure'' while playing benefits from much smoother movements as the ''bowing wheel'' takes some time to catch up to varying amounts of friction.

== The "dcmotor"-''module'' ==
The "dcmotor"-''module'' handles the direct raw control of the ''bowing motor'' and handles the reporting back of the current speed. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|run
|ru
|<nowiki>0|1</nowiki>
|Turns the motor off/on
|-
|pwm
|pw
|0-65535
|Bow motor direct power in 16-bit PWM values, requires that the ''PID'' is turned off
|-
|voltage
|vo
|~2 - 10V
|Sets the voltage of the regulator powering the motor. Changes here can make the motor more responsive to certain frequencies but will also affect how well the ''PID'' works. !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|current
|cu
|float
|Bow motor reported current use
|-
|currentlimit
|cl
|float
|Bow motor current limit (A)- !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|powerlimit
|pl
|float
|Bow motor power limit (W) - !WARNING! CAN RUIN YOUR INSTRUMENT IF CHANGED
|-
|frequency
|fq
|float
|Bow motor reported frequency
|-
|emergencystop
|es
|ms (0-65535)
|Immediately stops the bowing motor and doesn't allow it to start again until the cool down period given in the first argument has lapsed (milliseconds)
|-
|minpwm
|ip
|0-65535
|Bow motor minimum PWM (for calibration)
|-
|maxpwm
|xp
|0-65535
|Bow motor maximum PWM (for calibration)
|}

== The "pidcontroller"-''module'' ==
The "pidcontroller"-''module'' is responsible for keeping the "dcmotor"-''module'' at a certain frequency (given in Hertz). It takes the output of the motor frequency measurement and feeds it a PWM value that tries to make the speed constant regardless of the friction that the motor is enduring. To learn more about PID Controllers please see this [[wikipedia:PID_controller|wikipedia article]]. The ''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|targetfrequency
|tf
|hertz
|Sets the PID target frequency
|-
|ki
|ki
|float
|Sets the Ki parameter of the PID
|-
|kp
|kp
|float
|Sets the Kp parameter of the PID
|-
|kd
|kd
|float
|Sets the Kd parameter of the PID
|-
|integratorerror
|ie
|float
|Sets the lower threshold of error values for the PID integrator to ignore
|-
|reset
|re
| -
|Resets the PID integrator and derivative
|-
|maxerror
|xe
|float
|Maximum error to correct in each PID loop, essentially sets acceleration
|-
|peakerror
|pe
|float
|Get latest PID peak error
|-
|motorspeedmax
|msx
|Hertz
|Bow motor maximum speed limit
|-
|motorspeedmin
|msi
|Hertz
|Bow motor minimum speed limit
|-
|measuretimetotarget
|mtt
|Hertz
|Measure the time it takes to change from the current frequency to the target frequency, for testing purposes
|}

== The "harmonicserieshandler"-''module'' ==
The "harmonicserieshandler"-''module'' is responsible for sending frequency data to the "pid"-''module''. It handles calculating the correct frequency of the ''bowing wheel'' according to the selected ''harmonic'' and ''harmonic shift'' per the currently selected ''harmonic series''. The "harmonicserieshandler"-''module'' has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|fundamental
|fu
|Hertz
|The fundamental frequency of the string, all harmonics are calculated from this number
|-
|harmonic
|h
|int
|Selects the harmonic number to set the ''bowing wheel'' to. A ratio is taken from the given ''harmonic'' in the current ''harmonic series'', the ratio is then multiplied by the ''fundamental frequency''
|-
|harmonicadd
|ha
|int
|This number is added to the current harmonic
|-
|harmonicbase
|hb
|int
|Same as harmonic but where the harmonic number is based on a MIDI note given by basenote
|-
|basenote
|bn
|0-127
|Sets the MIDI base note of the ''bowing wheel'', used in conjunction with "harmonicbase"
|-
|shift
|sh
| -32767 - 32767
|Sets shift from the currently playing harmonic where 32767 equals the entire harmonic shift range shifted up
|-
|shiftrange
|sr
|0-36
|Set the number of harmonic numbers that constitutes an entire harmonic shift
|-
|shift5
|sh5
| -32767 - 32767
|Sets the shift from the currently playing harmonic over 5 octaves where 32767 equals 5 octaves shift up from the fundamental
|-
|add
|a
|(name):(ratios)
|Add a new series with the given name and parameters
|-
|remove
|rm
|series
|Remove the series given and shift any series accordingly. Cannot remove all series
|-
|count
|c
| -
|Returns the number of harmonic series in the list and their IDs
|}
The "harmonicserieshandler"-module contains at the very least ONE harmonic series, by default it contains two: one for equal temperament and one for just intonation. The current series can be selected by simply indexing the "harmonicseries"-''module'' without a ''command'', e.g. "harmonicserieshandler.harmonicseries[1]". To be consistent, these are the ''modules'' in the "harmonicserieshandler"-''module'':
{| class="wikitable"
|+
!Long name
!Short name
|-
|harmonicseries
|hs
|}

== The "harmonicseries"-''module'' ==
The "harmonicseries"-''module'' contains any number of ''ratios'' that comprises a scale, ratios are given in a standard format where a ratio of "1" is equal to the fundamental, "2" would be one octave up etc. A standard ''harmonic series'' contains 12 ratios following a just intonation scheme. The "harmonicserieshandler"-''module'' will automatically adapt to the currently selected ''harmonic series'' length, whether it's a standard 12-tone scale, some kinda 3-tone scale or a full on bananas 53-tone scale. The ''commands'' of the "harmonicseries"-''module'' is as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected ''harmonic Series''
|-
|name
|na
|string
|Sets the name of the ''harmonic series''
|-
|data
|da
|name:ratios
|Gets / sets all data for the ''harmonic series'' in the given slot with an arbitrary ''name'' as the first ''parameter''. The length of the series is simply set to the amount of ratios given
|-
|ratio
|r
|harmonic:ratio
|Sets the ratio of the given harmonic in current ''harmonic series'', will increase the list size if needed to address the harmonic
|-
|remove
|rm
|harmonic
|Remove the harmonic ratio given in the current series and shift any ratios accordingly. Cannot remove all ratios
|}

== The "mute"-''module'' ==
The "mute"-''module'' works very similarly to the "bowpressure"-''module'' in that it controls a stepper motor with some software limits in place in order to press the mute against the string. The ''commands'' are as follows:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|setposition
|sp
|0-65535
|Set mute position
|-
|fullmute
|fm
|<nowiki>0|1</nowiki>
|Puts the mute in ''full mute'' position, ''conditional''
|-
|halfmute
|hm
|<nowiki>0|1</nowiki>
|Puts the mute in ''half mute'' position, ''conditional''
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Put the mute in the ''rest'' position, ''conditional''
|-
|savefull
|sf
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''full mute'' position, ''conditional''
|-
|savehalf
|sh
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''half mute'' position, ''conditional''
|-
|saverest
|sr
|<nowiki>0|1</nowiki>
|Save the current mute position as the ''rest'' position, ''conditional''
|-
|fullmuteposition
|fmp
|0-65535
|Sets the ''full mute'' position according to the ''hardware position'' given
|-
|halfmuteposition
|hmp
|0-65535
|Sets the ''half mute'' position according to the ''hardware position'' given
|-
|restposition
|rp
|0-65535
|Sets the ''rest'' position according to the ''hardware position'' given
|-
|sustain
|su
|<nowiki>0|1</nowiki>
|Sets the sustain off/on, this will keep the mute in the ''rest'' position even if a "fullmute"-''command'' is given, lasts until "sustain" is set to "0".
|-
|backoff
|bo
|0-65535
|Setting the time that the mute stays in the mutefullmute position before automatically going into rest, set in mS. A value of "0" disables backoff. This is used because if the mute is not backing off until something is attempted to be played, the backing-off time will either introduce ''latency'' or the string will be initially partially muted
|-
|home
|hm
| -
|Home mute, used during initialization and if the mute were to loose position
|-
|hardwareposition
|hwp
|0-65535
|Sets the ''hardware position'' of the mute instead of scaling it over the ''full mute'' and ''rest'' positions. Mainly used internally by other ''modules''
|-
|completetask
|cpt
| -
|Requests a callback when the current operation is finished. Only used internally by other ''modules''
|-
|autocorrect
|ac
|<nowiki>0|1</nowiki>
|Enables auto correct positioning that uses the homing sensor to correct positioning on the fly. EXPERIMENTAL
|-
|homingsensed
|hms
| -
|Requests whether the homing sensor is currently active or not. Only used internally by other ''modules''
|-
|movedirection
|md
| -
|Requests the current direction of movement (0 Forward, 1 Reverse). Only used internally by other ''modules''
|-
|currentstep
|cs
| -
|Requests the current step. Only used internally by other ''modules''
|-
|homingpoint
|hmp
|edgedirection
|Requests the given homing point. Only used internally by other ''modules''
|-
|homingstage
|hms
| -
|Requests the current homing stage (UNHOMED, HOMED, FIRSTHOMINGRISING, SECONDHOMINGFALLING, SECONDHOMINGRISING, FIRSTHOMINGFALLING, MOVEPASTHOMESWITCH, MOVETOHOMESWITCH, GOTOOFFSET). Only used internally by other ''modules.''
|-
|tmcinfo
|tmi
| -
|Request statistical information from the TMC2209 stepper motor driver
|}

== The "solenoid"-''module'' ==
The "solenoid"-''module'' currently controls the ''hammer'' of the Ekdahl FAR. Due to the fact that the very same ''module'' could be used for anything that uses a striking ''solenoid'' it was named as such. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|engage
|en
|0-65535
|Engages the solenoid using the first parameter as the force
|-
|rest
|rs
|<nowiki>0|1</nowiki>
|Forces the solenoid to its rest position, ''conditional''
|-
|maxforce
|xf
|0-65535
|Set solenoid maximum usable force
|-
|minforce
|if
|0-65535
|Set solenoid minimum usable force
|-
|forcemultiplier
|fm
|0-65535
|Set solenoid force multiplier, useful for scaling of all incoming "engage"-''commands''
|-
|engageduration
|ed
|uS
|Sets the duration of the solenoid hit in uS, if a value of 0 is set the solenoid will not disengage until a rest command has been given. WARNING!! HAVING THE SOLENOID ON FOR A SPAN OF SECONDS COULD DESTROY THE CIRCUITRY!!
|}

== The "controlbox"-''module'' ==
The "controlbox"-''module'' communicates with an external ''control box'' and will issue associated ''commands'' whenever new values are read on the ADC-converters. It handles averaging and does some noise-cancellation functions on the values as well. The ''commands'' are:
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|harmonic
|har
|command string
|Sets the command string invoked when the harmonic knob or modulation changes
|-
|harmonicshift
|has
|command string
|Sets the command string invoked when the harmonic shift modulation changes
|-
|finetune
|fin
|command string
|Sets the command string invoked when the fine tune knob changes
|-
|pressure
|pre
|command string
|Sets the command string invoked when the pressure knob or modulation changes
|-
|mute
|mut
|command string
|Sets the command string invoked when the mute knob or modulation changes
|-
|hammerscale
|hms
|command string
|Sets the command string invoked when the hammer scale knob changes
|-
|gate
|gt
|command string
|Sets the command string invoked when the gate switch or modulation changes
|-
|hammertrig
|hmt
|command string
|Sets the command string invoked when the hammer trigger modulation changes
|-
|controldefaults
|cde
| -
|Reverts all ADC command strings to default values
|-
|datareturn
|dr
|channel:value
|Sent when a new value is presented on one of the ADC channels, cannot be invoked. Triggers the commands associated with the channel
|-
|adcsetting
|adcs
|channel : averages : interrupterrorthreshold : continuouserrorthreshold : continuoustimeout
|Sets ADC settings for a given channel. Averages are the number of samples to average, interruptthreshold is how much the value must change in order to issue a new value change event. continuousthreshold is how much the value must change when a previous change has already been recorded within the timespan of continuoustimeout
|-
|testadclatency
|tal
|0-65535
|Start a ADC latency test
|-
|testadclatencyreturn
|talr
| -
|Return from latency test
|-
|testadcminmax
|tix
|channel
|Test min/max value for a given channel and resets the counter
|}

== The "midiconfigurationhandler"-''module'' ==
The "midiconfigurationhandler"-''module'' handles a number of "midiconfiguration"-''modules''. It has the following ''commands'':
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|allnotesoff
|ano
| -
|Clears the entire buffer of MIDI notes held
|-
|add
|a
|name
|Adds a new MIDI configuration with the given name
|-
|remove
|rm
|int
|Remove the specified MIDI configuration
|-
|count
|c
| -
|Returns the number of MIDI configurations
|}
It contains one or more of the following
{| class="wikitable"
|+
!Long name
!Short name
|-
|midiconfiguration
|mc
|}

== The "midiconfiguration"-''module'' ==
A "midiconfiguration"-''module'' handles the reception of ''MIDI messages'' and will output the associated ''commands'' to the instrument internally. The commands are as follows
{| class="wikitable"
|+
!Long name
!Short name
!Parameters
!Description
|-
|[index]
| -
| -
|Sets the currently selected MIDI configuration
|-
|name
|na
|string
|Set the name of the MIDI configuration
|-
|noteon
|non
|''commands''
|Sets the commands to execute at a MIDI Note On event
|-
|noteoff
|nof
|''commands''
|Sets the commands to execute at a MIDI Note Off event
|-
|polyaftertouch
|pat
|''commands''
|Sets the commands to execute at a MIDI Polyphonic after touch event
|-
|channelaftertouch
|cat
|''commands''
|Sets the commands to execute at a MIDI Channel after touch event
|-
|pitchbend
|pb
|''commands''
|Sets the commands to execute at a MIDI Pitch bend event
|}

The Ekdahl FAR - Command reference V1.1

2026-06-12T15:36:04Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T15:10:00Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T14:34:15Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T14:15:51Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T14:01:16Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T13:38:26Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T13:27:18Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T12:44:53Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T12:07:20Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T11:55:23Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T11:40:18Z

Knaadmin: /* Introduction */

The Ekdahl FAR - Command reference V1.1

2026-06-12T11:05:30Z

Knaadmin:

The Ekdahl FAR - Command reference V1.1

2026-06-12T11:03:39Z

Knaadmin: Created page with "== Introduction == The Ekdahl FAR V1.1 introduces the concept of ''modules''. A ''module'' can contain any number of ''commands'' as well as other ''modules''. Furthermore any number of ''modules'' of the same type can exist within a context, these are addressed using classic C-style array ''indexing'' with the help of brackets ("[ ]"). Extending on the classic usage, multiple ''indexes'' can be addressed simultaneously by either comma-separating the objects ("[0,3,4]")..."

MediaWiki:Sidebar

2026-06-12T10:48:52Z

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 V1.0|Command reference V1.0
** The Ekdahl FAR - Command reference V1.1|Command reference V1.1
** The Ekdahl FAR - Specifications|Specifications
* SEARCH
* TOOLBOX
* LANGUAGES

The Ekdahl FAR - Command language (1.0)

2026-06-12T10:46:04Z

Knaadmin: Knaadmin moved page The Ekdahl FAR - Command language (1.0) to The Ekdahl FAR - Command language over redirect

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

The Ekdahl FAR - Command language

2026-06-12T10:46:04Z

Knaadmin: Knaadmin moved page The Ekdahl FAR - Command language (1.0) to The Ekdahl FAR - Command language over redirect

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

Since version 1.1 of the Ekdahl FAR Firmware, all commands are grouped in a hierarchical fashion according to their ''modules'' and each ladder in the hierarchy is separated by a period ("."), this works very much like folders or directories in a regular computer. Every ''module'' can contain both ''commands'' and other ''modules''. For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which handles direct control of the bowing motor. It also has a "pid" ''module'' that handles bow frequency among other thing.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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 valid, 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''
These variables will contain whatever data is relevant to the last event that occurred and may be overwritten by the next event.

===== 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:"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 ''"''bowcontrolfrequency" / "bowingwheel.pid.targetfrequency" is put in between double quotes ("). This is because the "pow''"-''function requires the use of a comma (",") in order to separate in between its two required inputs; ''x'' and ''y''. In order for the Ekdahl FAR to know that this comma does not signal the beginning of a new ''command,'' we use quotes. Single (') and double (") quotes can be used and nested in all ''parameters'' and are required in a lot of circumstances, improper nesting or not using quotes can lead to the instrument not understanding 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" / "bowingwheel.pid.targetfrequency"-command we can ask the Ekdahl FAR what the bowing frequency is set to by writing<pre>
FAR < 1.1:
rqi:bowcontrolfrequency

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command "bcf" / "bw.pid.tf" and has the value ''82.5''. Note that the returned ''command'' sent by an "rqi"-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn:3
</pre>will return the last data read on ''analog-to-digital convert'' channel 3.

== MIDI mapping ==
The way ''MIDI'' works int the Ekdahl FAR is that each ''MIDI message'' is associated with a certain ''command string'' and the ''MIDI message'' will also update some of the internal ''variables''. Any time the associated ''MIDI message'' is received the Ekdahl FAR will execute the ''commands'' that have been associated with that ''MIDI message''. Several ''MIDI configurations'' can be stored and recalled at any time, each with a different set of ''commands'' associated with each ''MIDI message''.

'''FAR < 1.1'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is "midieventhandler" or "mev" for short. The first ''parameter'' of "mev" is the type of ''MIDI message'' that we want to remap;

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

'''FAR 1.1'''

The "bowingwheel"-''module'' contains a ''module'' called "midiconfigurationhandler" that handles the loading and switching in between different ''MIDI configurations''. The "midiconfigurationhandler"''-module'' has one or more ''"''midiconfiguration"-''modules'', each having its own ''MIDI'' settings. In order to change the ''command mapping'' for a ''MIDI message'' in a specific ''MIDI configuration'', the following ''commands'' are used;

* '''noteon/non''':''commands'' - Sets the ''commands'' executed for a 'note on' ''MIDI message''
* '''noteoff/nof''''':commands'' - Sets the commands executed for a 'note off' ''MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a 'poly aftertouch' ''MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a 'channel aftertouch' ''MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a 'pitch bend' ''MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a 'program change' ''MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the ''commands'' executed for 'continuous controller' no ''controller''

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 in the currently selected ''MIDI configuration''.<pre>
FAR < 1.1:
rqi:midieventhandler:pb

FAR 1.1:
rqi:bowingwheel.midiconfigurationhandler.midiconfiguration.pitchbend
</pre>This may return something like<pre>
FAR < 1.1:
[irq]mev:pb:"bowcontrolharmonicshift:pitch*4"

FAR 1.1:
[irq]bw[0].mcf[0].mc[0].pb:"bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4"
</pre>The first part of the return message tells us that the incoming message is of "rqi"-type ("[irq]") which means it's responding to a information request ''command'' sent. The second part tells us what ''command'' the information request return is responding to and any ''parameters'' that may be pertinent. The third part of the message is the actual data stored.

For the FAR < 1.1 the data returned is for the ''command'' "mev" with the first ''parameter'' set to "pb", the ''command reference'' tells us this means the ''command'' "midieventhandler" and the ''parameter'' "pb" indicates this has to do with the ''pitch bend''. The data is "bowcontrolharmonicshift:pitch*4".

For the FAR 1.1 the data returned is for the ''command'' "bw[0].mcf[0].mc[0].pb" (bowinwheel[0].midiconfigurationhandler[0].midiconfiguration[0].pitchbend) and the data is "bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4". Note here that if we have several different ''MIDI configurations'' stored and we're currently using configuration number 2, the returned message would have been "bw[0].mcf[0].mc[2].pb".

that the ''pitch bend MIDI message'' is executing a "bowcontrolharmonicshift" / "harmonicseries.shift"-command with the parameter ''pitch*4''. Looking in the ''command reference'' we can see that ''"''bowcontrolharmonicshift" / "harmonicseries.shift"-''command'' shifts the frequency of the ''bowing wheel'' from the currently selected harmonic. The first (and only) ''parameter'' sets how much we want to shift it (the range depends on the "bowcontrolharmonicshiftrange''"'' / "harmonicseries.shiftrange"-''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 "bowcontrolharmonicshift" / "harmoniceseries.shift"-''command'' expects a ''16-bit signed'' value as its ''parameter''. This means that the valid ''parameter'' number can be anything from -32767 to 32767. A full ''harmonic shift'' downwards according to the range set 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 we have to multiply ''pitch'' by 4 in order to meet the requirements of a ''16-bit signed parameter''.

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 frequency''. Even if you would limit yourself to a single octave the instrument would never be able to be properly in tune. 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>
FAR < 1.1:
rqi:mev:noteon

FAR 1.1:
rqi:mcf.mf.non
</pre>Will return something like<pre>FAR < 1.1:
[irq]mev:noteon:'bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:note,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(velocity*512)*(1-notecount),bw.sm:0'</pre>As can be seen, there's a lot of stuff going on here! First of all, notice that everything after "mev:noteon:" / "mcf[0].mc[0].non:" is situated in between single quotes (') - this is absolutely crucial for the Ekdahl FAR in order to know that everything within those last two quotes is part of the last ''parameter'' of the "mev" / "mcf.mc.non"-''command''.

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

# "bchb:note" / "bw.hsh.hb:note" - Invokes the "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase"''-command'' with the first ''parameter'' set to the ''variable "''note". This sets the ''base harmonic'' that the Ekdahl FARs ''bowing motor'' should be set to. Here the ''variable'' "note" is used which is simply the MIDI key being pressed down, it is automatically converted by the ''command'' to the corresponding harmonic in the ''harmonic list''
# "bmr:1" / "bw.dcm.ru" - Sets the "bowmotorrun" / "dcmotor.run"-command to '1', starting the ''bow motor''
# "bpid:1" / "bw.pe:1" - Sets the "bowpid" / "bowingwheel.pidenable"-''command'' to '1'. Basically this enables the function that makes the Ekdahl FAR able to keep a stable frequency on the ''bowing motor''.
# "bpe:1" / "bw.bp.en" - Sets the "bowpressureengage" / "bowpressure.engage"-''command'' to '1' which moves the ''bowing jack'' to the ''engage position'', aka just below the string if not additional ''pressure'' is applied
# "se:(velocity*512)*(1-notecount)" / "so.en:(velocity*512)*(1-notecount)" - Executes the "solenoidengage" / "solenoid.engage"-''command'' with the value ''(velocity*512)*(1-notecount)''. This will make the ''solenoid'' strike the ''hammer'' with a force that is dependent on the "velocity"-''variable'' sent by the ''Note On MIDI message'' in order to make the ''hammer'' velocity sensitive. But it also adds the somewhat perplexing part "*(1-notecount)". "notecount" is a global ''variable'' that contains the number of MIDI keys that are currently being held down. If "notecount" is anything above zero, the outcome of the equation will either be zero or a negative number. The "solenoidengage" / "solenoid.engage"-''command'' requires a ''16-bit unsigned'' value, aka the only valid numbers are 0 - 65535. Anything below 0 will be interpreted as zero, so what this equation does is that it only fires off the ''hammer'' if there are no previous keys being held down - it's being used in ''staccato'' mode.
# "bcsm:0" / "bowingwheel.speedmode" - Sets the "bowcontrolspeedmode" / "bowingwheel.speedmode" to '1' which enables automatic shut down of the ''bowing motor'' after a given timeout.
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>FAR < 1.1:
[irq]mev:noteon:'bchb:36,bmr:1,bpid:1,bpe:1,se:(127*512)*(1-0),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:36,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(127*512)*(1-0),bw.sm: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" / "bw.hsh.hb:36" - The "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase" 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)" / "so.en: (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, the ''"''notecount"-''variable'' 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>
FAR < 1.1:
[irq]mev:noteon:'bchb:48,bmr:1,bpid:1,bpe:1,se:(63*512)*(1-1),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:48,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(65*512)*(1-1),bw.sm: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, the "notecount"-''variable'' is equal to ''1''. Here's what happens

# "bchb: 48" / "hsh.hb: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.en: (63*512)*(1-1)" - The equation evalutes as ''63 * 512 = 32256'' and ''1 - 1 = 0'' thus ''32256 * 0 = 0''. When the "solenoidengage" / "solenoid.engage"-''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(s) for setting the ''CV mapping'' is different and that they all modify (and thus share) the "value"-''variable''. These ''events'' are triggered whenever the analog-to-digital converter senses a change in a control or modulation jack, if you use something like an LFO with the modulation jacks here you will get a LOT of events and subsequent ''commands'' being sent.
'''FAR < 1.1:'''

The command for changing the CV mapping is "adccommandmap" or "acm", it take two parameters; channel and command string. The channels on the original Edkahl FAR Control box are as

* 0 - The "Harmonic" knob and jack
* 1 - The "Harmonic shift" knob and jack
* 2 - The "Fine tune" knob
* 3 - The "Pressure" knob and jack
* 4 - The "Hammertrig" button and jack
* 5 - The "Gate" switch and jack
* 6 - The "Hammer Scale" knob
* 7 - The "Mute" knob and jack

'''FAR 1.1:'''

The commands responsible for changing the CV mapping are located in the "controlbox"-module, these are

* '''harmonic''' '''/ har''' - Sets the ''commands'' executed when the "Harmonic"-knob or modulation changes
* '''harmonicshift''' '''/ has''' - Sets the ''commands'' executed when the "Harmonic shift"-knob or modulation changes
* '''finetune / fin''' - Sets the ''commands'' executed when the "Fine tune"-knob changes
* '''pressure''' '''/ pre''' - Sets the ''commands'' executed when the "Pressure"-knob or modulation changes
* '''mute''' '''/ mut''' - Sets the ''commands'' executed when the "Mute"-knob or modulation changes
* '''hammerscale / hms''' - Sets the ''commands'' executed when the "Hammer scale"-knob changes
* '''gate / gt''' - Sets the ''commands'' executed when the "Gate"-switch or modulation changes
* '''hammertrig''' '''/ hmt''' - Sets the ''commands'' executed when the "Hammer Trig"-button or modulation changes
In order to set/retrieve ''mapping data'' we just use a regular "rqi"-''command''. To for instance get the ''command string'' executed when the "pressure" knob or modulation is sent we can do the following
'''FAR < 1.1:'''
[send] rqi:acm:3
[returns] [irq]acm:3:'bpb:value'

'''FAR 1.1:'''
[send] rqi:controlbox.pressure
[returns] [irq]cb[0].pre:'bw.bp.ba:value'
As can be seen, when the ''pressure'' knob or modulation changes, the new data read by the ADC (stored in the "value"-''variable'') is sent to the ''command'' controlling the ''bow pressure baseline.'' Hopefully at this point it is obvious that making the knob and jack on the ''control box'' that is labeled as "Pressure" do something completely different, is quite easy - just remap the ''command string''.{{docnav
|[[The Ekdahl FAR - Service|Service]]
|[[The Ekdahl FAR - Command reference|Command reference]]
}}

The Ekdahl FAR - Command language

2026-06-12T10:45:15Z

Knaadmin: Knaadmin moved page The Ekdahl FAR - Command language to The Ekdahl FAR - Command language (1.0)

The Ekdahl FAR - Command reference V1.0

2026-06-12T10:44:30Z

Knaadmin: Knaadmin moved page The Ekdahl FAR - Command reference to The Ekdahl FAR - Command reference V1.0 without leaving a redirect

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

2026-06-12T10:32:53Z

Knaadmin:

The Ekdahl FAR - Command language

2026-06-12T10:12:26Z

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'', all 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''.

Since version 1.1 of the Ekdahl FAR Firmware, all commands are grouped in a hierarchical fashion according to their ''modules'' and each ladder in the hierarchy is separated by a period ("."), this works very much like folders or directories in a regular computer. Every ''module'' can contain both ''commands'' and other ''modules''. For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which handles direct control of the bowing motor. It also has a "pid" ''module'' that handles bow frequency among other thing.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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 valid, 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''
These variables will contain whatever data is relevant to the last event that occurred and may be overwritten by the next event.

===== 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:"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 ''"''bowcontrolfrequency" / "bowingwheel.pid.targetfrequency" is put in between double quotes ("). This is because the "pow''"-''function requires the use of a comma (",") in order to separate in between its two required inputs; ''x'' and ''y''. In order for the Ekdahl FAR to know that this comma does not signal the beginning of a new ''command,'' we use quotes. Single (') and double (") quotes can be used and nested in all ''parameters'' and are required in a lot of circumstances, improper nesting or not using quotes can lead to the instrument not understanding 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" / "bowingwheel.pid.targetfrequency"-command we can ask the Ekdahl FAR what the bowing frequency is set to by writing<pre>
FAR < 1.1:
rqi:bowcontrolfrequency

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command "bcf" / "bw.pid.tf" and has the value ''82.5''. Note that the returned ''command'' sent by an "rqi"-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn:3
</pre>will return the last data read on ''analog-to-digital convert'' channel 3.

== MIDI mapping ==
The way ''MIDI'' works int the Ekdahl FAR is that each ''MIDI message'' is associated with a certain ''command string'' and the ''MIDI message'' will also update some of the internal ''variables''. Any time the associated ''MIDI message'' is received the Ekdahl FAR will execute the ''commands'' that have been associated with that ''MIDI message''. Several ''MIDI configurations'' can be stored and recalled at any time, each with a different set of ''commands'' associated with each ''MIDI message''.

'''FAR < 1.1'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is "midieventhandler" or "mev" for short. The first ''parameter'' of "mev" is the type of ''MIDI message'' that we want to remap;

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

'''FAR 1.1'''

The "bowingwheel"-''module'' contains a ''module'' called "midiconfigurationhandler" that handles the loading and switching in between different ''MIDI configurations''. The "midiconfigurationhandler"''-module'' has one or more ''"''midiconfiguration"-''modules'', each having its own ''MIDI'' settings. In order to change the ''command mapping'' for a ''MIDI message'' in a specific ''MIDI configuration'', the following ''commands'' are used;

* '''noteon/non''':''commands'' - Sets the ''commands'' executed for a 'note on' ''MIDI message''
* '''noteoff/nof''''':commands'' - Sets the commands executed for a 'note off' ''MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a 'poly aftertouch' ''MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a 'channel aftertouch' ''MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a 'pitch bend' ''MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a 'program change' ''MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the ''commands'' executed for 'continuous controller' no ''controller''

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 in the currently selected ''MIDI configuration''.<pre>
FAR < 1.1:
rqi:midieventhandler:pb

FAR 1.1:
rqi:bowingwheel.midiconfigurationhandler.midiconfiguration.pitchbend
</pre>This may return something like<pre>
FAR < 1.1:
[irq]mev:pb:"bowcontrolharmonicshift:pitch*4"

FAR 1.1:
[irq]bw[0].mcf[0].mc[0].pb:"bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4"
</pre>The first part of the return message tells us that the incoming message is of "rqi"-type ("[irq]") which means it's responding to a information request ''command'' sent. The second part tells us what ''command'' the information request return is responding to and any ''parameters'' that may be pertinent. The third part of the message is the actual data stored.

For the FAR < 1.1 the data returned is for the ''command'' "mev" with the first ''parameter'' set to "pb", the ''command reference'' tells us this means the ''command'' "midieventhandler" and the ''parameter'' "pb" indicates this has to do with the ''pitch bend''. The data is "bowcontrolharmonicshift:pitch*4".

For the FAR 1.1 the data returned is for the ''command'' "bw[0].mcf[0].mc[0].pb" (bowinwheel[0].midiconfigurationhandler[0].midiconfiguration[0].pitchbend) and the data is "bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4". Note here that if we have several different ''MIDI configurations'' stored and we're currently using configuration number 2, the returned message would have been "bw[0].mcf[0].mc[2].pb".

that the ''pitch bend MIDI message'' is executing a "bowcontrolharmonicshift" / "harmonicseries.shift"-command with the parameter ''pitch*4''. Looking in the ''command reference'' we can see that ''"''bowcontrolharmonicshift" / "harmonicseries.shift"-''command'' shifts the frequency of the ''bowing wheel'' from the currently selected harmonic. The first (and only) ''parameter'' sets how much we want to shift it (the range depends on the "bowcontrolharmonicshiftrange''"'' / "harmonicseries.shiftrange"-''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 "bowcontrolharmonicshift" / "harmoniceseries.shift"-''command'' expects a ''16-bit signed'' value as its ''parameter''. This means that the valid ''parameter'' number can be anything from -32767 to 32767. A full ''harmonic shift'' downwards according to the range set 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 we have to multiply ''pitch'' by 4 in order to meet the requirements of a ''16-bit signed parameter''.

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 frequency''. Even if you would limit yourself to a single octave the instrument would never be able to be properly in tune. 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>
FAR < 1.1:
rqi:mev:noteon

FAR 1.1:
rqi:mcf.mf.non
</pre>Will return something like<pre>FAR < 1.1:
[irq]mev:noteon:'bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:note,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(velocity*512)*(1-notecount),bw.sm:0'</pre>As can be seen, there's a lot of stuff going on here! First of all, notice that everything after "mev:noteon:" / "mcf[0].mc[0].non:" is situated in between single quotes (') - this is absolutely crucial for the Ekdahl FAR in order to know that everything within those last two quotes is part of the last ''parameter'' of the "mev" / "mcf.mc.non"-''command''.

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

# "bchb:note" / "bw.hsh.hb:note" - Invokes the "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase"''-command'' with the first ''parameter'' set to the ''variable "''note". This sets the ''base harmonic'' that the Ekdahl FARs ''bowing motor'' should be set to. Here the ''variable'' "note" is used which is simply the MIDI key being pressed down, it is automatically converted by the ''command'' to the corresponding harmonic in the ''harmonic list''
# "bmr:1" / "bw.dcm.ru" - Sets the "bowmotorrun" / "dcmotor.run"-command to '1', starting the ''bow motor''
# "bpid:1" / "bw.pe:1" - Sets the "bowpid" / "bowingwheel.pidenable"-''command'' to '1'. Basically this enables the function that makes the Ekdahl FAR able to keep a stable frequency on the ''bowing motor''.
# "bpe:1" / "bw.bp.en" - Sets the "bowpressureengage" / "bowpressure.engage"-''command'' to '1' which moves the ''bowing jack'' to the ''engage position'', aka just below the string if not additional ''pressure'' is applied
# "se:(velocity*512)*(1-notecount)" / "so.en:(velocity*512)*(1-notecount)" - Executes the "solenoidengage" / "solenoid.engage"-''command'' with the value ''(velocity*512)*(1-notecount)''. This will make the ''solenoid'' strike the ''hammer'' with a force that is dependent on the "velocity"-''variable'' sent by the ''Note On MIDI message'' in order to make the ''hammer'' velocity sensitive. But it also adds the somewhat perplexing part "*(1-notecount)". "notecount" is a global ''variable'' that contains the number of MIDI keys that are currently being held down. If "notecount" is anything above zero, the outcome of the equation will either be zero or a negative number. The "solenoidengage" / "solenoid.engage"-''command'' requires a ''16-bit unsigned'' value, aka the only valid numbers are 0 - 65535. Anything below 0 will be interpreted as zero, so what this equation does is that it only fires off the ''hammer'' if there are no previous keys being held down - it's being used in ''staccato'' mode.
# "bcsm:0" / "bowingwheel.speedmode" - Sets the "bowcontrolspeedmode" / "bowingwheel.speedmode" to '1' which enables automatic shut down of the ''bowing motor'' after a given timeout.
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>FAR < 1.1:
[irq]mev:noteon:'bchb:36,bmr:1,bpid:1,bpe:1,se:(127*512)*(1-0),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:36,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(127*512)*(1-0),bw.sm: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" / "bw.hsh.hb:36" - The "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase" 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)" / "so.en: (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, the ''"''notecount"-''variable'' 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>
FAR < 1.1:
[irq]mev:noteon:'bchb:48,bmr:1,bpid:1,bpe:1,se:(63*512)*(1-1),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:48,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(65*512)*(1-1),bw.sm: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, the "notecount"-''variable'' is equal to ''1''. Here's what happens

# "bchb: 48" / "hsh.hb: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.en: (63*512)*(1-1)" - The equation evalutes as ''63 * 512 = 32256'' and ''1 - 1 = 0'' thus ''32256 * 0 = 0''. When the "solenoidengage" / "solenoid.engage"-''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(s) for setting the ''CV mapping'' is different and that they all modify (and thus share) the "value"-''variable''. These ''events'' are triggered whenever the analog-to-digital converter senses a change in a control or modulation jack, if you use something like an LFO with the modulation jacks here you will get a LOT of events and subsequent ''commands'' being sent.
'''FAR < 1.1:'''

The command for changing the CV mapping is "adccommandmap" or "acm", it take two parameters; channel and command string. The channels on the original Edkahl FAR Control box are as

* 0 - The "Harmonic" knob and jack
* 1 - The "Harmonic shift" knob and jack
* 2 - The "Fine tune" knob
* 3 - The "Pressure" knob and jack
* 4 - The "Hammertrig" button and jack
* 5 - The "Gate" switch and jack
* 6 - The "Hammer Scale" knob
* 7 - The "Mute" knob and jack

'''FAR 1.1:'''

The commands responsible for changing the CV mapping are located in the "controlbox"-module, these are

* '''harmonic''' - Sets the ''commands'' executed when the "Harmonic"-knob or modulation changes
* '''harmonicshift''' - Sets the ''commands'' executed when the "Harmonic shift"-knob or modulation changes
* '''finetune''' - Sets the ''commands'' executed when the "Fine tune"-knob changes
* '''pressure''' - Sets the ''commands'' executed when the "Pressure"-knob or modulation changes
* '''mute''' - Sets the ''commands'' executed when the "Mute"-knob or modulation changes
* '''hammerscale''' - Sets the ''commands'' executed when the "Hammer scale"-knob changes
* '''gate''' - Sets the ''commands'' executed when the "Gate"-switch or modulation changes
* '''hammertrig''' - Sets the ''commands'' executed when the "Hammer Trig"-button or modulation changes
In order to set/retrieve ''mapping data'' we just use a regular "rqi"-''command''. To for instance get the ''command string'' executed when the "harmonic" knob or modulation is sent we can do the following
'''FAR < 1.1:'''
[send] rqi:acm:0
[returns] [irq]acm:0:'bcha:value/1327.716667-20'

'''FAR 1.1:'''
[send] rqi:controlbox.harmonic
[returns] [irq]cb[0].har:'bw.hsh.ha:value/1327.716667-20'
What is returned is the ''command'' to set the ''harmonic'' with a ''parameter'' of "value/1327.71667-20"
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

The default response will be something like

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

The Ekdahl FAR - Command language

2026-06-12T09:37:55Z

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'', all 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''.

Since version 1.1 of the Ekdahl FAR Firmware, all commands are grouped in a hierarchical fashion according to their ''modules'' and each ladder in the hierarchy is separated by a period ("."), this works very much like folders or directories in a regular computer. Every ''module'' can contain both ''commands'' and other ''modules''. For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which handles direct control of the bowing motor. It also has a "pid" ''module'' that handles bow frequency among other thing.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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 valid, 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''
These variables will contain whatever data is relevant to the last event that occurred and may be overwritten by the next event.

===== 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:"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 ''"''bowcontrolfrequency" / "bowingwheel.pid.targetfrequency" is put in between double quotes ("). This is because the "pow''"-''function requires the use of a comma (",") in order to separate in between its two required inputs; ''x'' and ''y''. In order for the Ekdahl FAR to know that this comma does not signal the beginning of a new ''command,'' we use quotes. Single (') and double (") quotes can be used and nested in all ''parameters'' and are required in a lot of circumstances, improper nesting or not using quotes can lead to the instrument not understanding 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" / "bowingwheel.pid.targetfrequency"-command we can ask the Ekdahl FAR what the bowing frequency is set to by writing<pre>
FAR < 1.1:
rqi:bowcontrolfrequency

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command "bcf" / "bw.pid.tf" and has the value ''82.5''. Note that the returned ''command'' sent by an "rqi"-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn:3
</pre>will return the last data read on ''analog-to-digital convert'' channel 3.

== MIDI mapping ==
The way ''MIDI'' works int the Ekdahl FAR is that each ''MIDI message'' is associated with a certain ''command string'' and the ''MIDI message'' will also update some of the internal ''variables''. Any time the associated ''MIDI message'' is received the Ekdahl FAR will execute the ''commands'' that have been associated with that ''MIDI message''. Several ''MIDI configurations'' can be stored and recalled at any time, each with a different set of ''commands'' associated with each ''MIDI message''.

'''FAR < 1.1'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is "midieventhandler" or "mev" for short. The first ''parameter'' of "mev" is the type of ''MIDI message'' that we want to remap;

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

'''FAR 1.1'''

The "bowingwheel"-''module'' contains a ''module'' called "midiconfigurationhandler" that handles the loading and switching in between different ''MIDI configurations''. The "midiconfigurationhandler"''-module'' has one or more ''"''midiconfiguration"-''modules'', each having its own ''MIDI'' settings. In order to change the ''command mapping'' for a ''MIDI message'' in a specific ''MIDI configuration'', the following ''commands'' are used;

* '''noteon/non''':''commands'' - Sets the ''commands'' executed for a 'note on' ''MIDI message''
* '''noteoff/nof''''':commands'' - Sets the commands executed for a 'note off' ''MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a 'poly aftertouch' ''MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a 'channel aftertouch' ''MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a 'pitch bend' ''MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a 'program change' ''MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the ''commands'' executed for 'continuous controller' no ''controller''

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 in the currently selected ''MIDI configuration''.<pre>
FAR < 1.1:
rqi:midieventhandler:pb

FAR 1.1:
rqi:bowingwheel.midiconfigurationhandler.midiconfiguration.pitchbend
</pre>This may return something like<pre>
FAR < 1.1:
[irq]mev:pb:"bowcontrolharmonicshift:pitch*4"

FAR 1.1:
[irq]bw[0].mcf[0].mc[0].pb:"bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4"
</pre>The first part of the return message tells us that the incoming message is of "rqi"-type ("[irq]") which means it's responding to a information request ''command'' sent. The second part tells us what ''command'' the information request return is responding to and any ''parameters'' that may be pertinent. The third part of the message is the actual data stored.

For the FAR < 1.1 the data returned is for the ''command'' "mev" with the first ''parameter'' set to "pb", the ''command reference'' tells us this means the ''command'' "midieventhandler" and the ''parameter'' "pb" indicates this has to do with the ''pitch bend''. The data is "bowcontrolharmonicshift:pitch*4".

For the FAR 1.1 the data returned is for the ''command'' "bw[0].mcf[0].mc[0].pb" (bowinwheel[0].midiconfigurationhandler[0].midiconfiguration[0].pitchbend) and the data is "bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4". Note here that if we have several different ''MIDI configurations'' stored and we're currently using configuration number 2, the returned message would have been "bw[0].mcf[0].mc[2].pb".

that the ''pitch bend MIDI message'' is executing a "bowcontrolharmonicshift" / "harmonicseries.shift"-command with the parameter ''pitch*4''. Looking in the ''command reference'' we can see that ''"''bowcontrolharmonicshift" / "harmonicseries.shift"-''command'' shifts the frequency of the ''bowing wheel'' from the currently selected harmonic. The first (and only) ''parameter'' sets how much we want to shift it (the range depends on the "bowcontrolharmonicshiftrange''"'' / "harmonicseries.shiftrange"-''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 "bowcontrolharmonicshift" / "harmoniceseries.shift"-''command'' expects a ''16-bit signed'' value as its ''parameter''. This means that the valid ''parameter'' number can be anything from -32767 to 32767. A full ''harmonic shift'' downwards according to the range set 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 we have to multiply ''pitch'' by 4 in order to meet the requirements of a ''16-bit signed parameter''.

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 frequency''. Even if you would limit yourself to a single octave the instrument would never be able to be properly in tune. 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>
FAR < 1.1:
rqi:mev:noteon

FAR 1.1:
rqi:mcf.mf.non
</pre>Will return something like<pre>FAR < 1.1:
[irq]mev:noteon:'bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:note,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(velocity*512)*(1-notecount),bw.sm:0'</pre>As can be seen, there's a lot of stuff going on here! First of all, notice that everything after "mev:noteon:" / "mcf[0].mc[0].non:" is situated in between single quotes (') - this is absolutely crucial for the Ekdahl FAR in order to know that everything within those last two quotes is part of the last ''parameter'' of the "mev" / "mcf.mc.non"-''command''.

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

# "bchb:note" / "bw.hsh.hb:note" - Invokes the "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase"''-command'' with the first ''parameter'' set to the ''variable "''note". This sets the ''base harmonic'' that the Ekdahl FARs ''bowing motor'' should be set to. Here the ''variable'' "note" is used which is simply the MIDI key being pressed down, it is automatically converted by the ''command'' to the corresponding harmonic in the ''harmonic list''
# "bmr:1" / "bw.dcm.ru" - Sets the "bowmotorrun" / "dcmotor.run"-command to '1', starting the ''bow motor''
# "bpid:1" / "bw.pe:1" - Sets the "bowpid" / "bowingwheel.pidenable"-''command'' to '1'. Basically this enables the function that makes the Ekdahl FAR able to keep a stable frequency on the ''bowing motor''.
# "bpe:1" / "bw.bp.en" - Sets the "bowpressureengage" / "bowpressure.engage"-''command'' to '1' which moves the ''bowing jack'' to the ''engage position'', aka just below the string if not additional ''pressure'' is applied
# "se:(velocity*512)*(1-notecount)" / "so.en:(velocity*512)*(1-notecount)" - Executes the "solenoidengage" / "solenoid.engage"-''command'' with the value ''(velocity*512)*(1-notecount)''. This will make the ''solenoid'' strike the ''hammer'' with a force that is dependent on the "velocity"-''variable'' sent by the ''Note On MIDI message'' in order to make the ''hammer'' velocity sensitive. But it also adds the somewhat perplexing part "*(1-notecount)". "notecount" is a global ''variable'' that contains the number of MIDI keys that are currently being held down. If "notecount" is anything above zero, the outcome of the equation will either be zero or a negative number. The "solenoidengage" / "solenoid.engage"-''command'' requires a ''16-bit unsigned'' value, aka the only valid numbers are 0 - 65535. Anything below 0 will be interpreted as zero, so what this equation does is that it only fires off the ''hammer'' if there are no previous keys being held down - it's being used in ''staccato'' mode.
# "bcsm:0" / "bowingwheel.speedmode" - Sets the "bowcontrolspeedmode" / "bowingwheel.speedmode" to '1' which enables automatic shut down of the ''bowing motor'' after a given timeout.
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>FAR < 1.1:
[irq]mev:noteon:'bchb:36,bmr:1,bpid:1,bpe:1,se:(127*512)*(1-0),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:36,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(127*512)*(1-0),bw.sm: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" / "bw.hsh.hb:36" - The "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase" 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)" / "so.en: (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, the ''"''notecount"-''variable'' 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>
FAR < 1.1:
[irq]mev:noteon:'bchb:48,bmr:1,bpid:1,bpe:1,se:(63*512)*(1-1),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:48,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(65*512)*(1-1),bw.sm: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, the "notecount"-''variable'' is equal to ''1''. Here's what happens

# "bchb: 48" / "hsh.hb: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.en: (63*512)*(1-1)" - The equation evalutes as ''63 * 512 = 32256'' and ''1 - 1 = 0'' thus ''32256 * 0 = 0''. When the "solenoidengage" / "solenoid.engage"-''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''.
'''FAR < 1.1:'''

The command for changing the CV mapping is "adccommandmap" or "acm", it take two parameters; channel and command string. The channels on the original Edkahl FAR Control box are as

* 0 - The "Harmonic" knob and jack
* 1 - The "Harmonic shift" knob and jack
* 2 - The "Fine tune" knob
* 3 - The "Pressure" knob and jack
* 4 - The "Hammertrig" button and jack
* 5 - The "Gate" switch and jack
* 6 - The "Hammer Scale" knob
* 7 - The "Mute" knob and jack

'''FAR 1.1:'''

The commands responsible for changing the CV mapping are located in the "controlbox"-module, these are

* '''harmonic''' - Sets the ''commands'' executed when the "Harmonic"-knob or modulation changes
* '''harmonicshift''' - Sets the ''commands'' executed when the "Harmonic shift"-knob or modulation changes
* '''finetune''' - Sets the ''commands'' executed when the "Fine tune"-knob changes
* '''pressure''' - Sets the ''commands'' executed when the "Pressure"-knob or modulation changes
* '''mute''' - Sets the ''commands'' executed when the "Mute"-knob or modulation changes
* '''hammerscale''' - Sets the ''commands'' executed when the "Hammer scale"-knob changes
* '''gate''' - Sets the ''commands'' executed when the "Gate"-switch or modulation changes
* '''hammertrig''' - Sets the ''commands'' executed when the "Hammer Trig"-button or modulation changes
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

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

2026-06-12T09:04:31Z

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'', all 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''.

Since version 1.1 of the Ekdahl FAR Firmware, all commands are grouped in a hierarchical fashion according to their ''modules'' and each ladder in the hierarchy is separated by a period ("."), this works very much like folders or directories in a regular computer. Every ''module'' can contain both ''commands'' and other ''modules''. For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which handles direct control of the bowing motor. It also has a "pid" ''module'' that handles bow frequency among other thing.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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 valid, 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''
These variables will contain whatever data is relevant to the last event that occurred and may be overwritten by the next event.

===== 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:"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 ''"''bowcontrolfrequency" / "bowingwheel.pid.targetfrequency" is put in between double quotes ("). This is because the "pow''"-''function requires the use of a comma (",") in order to separate in between its two required inputs; ''x'' and ''y''. In order for the Ekdahl FAR to know that this comma does not signal the beginning of a new ''command,'' we use quotes. Single (') and double (") quotes can be used and nested in all ''parameters'' and are required in a lot of circumstances, improper nesting or not using quotes can lead to the instrument not understanding 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" / "bowingwheel.pid.targetfrequency"-command we can ask the Ekdahl FAR what the bowing frequency is set to by writing<pre>
FAR < 1.1:
rqi:bowcontrolfrequency

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command "bcf" / "bw.pid.tf" and has the value ''82.5''. Note that the returned ''command'' sent by an "rqi"-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn:3
</pre>will return the last data read on ''analog-to-digital convert'' channel 3.

== MIDI mapping ==
The way ''MIDI'' works int the Ekdahl FAR is that each ''MIDI message'' is associated with a certain ''command string'' and the ''MIDI message'' will also update some of the internal ''variables''. Any time the associated ''MIDI message'' is received the Ekdahl FAR will execute the ''commands'' that have been associated with that ''MIDI message''. Several ''MIDI configurations'' can be stored and recalled at any time, each with a different set of ''commands'' associated with each ''MIDI message''.

'''FAR < 1.1:'''

'''FAR < 1.1'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is "midieventhandler" or "mev" for short. The first ''parameter'' of "mev" is the type of ''MIDI message'' that we want to remap;

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

'''FAR 1.1'''

The "bowingwheel"-''module'' contains a ''module'' called "midiconfigurationhandler" that handles the loading and switching in between different ''MIDI configurations''. The "midiconfigurationhandler"''-module'' has one or more ''"''midiconfiguration"-''modules'', each having its own ''MIDI'' settings. In order to change the ''command mapping'' for a ''MIDI message'' in a specific ''MIDI configuration'', the following ''commands'' are used;

* '''noteon/non''':''commands'' - Sets the ''commands'' executed for a 'note on' ''MIDI message''
* '''noteoff/nof''''':commands'' - Sets the commands executed for a 'note off' ''MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a 'poly aftertouch' ''MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a 'channel aftertouch' ''MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a 'pitch bend' ''MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a 'program change' ''MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the ''commands'' executed for 'continuous controller' no ''controller''

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 in the currently selected ''MIDI configuration''.<pre>
FAR < 1.1:
rqi:midieventhandler:pb

FAR 1.1:
rqi:bowingwheel.midiconfigurationhandler.midiconfiguration.pitchbend
</pre>This may return something like<pre>
FAR < 1.1:
[irq]mev:pb:"bowcontrolharmonicshift:pitch*4"

FAR 1.1:
[irq]bw[0].mcf[0].mc[0].pb:"bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4"
</pre>The first part of the return message tells us that the incoming message is of "rqi"-type ("[irq]") which means it's responding to a information request ''command'' sent. The second part tells us what ''command'' the information request return is responding to and any ''parameters'' that may be pertinent. The third part of the message is the actual data stored.

For the FAR < 1.1 the data returned is for the ''command'' "mev" with the first ''parameter'' set to "pb", the ''command reference'' tells us this means the ''command'' "midieventhandler" and the ''parameter'' "pb" indicates this has to do with the ''pitch bend''. The data is "bowcontrolharmonicshift:pitch*4".

For the FAR 1.1 the data returned is for the ''command'' "bw[0].mcf[0].mc[0].pb" (bowinwheel[0].midiconfigurationhandler[0].midiconfiguration[0].pitchbend) and the data is "bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4". Note here that if we have several different ''MIDI configurations'' stored and we're currently using configuration number 2, the returned message would have been "bw[0].mcf[0].mc[2].pb".

that the ''pitch bend MIDI message'' is executing a "bowcontrolharmonicshift" / "harmonicseries.shift"-command with the parameter ''pitch*4''. Looking in the ''command reference'' we can see that ''"''bowcontrolharmonicshift" / "harmonicseries.shift"-''command'' shifts the frequency of the ''bowing wheel'' from the currently selected harmonic. The first (and only) ''parameter'' sets how much we want to shift it (the range depends on the "bowcontrolharmonicshiftrange''"'' / "harmonicseries.shiftrange"-''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 "bowcontrolharmonicshift" / "harmoniceseries.shift"-''command'' expects a ''16-bit signed'' value as its ''parameter''. This means that the valid ''parameter'' number can be anything from -32767 to 32767. A full ''harmonic shift'' downwards according to the range set 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 we have to multiply ''pitch'' by 4 in order to meet the requirements of a ''16-bit signed parameter''.

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 frequency''. Even if you would limit yourself to a single octave the instrument would never be able to be properly in tune. 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>
FAR < 1.1:
rqi:mev:noteon

FAR 1.1:
rqi:mcf.mf.non
</pre>Will return something like<pre>FAR < 1.1:
[irq]mev:noteon:'bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:note,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(velocity*512)*(1-notecount),bw.sm:0'</pre>As can be seen, there's a lot of stuff going on here! First of all, notice that everything after "mev:noteon:" / "mcf[0].mc[0].non:" is situated in between single quotes (') - this is absolutely crucial for the Ekdahl FAR in order to know that everything within those last two quotes is part of the last ''parameter'' of the "mev" / "mcf.mc.non"-''command''.

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

# "bchb:note" / "bw.hsh.hb:note" - Invokes the "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase"''-command'' with the first ''parameter'' set to the ''variable "''note". This sets the ''base harmonic'' that the Ekdahl FARs ''bowing motor'' should be set to. Here the ''variable'' "note" is used which is simply the MIDI key being pressed down, it is automatically converted by the ''command'' to the corresponding harmonic in the ''harmonic list''
# "bmr:1" / "bw.dcm.ru" - Sets the "bowmotorrun" / "dcmotor.run"-command to '1', starting the ''bow motor''
# "bpid:1" / "bw.pe:1" - Sets the "bowpid" / "bowingwheel.pidenable"-''command'' to '1'. Basically this enables the function that makes the Ekdahl FAR able to keep a stable frequency on the ''bowing motor''.
# "bpe:1" / "bw.bp.en" - Sets the "bowpressureengage" / "bowpressure.engage"-''command'' to '1' which moves the ''bowing jack'' to the ''engage position'', aka just below the string if not additional ''pressure'' is applied
# "se:(velocity*512)*(1-notecount)" / "so.en:(velocity*512)*(1-notecount)" - Executes the "solenoidengage" / "solenoid.engage"-''command'' with the value ''(velocity*512)*(1-notecount)''. This will make the ''solenoid'' strike the ''hammer'' with a force that is dependent on the "velocity"-''variable'' sent by the ''Note On MIDI message'' in order to make the ''hammer'' velocity sensitive. But it also adds the somewhat perplexing part "*(1-notecount)". "notecount" is a global ''variable'' that contains the number of MIDI keys that are currently being held down. If "notecount" is anything above zero, the outcome of the equation will either be zero or a negative number. The "solenoidengage" / "solenoid.engage"-''command'' requires a ''16-bit unsigned'' value, aka the only valid numbers are 0 - 65535. Anything below 0 will be interpreted as zero, so what this equation does is that it only fires off the ''hammer'' if there are no previous keys being held down - it's being used in ''staccato'' mode.
# "bcsm:0" / "bowingwheel.speedmode" - Sets the "bowcontrolspeedmode" / "bowingwheel.speedmode" to '1' which enables automatic shut down of the ''bowing motor'' after a given timeout.
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>FAR < 1.1:
[irq]mev:noteon:'bchb:36,bmr:1,bpid:1,bpe:1,se:(127*512)*(1-0),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:36,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(127*512)*(1-0),bw.sm: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" / "bw.hsh.hb:36" - The "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase" 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)" / "so.en: (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, the ''"''notecount"-''variable'' 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>
FAR < 1.1:
[irq]mev:noteon:'bchb:48,bmr:1,bpid:1,bpe:1,se:(63*512)*(1-1),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:48,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(65*512)*(1-1),bw.sm: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, the "notecount"-''variable'' is equal to ''1''. Here's what happens

# "bchb: 48" / "hsh.hb: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.en: (63*512)*(1-1)" - The equation evalutes as ''63 * 512 = 32256'' and ''1 - 1 = 0'' thus ''32256 * 0 = 0''. When the "solenoidengage" / "solenoid.engage"-''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

2026-06-10T18:05:36Z

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'', all 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''.

Since version 1.1 of the Ekdahl FAR Firmware, all commands are grouped in a hierarchical fashion according to their ''modules'' and each ladder in the hierarchy is separated by a period ("."), this works very much like folders or directories in a regular computer. Every ''module'' can contain both ''commands'' and other ''modules''. For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which handles direct control of the bowing motor. It also has a "pid" ''module'' that handles bow frequency among other thing.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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 valid, 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''
These variables will contain whatever data is relevant to the last event that occurred and may be overwritten by the next event.

===== 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:"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 ''"''bowcontrolfrequency" / "bowingwheel.pid.targetfrequency" is put in between double quotes ("). This is because the "pow''"-''function requires the use of a comma (",") in order to separate in between its two required inputs; ''x'' and ''y''. In order for the Ekdahl FAR to know that this comma does not signal the beginning of a new ''command,'' we use quotes. Single (') and double (") quotes can be used and nested in all ''parameters'' and are required in a lot of circumstances, improper nesting or not using quotes can lead to the instrument not understanding 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" / "bowingwheel.pid.targetfrequency"-command we can ask the Ekdahl FAR what the bowing frequency is set to by writing<pre>
FAR < 1.1:
rqi:bowcontrolfrequency

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command "bcf" / "bw.pid.tf" and has the value ''82.5''. Note that the returned ''command'' sent by an "rqi"-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn:3
</pre>will return the last data read on ''analog-to-digital convert'' channel 3.

== MIDI mapping ==
The way ''MIDI'' works int the Ekdahl FAR is that each ''MIDI message'' is associated with a certain ''command string'' and the ''MIDI message'' will also update some of the internal ''variables''. Any time the associated ''MIDI message'' is received the Ekdahl FAR will execute the ''commands'' that have been associated with that ''MIDI message''. Several ''MIDI configurations'' can be stored and recalled at any time, each with a different set of ''commands'' associated with each ''MIDI message''.

'''FAR < 1.1:'''

'''FAR < 1.1'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is "midieventhandler" or "mev" for short. The first ''parameter'' of "mev" is the type of ''MIDI message'' that we want to remap;

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

'''FAR 1.1'''

The "bowingwheel"-''module'' contains a ''module'' called "midiconfigurationhandler" that handles the loading and switching in between different ''MIDI configurations''. The "midiconfigurationhandler"''-module'' has one or more ''"''midiconfiguration"-''modules'', each having its own ''MIDI'' settings. In order to change the ''command mapping'' for a ''MIDI message'' in a specific ''MIDI configuration'', the following ''commands'' are used;

* '''noteon/non''':''commands'' - Sets the ''commands'' executed for a 'note on' ''MIDI message''
* '''noteoff/nof''''':commands'' - Sets the commands executed for a 'note off' ''MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a 'poly aftertouch' ''MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a 'channel aftertouch' ''MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a 'pitch bend' ''MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a 'program change' ''MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the ''commands'' executed for 'continuous controller' no ''controller''

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 in the currently selected ''MIDI configuration''.<pre>
FAR < 1.1:
rqi:midieventhandler:pb

FAR 1.1:
rqi:bowingwheel.midiconfigurationhandler.midiconfiguration.pitchbend
</pre>This may return something like<pre>
FAR < 1.1:
[irq]mev:pb:"bowcontrolharmonicshift:pitch*4"

FAR 1.1:
[irq]bw[0].mcf[0].mc[0].pb:"bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4"
</pre>The first part of the return message tells us that the incoming message is of "rqi"-type ("[irq]") which means it's responding to a information request ''command'' sent. The second part tells us what ''command'' the information request return is responding to and any ''parameters'' that may be pertinent. The third part of the message is the actual data stored.

For the FAR < 1.1 the data returned is for the ''command'' "mev" with the first ''parameter'' set to "pb", the ''command reference'' tells us this means the ''command'' "midieventhandler" and the ''parameter'' "pb" indicates this has to do with the ''pitch bend''. The data is "bowcontrolharmonicshift*4".

For the FAR 1.1 the data returned is for the ''command'' "bw[0].mcf[0].mc[0].pb" (bowinwheel[0].midiconfigurationhandler[0].midiconfiguration[0].pitchbend) and the data is "bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4". Note here that if we have several different ''MIDI configurations'' stored and we're currently using configuration number 2, the returned message would have been "bw[0].mcf[0].mc[2].pb".

that the ''pitch bend MIDI message'' is executing a "bowcontrolharmonicshift" / "harmonicseries.shift"-command with the parameter ''pitch*4''. Looking in the ''command reference'' we can see that ''"''bowcontrolharmonicshift" / "harmonicseries.shift"-''command'' shifts the frequency of the ''bowing wheel'' from the currently selected harmonic. The first (and only) ''parameter'' sets how much we want to shift it (the range depends on the "bowcontrolharmonicshiftrange''"'' / "harmonicseries.shiftrange"-''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 "bowcontrolharmonicshift" / "harmoniceseries.shift"-''command'' expects a ''16-bit signed'' value as its ''parameter''. This means that the valid ''parameter'' number can be anything from -32767 to 32767. A full ''harmonic shift'' downwards according to the range set 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 we have to multiply ''pitch'' by 4 in order to meet the requirements of a ''16-bit signed parameter''.

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 frequency''. Even if you would limit yourself to a single octave the instrument would never be able to be properly in tune. 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>
FAR < 1.1:
rqi:mev:noteon

FAR 1.1:
rqi:mcf.mf.non
</pre>Will return something like<pre>FAR < 1.1:
[irq]mev:noteon:'bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:note,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(velocity*512)*(1-notecount),bw.sm:0'</pre>As can be seen, there's a lot of stuff going on here! First of all, notice that everything after "mev:noteon:" / "mcf[0].mc[0].non:" is situated in between single quotes (') - this is absolutely crucial for the Ekdahl FAR in order to know that everything within those last two quotes is part of the last ''parameter'' of the "mev" / "mcf.mc.non"-''command''.

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

# "bchb:note" / "bw.hsh.hb:note" - Invokes the "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase"''-command'' with the first ''parameter'' set to the ''variable note''. This sets the ''base harmonic'' that the Ekdahl FARs ''bowing motor'' should be set to. Here the ''variable'' "note" is used which is simply the MIDI key being pressed down, it is automatically converted by the ''command'' to the corresponding harmonic in the ''harmonic list''
# "bmr:1" / "bw.dcm.ru" - Sets the "bowmotorrun" / "dcmotor.run"-command to '1', starting the ''bow motor''
# "bpid:1" / "bw.pe:1" - Sets the "bowpid" / "bowingwheel.pidenable"-''command'' to '1'. Basically this enables the function that makes the Ekdahl FAR able to keep a stable frequency on the ''bowing motor''.
# "bpe:1" / "bw.bp.en" - Sets the "bowpressureengage" / "bowpressure.engage"-''command'' to '1' which moves the ''bowing jack'' to the ''engage position'', aka just below the string if not additional ''pressure'' is applied
# "se:(velocity*512)*(1-notecount)" / "so.en:(velocity*512)*(1-notecount)" - Executes the "solenoidengage" / "solenoid.engage"-''command'' with the value ''(velocity*512)*(1-notecount)''. This will make the ''solenoid'' strike the ''hammer'' with a force that is dependent on the ''velocity'' variable sent by the ''Note On MIDI message'' in order to make the ''hammer'' velocity sensitive. But it also adds the somewhat perplexing part "*(1-notecount)". "notecount" is a global ''variable'' that contains the number of MIDI keys that are currently being held down. If "notecount" is anything above zero, the outcome of the equation will either be zero or a negative number. The "solenoidengage" / "solenoid.engage"-''command'' requires a ''16-bit unsigned'' value, aka the only valid numbers are 0 - 65535. Anything below 0 will be interpreted as zero, so what this equation does is that it only fires off the ''hammer'' if there are no previous keys being held down - it's being used in ''staccato'' mode.
# "bcsm:0" / "bowingwheel.speedmode" - Sets the "bowcontrolspeedmode" / "bowingwheel.speedmode" to '1' which enables automatic shut down of the ''bowing motor'' after a given timeout.
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

2026-06-10T17:53:56Z

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'', all 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''.

Since version 1.1 of the Ekdahl FAR Firmware, all commands are grouped in a hierarchical fashion according to their ''modules'' and each ladder in the hierarchy is separated by a period ("."), this works very much like folders or directories in a regular computer. Every ''module'' can contain both ''commands'' and other ''modules''. For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which handles direct control of the bowing motor. It also has a "pid" ''module'' that handles bow frequency among other thing.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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 valid, 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''
These variables will contain whatever data is relevant to the last event that occurred and may be overwritten by the next event.

===== 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:"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 ''"''bowcontrolfrequency" / "bowingwheel.pid.targetfrequency" is put in between double quotes ("). This is because the "pow''"-''function requires the use of a comma (",") in order to separate in between its two required inputs; ''x'' and ''y''. In order for the Ekdahl FAR to know that this comma does not signal the beginning of a new ''command,'' we use quotes. Single (') and double (") quotes can be used and nested in all ''parameters'' and are required in a lot of circumstances, improper nesting or not using quotes can lead to the instrument not understanding 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" / "bowingwheel.pid.targetfrequency"-command we can ask the Ekdahl FAR what the bowing frequency is set to by writing<pre>
FAR < 1.1:
rqi:bowcontrolfrequency

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command "bcf" / "bw.pid.tf" and has the value ''82.5''. Note that the returned ''command'' sent by an "rqi"-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn:3
</pre>will return the last data read on ''analog-to-digital convert'' channel 3.

== MIDI mapping ==
The way ''MIDI'' works int the Ekdahl FAR is that each ''MIDI message'' is associated with a certain ''command string'' and the ''MIDI message'' will also update some of the internal ''variables''. Any time the associated ''MIDI message'' is received the Ekdahl FAR will execute the ''commands'' that have been associated with that ''MIDI message''. Several ''MIDI configurations'' can be stored and recalled at any time, each with a different set of ''commands'' associated with each ''MIDI message''.

'''FAR < 1.1:'''

'''FAR < 1.1'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is "midieventhandler" or "mev" for short. The first ''parameter'' of "mev" is the type of ''MIDI message'' that we want to remap;

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

'''FAR 1.1'''

The "bowingwheel"-''module'' contains a ''module'' called "midiconfigurationhandler" that handles the loading and switching in between different ''MIDI configurations''. The "midiconfigurationhandler"''-module'' has one or more ''"''midiconfiguration"-''modules'', each having its own ''MIDI'' settings. In order to change the ''command mapping'' for a ''MIDI message'' in a specific ''MIDI configuration'', the following ''commands'' are used;

* '''noteon/non''':''commands'' - Sets the ''commands'' executed for a 'note on' ''MIDI message''
* '''noteoff/nof''''':commands'' - Sets the commands executed for a 'note off' ''MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a 'poly aftertouch' ''MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a 'channel aftertouch' ''MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a 'pitch bend' ''MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a 'program change' ''MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the ''commands'' executed for 'continuous controller' no ''controller''

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 in the currently selected ''MIDI configuration''.<pre>
FAR < 1.1:
rqi:midieventhandler:pb

FAR 1.1:
rqi:bowingwheel.midiconfigurationhandler.midiconfiguration.pitchbend
</pre>This may return something like<pre>
FAR < 1.1:
[irq]mev:pb:"bowcontrolharmonicshift:pitch*4"

FAR 1.1:
[irq]bw[0].mcf[0].mc[0].pb:"bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4"
</pre>The first part of the return message tells us that the incoming message is of "rqi"-type ("[irq]") which means it's responding to a information request ''command'' sent. The second part tells us what ''command'' the information request return is responding to and any ''parameters'' that may be pertinent. The third part of the message is the actual data stored.

For the FAR < 1.1 the data returned is for the ''command'' "mev" with the first ''parameter'' set to "pb", the ''command reference'' tells us this means the ''command'' "midieventhandler" and the ''parameter'' "pb" indicates this has to do with the ''pitch bend''. The data is "bowcontrolharmonicshift*4".

For the FAR 1.1 the data returned is for the ''command'' "bw[0].mcf[0].mc[0].pb" (bowinwheel[0].midiconfigurationhandler[0].midiconfiguration[0].pitchbend) and the data is "bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4". Note here that if we have several different ''MIDI configurations'' stored and we're currently using configuration number 2, the returned message would have been "bw[0].mcf[0].mc[2].pb".

that the ''pitch bend MIDI message'' is executing a "bowcontrolharmonicshift" / "harmonicseries.shift"-command with the parameter ''pitch*4''. Looking in the ''command reference'' we can see that ''"''bowcontrolharmonicshift" / "harmonicseries.shift"-''command'' shifts the frequency of the ''bowing wheel'' from the currently selected harmonic. The first (and only) ''parameter'' sets how much we want to shift it (the range depends on the "bowcontrolharmonicshiftrange''"'' / "harmonicseries.shiftrange"-''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 "bowcontrolharmonicshift" / "harmoniceseries.shift"-''command'' expects a ''16-bit signed'' value as its ''parameter''. This means that the valid ''parameter'' number can be anything from -32767 to 32767. A full ''harmonic shift'' downwards according to the range set 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 we have to multiply ''pitch'' by 4 in order to meet the requirements of a ''16-bit signed parameter''.

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 frequency''. Even if you would limit yourself to a single octave the instrument would never be able to be properly in tune. 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>
FAR < 1.1:
rqi:mev:noteon

FAR 1.1:
rqi:mcf.mf.non
</pre>Will return something like<pre>FAR < 1.1:
[irq]mev:noteon:'bchb:note,bmr:1,bpid:1,bpe:1,se:(velocity*512)*(1-notecount),bcsm:0'

FAR 1.1:
[irq]mcf[0].mc[0].non:'bw.hsh.hb:note,bw.dcm.ru:1,bw.pe:1,bw.bp.en:1,so.en:(velocity*512)*(1-notecount),bw.sm:0'</pre>As can be seen, there's a lot of stuff going on here! First of all, notice that everything after "mev:noteon:" / "mcf[0].mc[0].non:" is situated in between single quotes (') - this is absolutely crucial for the Ekdahl FAR in order to know that everything within those last two quotes is part of the last ''parameter'' of the "mev" / "mcf.mc.non"-''command''.

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

# "bchb:note" / "bw.hsh.hb:note" - Invokes the "bowcontrolharmonicbase" / "harmonicserieshandler.harmonicbase"''-command'' with the first ''parameter'' set to the ''variable note''. This sets the ''base harmonic'' that the Ekdahl FARs ''bowing motor'' should be set to.
# "bmr:1" / "bw.dcm.ru" - Sets the "bowmotorrun" / "dcmotor.run"-command to '1', starting the ''bow motor''
# "bpid:1" / "bw.pe:1" - Sets the "bowpid" / "bowingwheel.pidenable"-''command'' to '1'. Basically this enables the function that makes the Ekdahl FAR able to keep a stable frequency on the ''bowing motor''.
# "bpe:1" / "bw.bp.en" - Sets the "bowpressureengage" / "bowpressure.engage"-''command'' to '1' which moves the ''bowing jack'' to the ''engage position''
# "se:(velocity*512)*(1-notecount)" / "so.en:(velocity*512)*(1-notecount)" - Executes the "solenoidengage" / "solenoid.engage"-''command'' with the value ''(velocity*512)*(1-notecount)''. This will make the ''solenoid'' strike the ''hammer'' with a force that is dependent on the ''velocity'' variable sent by the ''Note On MIDI message'' in order to make the ''hammer'' velocity sensitive. But it also adds the somewhat perplexing part "*(1-notecount)". "notecount" is a global ''variable'' that contains the number of MIDI keys that are currently being held down. If "notecount" is anything above zero, the outcome of the equation will either be zero or a negative number. The "solenoidengage" / "solenoid.engage"-''command'' requires a ''16-bit unsigned'' value, aka the only valid numbers are 0 - 65535. Anything below 0 will be interpreted as zero, so what this equation does is that it only fires off the ''hammer'' if there are no previous keys being held down - it's going into ''staccato'' mode.
# "bcsm:0" / "bowingwheel.speedmode" - Sets the "bowcontrolspeedmode" / "bowingwheel.speedmode" to '1' which enables automatic shut down of the ''bowing motor'' after a given timeout.
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

2026-06-08T18:17:41Z

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'', all 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''.

Since version 1.1 of the Ekdahl FAR Firmware, all commands are grouped in a hierarchical fashion according to their ''modules'' and each ladder in the hierarchy is separated by a period ("."), this works very much like folders or directories in a regular computer. Every ''module'' can contain both ''commands'' and other ''modules''. For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which handles direct control of the bowing motor. It also has a "pid" ''module'' that handles bow frequency among other thing.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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 valid, 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''
These variables will contain whatever data is relevant to the last event that occurred and may be overwritten by the next event.

===== 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:"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 ''"''bowcontrolfrequency" / "bowingwheel.pid.targetfrequency" is put in between double quotes ("). This is because the "pow''"-''function requires the use of a comma (",") in order to separate in between its two required inputs; ''x'' and ''y''. In order for the Ekdahl FAR to know that this comma does not signal the beginning of a new ''command,'' we use quotes. Single (') and double (") quotes can be used and nested in all ''parameters'' and are required in a lot of circumstances, improper nesting or not using quotes can lead to the instrument not understanding 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" / "bowingwheel.pid.targetfrequency"-command we can ask the Ekdahl FAR what the bowing frequency is set to by writing<pre>
FAR < 1.1:
rqi:bowcontrolfrequency

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command "bcf" / "bw.pid.tf" and has the value ''82.5''. Note that the returned ''command'' sent by an "rqi"-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn:3
</pre>will return the last data read on ''analog-to-digital convert'' channel 3.

== MIDI mapping ==
The way ''MIDI'' works int the Ekdahl FAR is that each ''MIDI message'' is associated with a certain ''command string'' and the ''MIDI message'' will also update some of the internal ''variables''. Any time the associated ''MIDI message'' is received the Ekdahl FAR will execute the ''commands'' that have been associated with that ''MIDI message''. Several ''MIDI configurations'' can be stored and recalled at any time, each with a different set of ''commands'' associated with each ''MIDI message''.

'''FAR < 1.1:'''

'''FAR < 1.1'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is "midieventhandler" or "mev" for short. The first ''parameter'' of "mev" is the type of ''MIDI message'' that we want to remap;

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

'''FAR 1.1'''

The "bowingwheel"-''module'' contains a ''module'' called "midiconfigurationhandler" that handles the loading and switching in between different ''MIDI configurations''. The "midiconfigurationhandler"''-module'' has one or more ''"''midiconfiguration"-''modules'', each having its own ''MIDI'' settings. In order to change the ''command mapping'' for a ''MIDI message'' in a specific ''MIDI configuration'', the following ''commands'' are used;

* '''noteon/non''':''commands'' - Sets the ''commands'' executed for a 'note on' ''MIDI message''
* '''noteoff/nof''''':commands'' - Sets the commands executed for a 'note off' ''MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a 'poly aftertouch' ''MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a 'channel aftertouch' ''MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a 'pitch bend' ''MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a 'program change' ''MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the ''commands'' executed for 'continuous controller' no ''controller''

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 in the currently selected ''MIDI configuration''.<pre>
FAR < 1.1:
rqi:midieventhandler:pb

FAR 1.1:
rqi:bowingwheel.midiconfigurationhandler.midiconfiguration.pitchbend
</pre>This may return something like<pre>
FAR < 1.1:
[irq]mev:pb:"bchsh:pitch*4"

FAR 1.1:
[irq]bw[0].mcf[0].mc[0].pb:"bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4"
</pre>The first part of the return message tells us that the incoming message is of "rqi"-type ("[irq]") which means it's responding to a information request ''command'' sent. The second part tells us what ''command'' the data pertains to, and any ''parameters'' that may be pertinent. The third part of the message is the actual data stored.

For the FAR < 1.1 the data returned is for the ''command'' "mev" with the first ''parameter'' set to "pb", the ''command reference'' tells us this means the ''command'' "midieventhandler" and the ''parameter'' "pb" indicates this has to do with the ''pitch bend''. The data is "bchsh*4".

For the FAR 1.1 the data returned is for the ''command'' "bw[0].mcf[0].mc[0].pb" (bowinwheel[0].midiconfigurationhandler[0].midiconfiguration[0].pitchbend) and the data is "bowingwheel.harmonicserieshandler.harmonicseries.shift:pitch*4". Note here that if we have several different ''MIDI configurations'' stored and we're currently using configuration number 2, the returned message would have been "bw[0].mcf[0].mc[2].pb".

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

2026-06-08T15:06:37Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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''
These variables will contain whatever data is relevant to the last midi message sent and will not stay relevant beyond the reception of the last 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

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

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' / ''bw.pid.tf'' and has the value ''82.5''. Note that the returned ''command'' sent by an ''rqi''-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn: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.

'''FAR < 1.1:'''

'''FAR < 1.1'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is 'midieventhandler' or 'mev' for short. The first ''parameter'' of 'mev' is the type of ''MIDI message'' that we want to remap

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

'''FAR 1.1'''

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

* '''noteon/non''':''commands'' - Sets the ''commands'' executed for a 'note on' ''MIDI message''
* '''noteoff/nof''''':commands'' - Sets the commands executed for a 'note off' ''MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a 'poly aftertouch' ''MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a 'channel aftertouch' ''MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a 'pitch bend' ''MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a 'program change' ''MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the ''commands'' executed for 'continuous controller' no ''controller''

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>
FAR < 1.1:
rqi:mev:pb

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

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

2026-06-08T14:58:21Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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''
These variables will contain whatever data is relevant to the last midi message sent and will not stay relevant beyond the reception of the last 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

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

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' / ''bw.pid.tf'' and has the value ''82.5''. Note that the returned ''command'' sent by an ''rqi''-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn: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.

'''FAR < 1.1:'''
<pre>
The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is ''midieventhandler'' or ''mev'' for short. The first ''parameter'' of ''mev'' is the type of ''MIDI message'' that we want to remap

* '''''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''.
</pre>

<pre>
'''FAR 1.1:'''

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

* '''noteon/non''''':commands'' - Sets the commands executed for a ''note on'' ''MIDI message''
* '''noteoff''/nof'''''<nowiki/>'':commands'' - Sets the commands executed for a ''note off MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a ''poly aftertouch MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a ''channel aftertouch MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a ''pitch bend MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a ''program change MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the commands executed for ''continuous controller'' no ''controller''
</pre>

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>
FAR < 1.1:
rqi:mev:pb

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

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

2026-06-08T14:18:17Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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''
These variables will contain whatever data is relevant to the last midi message sent and will not stay relevant beyond the reception of the last 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

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

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' / ''bw.pid.tf'' and has the value ''82.5''. Note that the returned ''command'' sent by an ''rqi''-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn: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.

'''FAR < 1.1:'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is ''midieventhandler'' or ''mev'' for short. The first ''parameter'' of ''mev'' is the type of ''MIDI message'' that we want to remap

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

'''FAR 1.1:'''

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

* '''noteon/non''''':commands'' - Sets the commands executed for a ''note on'' ''MIDI message''
* '''noteoff''/nof'''''<nowiki/>'':commands'' - Sets the commands executed for a ''note off MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a ''poly aftertouch MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a ''channel aftertouch MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a ''pitch bend MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a ''program change MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the commands executed for ''continuous controller'' no ''controller''

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

2026-06-08T14:16:14Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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''
These variables will contain whatever data is relevant to the last midi message sent and will not stay relevant beyond the reception of the last 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

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

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' / ''bw.pid.tf'' and has the value ''82.5''. Note that the returned ''command'' sent by an ''rqi''-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn: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.

'''FAR < 1.1:'''
<pre>
The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is ''midieventhandler'' or ''mev'' for short. The first ''parameter'' of ''mev'' is the type of ''MIDI message'' that we want to remap

* '''''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''.
</pre>

<pre>
'''FAR 1.1:'''

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

* '''noteon/non''''':commands'' - Sets the commands executed for a ''note on'' ''MIDI message''
* '''noteoff''/nof'''''<nowiki/>'':commands'' - Sets the commands executed for a ''note off MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a ''poly aftertouch MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a ''channel aftertouch MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a ''pitch bend MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a ''program change MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the commands executed for ''continuous controller'' no ''controller''
</pre>

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

2026-06-08T14:15:12Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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''
These variables will contain whatever data is relevant to the last midi message sent and will not stay relevant beyond the reception of the last 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

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

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' / ''bw.pid.tf'' and has the value ''82.5''. Note that the returned ''command'' sent by an ''rqi''-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn: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.

'''FAR < 1.1:'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is ''midieventhandler'' or ''mev'' for short. The first ''parameter'' of ''mev'' is the type of ''MIDI message'' that we want to remap

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

'''FAR 1.1:'''

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

* '''noteon/non''''':commands'' - Sets the commands executed for a ''note on'' ''MIDI message''
* '''noteoff''/nof'''''<nowiki/>'':commands'' - Sets the commands executed for a ''note off MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a ''poly aftertouch MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a ''channel aftertouch MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a ''pitch bend MIDI message''
* '''programchange/pc''''':commands'' - Sets the commands executed for a ''program change MIDI message''
* '''continuouscontrollerdata/ccd''''':controller:commands'' - Sets the commands executed for ''continuous controller'' no ''controller''

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

2026-06-07T18:04:44Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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''
These variables will contain whatever data is relevant to the last midi message sent and will not stay relevant beyond the reception of the last 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

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

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' / ''bw.pid.tf'' and has the value ''82.5''. Note that the returned ''command'' sent by an ''rqi''-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn: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.

'''FAR < 1.1:'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is ''midieventhandler'' or ''mev'' for short. The first ''parameter'' of ''mev'' is the type of ''MIDI message'' that we want to remap

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

'''FAR 1.1:'''

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

* '''noteon/non''''':commands'' - Sets the commands executed for a ''note on'' ''MIDI message''
* '''noteoff''/nof'''''<nowiki/>'':commands'' - Sets the commands executed for a ''note off MIDI message''
* '''polyaftertouch/pat''''':commands'' - Sets the commands executed for a ''poly aftertouch MIDI message''
* '''channelaftertouch/cat''''':commands'' - Sets the commands executed for a ''channel aftertouch MIDI message''
* '''pitchbend/pb''''':commands'' - Sets the commands executed for a ''pitch bend MIDI message''

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

2026-06-07T17:58:29Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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''
These variables will contain whatever data is relevant to the last midi message sent and will not stay relevant beyond the reception of the last 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

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

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf:82.5
</pre>Where '[irq]' denotes that the message returned is in the ''info request-''category, that it pertains to the command ''bcf'' / ''bw.pid.tf'' and has the value ''82.5''. Note that the returned ''command'' sent by an ''rqi''-command always uses the ''short name'' in order to preserve bandwidth. In the FAR 1.1 the return statement always returns the ''index'' of the ''module''(s) in question.

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

FAR 1.1:
rqi:controlbox.datareturn: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.

'''FAR < 1.1:'''

The ''command'' responsible for mapping ''command strings'' to different ''MIDI messages'' is ''midieventhandler'' or ''mev'' for short. The first ''parameter'' of ''mev'' is the type of ''MIDI message'' that we want to remap

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

'''FAR 1.1:'''

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

We can of course use the ''rqi''-command to check the current mapping, below we are asking what the current ''command string'' associated with the ''pitch bend'' ''MIDI message'' is<pre>
rqi:mev:pb
</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

2026-06-07T17:24:28Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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''
These variables will contain whatever data is relevant to the last midi message sent and will not stay relevant beyond the reception of the last 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

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

FAR 1.1:
rqi:bowingwheel.pid.targetfrequency
</pre>The return value would be something like<pre>
FAR < 1.1:
[irq]bcf:82.5

FAR 1.1:
[irq]bw[0].pid[0].tf: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

2026-06-07T17:21:37Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5

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

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

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:82.5+note*20

FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency: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''
These variables will contain whatever data is relevant to the last midi message sent and will not stay relevant beyond the reception of the last 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>
FAR < 1.1:
bowmotorrun:1, bowcontrolfrequency:"8.17579875 * pow(2, (1/12 * note))"

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

2026-06-07T08:29:58Z

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'', all 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''.

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

For instance, everything associated with the ''bowing wheel'' is now collected under "bowingwheel" ''module''. That in turn contains a "dcmotor" ''module'' which does direct control of the bowing motor, and it has a "pid" ''module'' that handles bow frequency.

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>FAR < 1.1:
bowmotorrun:1, bowcontrolfrequecy:82.5
FAR 1.1:
bowingwheel.dcmotor.run:1, bowingwheel.pid.targetfrequency:82.5</pre>We could also use the ''short names'' for the commands<pre>FAR < 1.1:
bmr:1,bcf:82.5
FAR 1.1:
bw.dcm.ru:1, bw.pid.tf: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.

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

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]]
}}