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.
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
adccommandmap	acm	[channel]:[command string]	Sets the command string associated with the analog-to-digital converter channel of the Control box
adcdefaults	acd	none	Sets all command strings associated with all analog-to-digital converter channels to their default values
adcread	adcr	[channel]:[return only: value]	Returns the last value read by the analog-to-digital converter of the Command box on the channel given. This value is sent automatically any time a change in data is read
adcsettings	adcs	[channel]:[averages]:[interrupterrorthreshold]:[continuouserrorthreshold]:[continuoustimeout]	Sets the settings for the averager used for the given Control box analog-to-digital channel. Averages denote number of values read and averaged, interrupterrorthreshold sets the value change required for the Control box to report a new value. The continuouserrorthreshold and continuoustimeout are used to allow for continuous changes. See the firmware for more information
expressionparserevaluate	epev	[expression]	Evaluates the given expression and returns the calculated value. Used for debugging
testadclatency	tal	[value (0 - 65535)]	Debugging command to test ADC latency
testadclatencyreturn	talr	none	Stops ADC latency testing started with tal
testadcminmac	tamm	[channel]	Debugging command to test the min/max value for a given channel

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

Long name	Short name	Parameters	Description
bow	bow	[bow (0)]	Sets the current bow. This command is intended for future versions of the Ekdahl FAR that may have more than one bow per string module. Currently '0' is the only valid parameter
bowpid	bpid	[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
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
bowharmonicseries	bhs	[series]	Sets the current harmonic series
bowharmonicserieslist	bhsl	[(set only) series]:[(set only) name]:[ratios]	Sets all ratios and the name of the harmonic list in the given series. There can be any number of ratio-parameters and this effectively sets the number of harmonics per octave. If required, empty harmonic lists will be added until slot is a valid number. On return, only returns ratios of the current harmonic list (takes no parameters)
bowharmonicseriesratio	bhsr	[harmonic]:[ratio]	Sets the ratio of the given harmonic number in the current harmonic series. Will increase the number of ratios in the series if needed
bowharmonicseriesratioremove	bhsrr	[ratio]	Removes the ratio given, will move all ratios with a higher harmonic number in the series. Cannot remove all ratios
bowharmonicseriescount	bhsc	none	Returns the number of harmonic series and their names in the format ratios:name1:name2 [etc]
bowharmonicseriessave	bhss	[name]:[series]	Saves the current harmonic series into the slot given by the second parameter with the name give in the first parameter. Note that this command does not save it into flash memory
bowharmonicseriesremove	bhsrm	[series]	Removes the harmonic series given in the parameter. Shifts all series' with a higher series number
bowstatus	bs	none	Outputs debugging data. Deprecated
pickupstringfrequency	psf	none	Returns the fundamental frequency calculated from the current audio signal if, applicable
pickupaudiopeak	pap	none	Returns the peak amplitude of the current audio signal
pickupaudiorms	par	none	Returns the 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
bowcalibratestablethreshold	bcst	none	Sets the stable threshold value used

a

Command language

Specifications