The Ekdahl FAR - Command reference

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:

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	[command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug]:[0|1]	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

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	[config|name]	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	[noteon|noteoff|pat|cc[:0-127]|cat|pb|pc]:[command string]	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 'cc' MIDI event the second parameter is the command string. For '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 'Omni' (the instrument responding to all channels)
midiallnotesoff	mano	[conditional (0|1)]	Clears the entire MIDI buffer of notes held and turns off any bowing

ADC / Control box commands

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:

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

Long name	Short name	Parameters	Description
bowpid	bpid	[conditional (0|1)]	Sets whether the 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

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	[mode (0|1)]	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

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

Long name	Short name	Parameters	Description
bowmotorrun	bmr	[(0|1)]	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

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	[conditional (0|1)]	Puts the bow pressure in the rest position
bowpressureengage	bpe	[conditional (0|1)]	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	[(0|1)]	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

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	[conditional (0|1)]	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

Long name	Short name	Parameters	Description
mutesetposition	msp	[position (0 - 65535)]	Sets the mute position, scaled by the mutefullmuteposition and muterestposition
mutefullmute	mfm	[conditional (0|1)]	Sets the mute in the full mute position
mutehalfmute	mhm	[conditional (0|1)]	Sets the mute in the half mute position
muterest	mr	[conditional (0|1)]	Sets the mute in the mute rest position
mutesavefull	msf	[conditional (0|1)]	Sets the full mute position to be equal to the current mute position
mutesavehalf	msh	[conditional (0|1)]	Sets the half mute position to be equal to the current mute position
mutesaverest	msr	[conditional (0|1)]	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	[conditional (0|1)]	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

Long name	Short name	Parameters	Description
bowactuatoradd	baa	none	Add new bow actuator
bowacutatorremove	bar	[actuator]	Removes the actuator given in the parameter
bowactuatorset	bas	[actuator]	Sets the current actuator to the number given in the parameter
bowactuatorload	bal	none	Loads data from the current actuator
bowactuatorsave	bas	none	Saves the bow pressure position rest, bow pressure position engage and bow pressure position max into the current actuator
bowactuatordata	bad	[actuator]:[engage]:[max]:[rest]:[id]	Sets the bow pressure position engage, bow pressure position max, bow pressure position rest and actuator id of the actuator given by the first parameter
bowactuatorcount	bac	none	Returns the number of saved actuators
bowactuatorid	bai	id	Sets the id of the current actuator

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.

Command language

Specifications