What Is It for?
This interface lets you control the Espressivo app in a similar way as a gamepad does. Pushing a button, pressing a trigger or moving a stick: All this can be achieved by a small number of human-readable commands.
How Do I Access the Interface?
You access the interface either by the User Datagram Protocol (UDP) or a Bluetooth connection.
User Datagram Protocol (UDP)
The User Datagram Protocol (UDP) enables a user to exchange messages between the Espressivo app and an external app. In the Server panel make sure that the server is accepting incoming messages. By default, the Espressivo app is using port 9999. To get a first impression you might use the Terminalapplication and enter:
nc -u localhost 9999
Using UDP is quite simple but when running over a wireless network you might occasionally encounter high latency values.
Bluetooth
Alternatively, you might want to communicate over Bluetooth. For this purpose you need to implement a Bluetooth Peripheral using a service id and characteristic id as shown below:
Characteristic Id:
| Service Id | DA040001-232F-49DB-82D1-7C476CC84122 |
| Characteristic Id | DA040002-232F-49DB-82D1-7C476CC84122 |
With Bluetooth latency will be around 10 to 20 ms which is acceptable for the intended purpose.
How Does It Do the Job?
First, your app has to register by entering a message similar to:
register name Terminal model App symbol terminal button 1 button 2 stick 1x stick 1y
If successfully registered, the controller panel will present a tab showing entries similar to this:
The registered controller as shown in the controller panel.
After assigning interface elements to musical actions, the application is ready to process incoming messages.
Note: If you pass a symbol parameter, make sure that it is the name of a valid SF Symbol.
When no longer needed, your app should unregister with this command:
unregister name Terminal
What Messages Can Be Sent?
Structure of a Message
The general structure of a message consists of an address specifier, followed by a command or a control element specifier and one ore more parameter values. The general syntax is:
@<name> <command> | <element> <id> <parameter>+
In the example above, the address is:
@Terminal
Control Element Messages
Once your app is registered you can send control element messages. The Espressivo app will accept messages for the following control interfaces elements:
- button
- trigger
- stick
- sensor
Each of these elements is further identified by a number or code.
Note: You are sending messages to an interface element rather than a musical element.
Button
A button is used to pass a single boolean value.
- A button is determined by index numbers 1…8
- A parameter value of 1 means a button is pressed
- A parameter value of 0 is for a released button
Example: @Terminal button 1 1
Trigger
A trigger is used for a single numerical value.
- A trigger is determined by index numbers 1…4
- Parameters values are in the range between 0 and 1
Example: @Terminal trigger 1 0.5
Stick
A stick is used for two independent numerical values.
- A stick is specified by an index and a direction
- Valid specifiers are 1x, 1y, 2x, 2y, …, 4x, 4y
- Parameters values are in the range between -1 and 1
Example: @Terminal stick 1y -0.2
Note: Two messages are required to describe the position of a stick.
Alternatively, you can use the stickxy command to pass an X and a Y value simultaneously.
Example: @Terminal stickxy 1 0.5 -0.2
Sensor
A sensor holds a 3D position.
- A sensor is described by three components, x, y, and z
- There is only one addressable sensor per device or app
- Parameters values are in the range between -1 and 1
Note: Three messages are required to fully describe a sensor value.
Example: @Terminal sensor x 0.234
To pass all three components at once use the sensorxyz key.
Example: @Terminal sensorxyz -0.1 0.2 0.5
Additional Messages
The following additional messages can be used:
- config
- loop
- battery
Config
The config message returns information about the assigned actions.
Example: @Terminal config
Depending on the assignments made in the Espressivo app you will get a message similar to this one:
@Terminal .config button 1 Start\/Stop button 2 Rewind
Your app might use this information to name the buttons, sticks or sensors, accordingly.
Note: The dot before the config message marks a message sent from the server.
Loop
The loop message can be used to estimate the network latency. The server just sends back a .loop message. It is the app’s responsibility to calculate the latency.
Battery
The message can be used to present the battery level [%].
Example: @Terminal battery 70
What Apps Do Exist?
Currently, the following app is available:
- MusicalConductor app for iOS devices
Note: This interface might change in future versions.