Wozu dient sie?
Mit dieser Schnittstelle lässt sich die Espressivo-Applikation ähnlich wie mit einem Gamepad steuern. Schalter, Trigger und Sticks betätigen: All dies kann mit einer kleinen Anzahl von textbasierten Befehlen geschehen.
Wie kann ich dieses Interface verwenden?
Das Interface ist via das User Datagram Protocol (UDP) oder eine Bluetooth-Verbindung zugänglich.
User Datagram Protocol (UDP)
Das User Datagram Protocol (UDP) ermöglicht den Austausch von Befehlen zwischen der Espressivo-Applikation und einer externen App. Vergewissere dich, dass im Server-Panel der Server aktiviert ist. Standardmässig benutzt der integrierte UDP-Server den Port 9999. Benutze zum Beispiel die Terminal-Applikation, um einen ersten Eindruck von der Funktionsweise zu erhalten. Gib dazu diesen Befehl ein:
nc -u localhost 9999
Die Verwendung von UDP ist relativ einfach, aber bei Verwendung via WLAN kann die Latenzzeit lang sein.
Bluetooth
Als Alternative gibt es die Kommunikation über Bluetooth. Zu diesem Zweck ist es nötig, eine Bluetooth-Peripherie zu implementieren, welche die folgenden Parameter für Service und Charakteristik verwendet:
| Service Id | DA040001-232F-49DB-82D1-7C476CC84122 |
| Characteristic Id | DA040002-232F-49DB-82D1-7C476CC84122 |
Die Latenzzeit für Bluetooth beträgt zwischen 10 und 20 ms, was für unsern Verwendungszweck ausreichend ist.
Wie funktioniert die Kommunikation?
Registriere dein Programm mit einem Befehl wie diesem:
register name Terminal model App symbol terminal button 1 button 2 stick 1x stick 1y
Falls alles geklappt hat, sollte im Controller-Panel ein Tab mit etwa diesem Inhalt erscheinen:
Der registrierte Controller im Controller-Panel.
Nachdem die musikalischen Aktionen den Bedienungselementen zugeordnet worden sind, sollte das Programm eintreffende Befehle abarbeiten können.
Beachte: Falls du den symbol-Parameter verwendest, sollte der Name ein existierendes SF-Symbol bezeichnen.
Wenn das Interface nicht mehr benötigt wird, kannst du diesen Befehl verwenden:
unregister name Terminal
Welche Befehle stehen zur Verfügung?
Aufbau der Befehle
Der generelle Aufbau besteht aus einer Adressangabe, gefolgt von einem Befehl oder einem Interface-Elemente mit dazugehörigen Parametern. Die Syntax lautet:
@<name> <command> | <element> <id> <parameter>+
Im obigen Beispiel wird die Adresse so bezeichnet:
@Terminal
Befehle für Bedienungselemente
Wenn dein Programm registriert ist, kannst du Befehle an die Bedienungselemente senden. Die Espressivo-Applikation akzeptiert die folgenden Elemente:
- button
- trigger
- stick
- sensor
Jedes dieser Elemente wird mit einer Zahl oder einem Code genau bezeichnet.
Beachte: Die Befehle betreffen stets Bedienungselemente und keine musikalischen Elemente.
Button
Ein Button wird mit einem boolschen Wert assoziiert.
- Jeder Schalter erhält einen Index zwischen 1 und 8
- Ein Parameterwert von 1 bezeichnet eine gedrückte Taste
- Ein Parameterwert von 0 bezeichnet einen losgelassenen Schalter
Beispiel: @Terminal button 1 1
Trigger
Ein Trigger wird für einen kontinuierlichen nummerischen Wert verwendet.
- Trigger erhalten Indizes zwischen 1 und 4
- Die Parameterwerte liegen zwischen 0 und 1
Beispiel: @Terminal trigger 1 0.5
Stick
Ein Stick wird für zwei unabhängige nummerische Werte verwendet.
- Jeder Stick wird mit einem Index und einer Richtung bezeichnet
- Gültige Angaben sind: 1x, 1y, 2x, 2y, …, 4x, 4y
- Die Parameterwerte liegen zwischen -1 und 1
Beispiel: @Terminal stick 1y -0.2
Beachte: Ein Stick benötigt zwei Befehle.
Alternativ dazu gibt es den Befehl stickxy, mit welchem die x- und y-Werte gleichzeitig übermittelt werden.
Beispiel: @Terminal stickxy 1 0.5 -0.2
Sensor
Ein Sensor bezeichnet ein 3-D-Element.
- Ein Sensor wird durch drei Komponenten erfasst: x, y und z
- Es gibt nur einen Sensor pro Gerät
- Die Parameterwerte liegen zwischen -1 und 1
Beachte: Für einen Sensor werden insgesamt drei Befehle benötigt.
Alternativ dazu gibt es den Befehl sensorxyz, mit welchem die x-, y- und z-Werte gleichzeitig übermittelt werden.
Beispiel: @Terminal sensorxyz -0.2 0.1 0.0
Weitere Befehle
Diese folgenden Befehle stehen zusätzlich zur Verfügung:
- config
- loop
- battery
Config
Der config-Befehl gibt Informationen zu den assoziierten Aktionen zurück.
Beispiel: @Terminal config
Je nach Einstellungen in der Espressivo-Applikation erfolgt eine Rückmeldung mit etwa folgendem Inhalt:
@Terminal .config button 1 Start\/Stopp button 2 Zum Anfang
Diese Angaben können verwendet werden, um die Schalter, Trigger, Sticks und den Sensor korrekt zu beschriften.
Beachte: Der vorangestellte Punkt steht für einen Befehl, der vom Server ausgeht.
Loop
Der Loop-Befehl kann für die Abschätzung der Latenzzeit verwendet werden. Der Server schickt den Befehl .loop zurück. Für die Berechnung der Laufzeit ist die App zuständig.
Battery
Dieser Befehl ermöglicht die Anzeige der Batterieladung [%].
Beispiel: @Terminal battery 70
Welche Apps existieren?
Zur Zeit ist die folgende App verfügbar:
- Espressivo-App für iOS-Geräte
Beachte: Das Interface kann sich in Zukunft noch ändern.