The Ekdahl FAR - Command language

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 event occurs or a new CV / knob value is read, the commands associated with it will be internally sent. This can be things like "engage hammer" or "set the fundamental frequency" etc.

Some of the available commands are mainly used for calibrating and setting up the instrument and are usually saved into the instruments memory, these will be executed whenever the instrument is turned on.

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

Syntax

The commands are invoked using a plain text approach, most commands have both a long name and a short name which are interchangeable. A command may have one or more parameters associated with it, these parameters can be of different types; 16-bit numbers (values 0 - 65535), floating point numbers (values with decimals), booleans (0 for 'false', 1 for 'true') and strings (text). Some commands are conditional, meaning they will only execute if a parameter equates to '1' ('true').

The way commands are written in order to be executed is commandname:parameter1:parameter2:parameter3 [etc], several commands be executed in sequence by separating them with a comma (','), a bunch of commands strung together is called a command string. If for instance we would like to start the bowing wheel and set its frequency to 82.5 Hertz we could send the Ekdahl FAR the following command string

bowmotorrun:1, bowcontrolfrequecy:82.5

We could also use the short names for the commands

bmr:1,bcf:82.5

Both bowmotorrun and bowcontrolfrequency takes one parameter each, bowmotorrun is conditional and unless the first parameter is equal to '1' the motor will not start. The first parameter of bowcontrolfrequency sets the frequency of the bowing wheel, the instrument may not execute a command if it decides that the given parameters are outside of the working range or they are missing.

To test out a command you can send it directly to the Ekdahl FAR using the Console in the Configuration utility.

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

Variables, functions and equations

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

For instance, we can use the previous example and instead write our command string as follows

bowmotorrun:1,bowcontrolfrequency:82.5+note*20

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 e
• pi - Contains the constant 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 absolute value of x
• acos(x), asin(x), atan(x), atan2(x, y) - Returns the arc-cos, -sin, -tan and -tan2 of x
• atan2(x,y) - Returns the arctan2 of x, y
• floor(x), ceil(x) - Returns the floor and ceiling of x
• exp(x) - Returns the exponent of x
• fac(x) - Returns the factorial of x
• ln(x) - Returns the natural logarithm of x
• log10(x), log20(x) - Returns the logarithm of x using base 10 and 20 respectively
• ncr(x,y), npr(x,y) - Functions to calculate combinations and permutations
• pow(x,y) - Returns x^y
• sqrt(x) - Returns the square root of x
• cos(x), sin(x), tan(x) - Returns the cos, sin and tan of x
• cosh(x), sinh(x), tanh(x) - Returns the 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 deadband of x with the threshold of y

Functions can be readily used in a command string

bmr:1,bcf:"8.17579875 * pow(2, (1/12 * note))"

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 messages of [irq]commandname:parameter1 [etc] so that it can be used by a receiving software to keep track of parameter changes