The Ekdahl FAR - Command language

From KNAS Wiki
Revision as of 01:25, 22 January 2025 by Knaadmin (talk | contribs)
Jump to navigation Jump to search

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, bowmotorruns 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).

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:

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
  • e, exp(x), fac(x), ln(x), log10(x), log20(x), ncr(x,y), npr(x,y), pi, pow(x,y), sqrt(x)
  • cos(x), sin(x), tan(x)
  • cosh(x), sinh(x), tanh(x)
Retrieved from "http://knasmusic.com/wiki/index.php?title=The_Ekdahl_FAR_-_Command_language&oldid=1456"