The Ekdahl FAR - Command reference V1.1

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

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

Long name	Short name	Parameters	Description
version	ver	-	Gets the current firmware version
debugprint	dp	command|usb|hardware|undefined|priority|error|inforequest|expressionparser|debug:1|0	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	1|0	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:

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

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

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.

Long name	Short name	Parameters	Description
speedmode	sm	0|1	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	0|1	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

Long name	Short name
bowpressure	bp
dcmotor	dcm
pid	pid
harmonicserieshandler	hsh

The "bowpressure"-module handles the pressure of the bowing wheel against the string. The "bowpressure"-module has the following commands

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	0|1	Puts the bow pressure in the rest position, conditional
engage	en	0|1	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	0|1	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 parameters 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 handles the direct raw control of the bowing motor and handles the reporting back of the current speed. It has the following commands:

Long name	Short name	Parameters	Description
run	ru	0|1	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 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 article. The module has the following commands:

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