Shell - Multi Touch Bricklet

Dies ist die Beschreibung der Shell API Bindings für das Multi Touch Bricklet. Allgemeine Informationen über die Funktionen und technischen Spezifikationen des Multi Touch Bricklet sind in dessen Hardware Beschreibung zusammengefasst.

Eine Installationanleitung für die Shell API Bindings ist Teil deren allgemeine Beschreibung.

Beispiele

Der folgende Beispielcode ist Public Domain (CC0 1.0).

Simple

Download (example-simple.sh)

1
2
3
4
5
6
7
#!/bin/sh
# Connects to localhost:4223 by default, use --host and --port to change this

uid=XYZ # Change XYZ to the UID of your Multi Touch Bricklet

# Get current touch state
tinkerforge call multi-touch-bricklet $uid get-touch-state

Callback

Download (example-callback.sh)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
#!/bin/sh
# Connects to localhost:4223 by default, use --host and --port to change this

uid=XYZ # Change XYZ to the UID of your Multi Touch Bricklet

# Handle incoming touch state callbacks
tinkerforge dispatch multi-touch-bricklet $uid touch-state &

echo "Press key to exit"; read dummy

kill -- -$$ # Stop callback dispatch in background

API

Mögliche Exit Codes für alle tinkerforge Befehle sind:

  • 1: Unterbrochen (Ctrl+C)
  • 2: Syntaxfehler
  • 21: Python 2.5 oder neuer wird benötigt
  • 22: Python argparse Modul fehlt
  • 23: Socket-Fehler
  • 24: Andere Exception
  • 25: Ungültiger Platzhalter in Format-String
  • 26: Authentifizierungsfehler
  • 201: Timeout ist aufgetreten
  • 209: Ungültiger Argumentwert
  • 210: Funktion wird nicht unterstützt
  • 211: Unbekannter Fehler

Befehlsstruktur

Allgemeine Optionen des call und des dispatch Befehls sind hier zu finden. Im Folgenden wird die spezifische Befehlsstruktur dargestellt.

tinkerforge call multi-touch-bricklet [<option>..] <uid> <function> [<argument>..]
Parameter:
  • <uid> – Typ: String
  • <function> – Typ: String

Der call Befehl wird verwendet um eine Funktion des Multi Touch Bricklet aufzurufen. Der Befehl kennt mehrere Optionen:

  • --help zeigt Hilfe für den spezifischen call Befehl an und endet dann
  • --list-functions zeigt eine Liste der bekannten Funktionen des Multi Touch Bricklet an und endet dann
tinkerforge dispatch multi-touch-bricklet [<option>..] <uid> <callback>
Parameter:
  • <uid> – Typ: String
  • <callback> – Typ: String

Der dispatch Befehl wird verwendet um eingehende Callbacks des Multi Touch Bricklet abzufertigen. Der Befehl kennt mehrere Optionen:

  • --help zeigt Hilfe für den spezifischen dispatch Befehl an und endet dann
  • --list-callbacks zeigt eine Liste der bekannten Callbacks des Multi Touch Bricklet an und endet dann
tinkerforge call multi-touch-bricklet <uid> <function> [<option>..] [<argument>..]
Parameter:
  • <uid> – Typ: String
  • <function> – Typ: String

Abhängig von der Art der aufzurufenden <function> kennt diese verschiedene Optionen. Alle Funktionen kennen die folgenden Optionen:

  • --help zeigt Hilfe für die spezifische <function> an und endet dann

Getter-Funktionen kennen zusätzlich die folgenden Optionen:

  • --execute <command> Shell-Befehl der für jede eingehende Antwort ausgeführt wird (siehe den Abschnitt über Ausgabeformatierung für Details)

Setter-Funktionen kennen zusätzlich die folgenden Optionen:

  • --expect-response fragt Antwort an und wartet auf diese

Mit der --expect-response Option für Setter-Funktionen können Timeouts und andere Fehlerfälle auch für Aufrufe von Setter-Funktionen detektiert werden. Das Gerät sendet dann eine Antwort extra für diesen Zweck. Wenn diese Option für eine Setter-Funktion nicht angegeben ist, dann wird keine Antwort vom Gerät gesendet und Fehler werden stillschweigend ignoriert, da sie nicht detektiert werden können.

tinkerforge dispatch multi-touch-bricklet <uid> <callback> [<option>..]
Parameter:
  • <uid> – Typ: String
  • <callback> – Typ: String

Der abzufertigende <callback> kennt mehrere Optionen:

  • --help zeigt Hilfe für den spezifische <callback> an und endet dann
  • --execute <command> Shell-Befehlszeile der für jede eingehende Antwort ausgeführt wird (siehe den Abschnitt über Ausgabeformatierung für Details)

Grundfunktionen

tinkerforge call multi-touch-bricklet <uid> get-touch-state
Ausgabe:
  • state – Typ: Int, Wertebereich: [0 bis 216 - 1]

Gibt den aktuellen Tastzustand zurück. Der Zustand ist als ein Bitfeld repräsentiert.

Bits 0 bis 11 repräsentieren die 12 Elektroden und Bit 12 repräsentiert die Proximity (Nähe).

Wird eine Elektrode berührt, ist das korrespondierende Bit true. Wenn eine Hand oder vergleichbares in der Nähe der Elektroden ist wird Bit 12 auf true gesetzt.

Beispiel: Der Zustand 4103 = 0x1007 = 0b1000000000111 bedeutet dass die Elektroden 0, 1 und 2 berührt werden und das sich etwas in der nähe der Elektroden befindet.

Das Proximity Bit wird ab einer Distanz von ca. 1-2cm aktiviert. Eine Elektrode wird schon als berührt gezählt wenn ein Finger sie beinahe berührt. Dadurch ist es möglich ein Stück Papier oder Folie über die Elektrode zu kleben um damit ein Touchpanel mit einem professionellen Aussehen zu bauen.

tinkerforge call multi-touch-bricklet <uid> recalibrate
Ausgabe:
  • keine Ausgabe

Rekalibriert die Elektroden. Rufe diese Funktion auf wenn die Elektroden verändert oder bewegt wurden.

tinkerforge call multi-touch-bricklet <uid> set-electrode-config <enabled-electrodes>
Parameter:
  • <enabled-electrodes> – Typ: Int, Wertebereich: [0 bis 216 - 1]
Ausgabe:
  • keine Ausgabe

Aktiviert/deaktiviert Elektroden mit einem Bitfeld (siehe get-touch-state).

True aktiviert eine Elektrode, false deaktiviert eine Elektrode. Eine deaktivierte Elektrode hat immer den Zustand false. Wenn nicht alle Elektroden gebraucht werden können die ungebrauchten deaktiviert werden.

Wir empfehlen das Proximity Bit (Bit 12) zu deaktivieren wenn das Proximity-Feature nicht benötigt wird. Das verringert den Datenverkehr der durch den touch-state Callback ausgelöst wird.

Eine deaktivierte Elektrode verringert zusätzlich den Stromverbrauch.

Standardwert: 8191 = 0x1FFF = 0b1111111111111 (alle Elektroden aktiviert)

tinkerforge call multi-touch-bricklet <uid> get-electrode-config
Ausgabe:
  • enabled-electrodes – Typ: Int, Wertebereich: [0 bis 216 - 1]

Gibt die Elektrodenkonfiguration zurück, wie von set-electrode-config gesetzt.

tinkerforge call multi-touch-bricklet <uid> set-electrode-sensitivity <sensitivity>
Parameter:
  • <sensitivity> – Typ: Int, Wertebereich: [0 bis 255]
Ausgabe:
  • keine Ausgabe

Setzt die Empfindlichkeit der Elektrode. Eine Elektrode mit einer hohen Empfindlichkeit registriert eine Berührung früher als eine Elektrode mit einer niedrigen Empfindlichkeit.

Wenn eine große Elektrode verwendet wird sollte die Empfindlichkeit verringert werden, da eine größere Fläche aufgeladen werden kann. Wenn eine Elektrode aus größerem Abstand aktivierbar seien soll, muss die Empfindlichkeit vergrößert werden.

Nachdem eine neue Empfindlichkeit gesetzt wurde, macht es Sinn recalibrate aufzurufen damit die Elektroden mit der neu definierten Empfindlichkeit kalibriert werden.

Der zulässige Wertebereich für den Empfindlichkeitswert ist 5-201.

Der voreingestellte Empfindlichkeitswert ist 181.

tinkerforge call multi-touch-bricklet <uid> get-electrode-sensitivity
Ausgabe:
  • sensitivity – Typ: Int, Wertebereich: [0 bis 255]

Gibt die aktuelle Empfindlichkeit zurück, wie von set-electrode-sensitivity gesetzt.

Fortgeschrittene Funktionen

tinkerforge call multi-touch-bricklet <uid> get-identity
Ausgabe:
  • uid – Typ: String, Länge: bis zu 8
  • connected-uid – Typ: String, Länge: bis zu 8
  • position – Typ: Char
  • hardware-version – Typ: Int Array, Länge: 3, Wertebereich: [0 bis 255]
  • firmware-version – Typ: Int Array, Länge: 3, Wertebereich: [0 bis 255]
  • device-identifier – Typ: Int, Wertebereich: [0 bis 216 - 1]

Gibt die UID, die UID zu der das Bricklet verbunden ist, die Position, die Hard- und Firmware Version sowie den Device Identifier zurück.

Die Position kann 'a', 'b', 'c' oder 'd' sein.

Eine Liste der Device Identifier Werte ist hier zu finden. 

Callbacks

Callbacks können registriert werden um zeitkritische oder wiederkehrende Daten vom Gerät zu erhalten:

tinkerforge dispatch multi-touch-bricklet <uid> example

Die verfügbaren Callbacks werden weiter unten beschrieben.

Bemerkung

Callbacks für wiederkehrende Ereignisse zu verwenden ist immer zu bevorzugen gegenüber der Verwendung von Abfragen. Es wird weniger USB-Bandbreite benutzt und die Latenz ist erheblich geringer, da es keine Paketumlaufzeit gibt.

tinkerforge dispatch multi-touch-bricklet <uid> touch-state
Ausgabe:
  • state – Typ: Int, Wertebereich: [0 bis 216 - 1]

Gibt den aktuellen Tastzustand zurück, siehe get-touch-state für mehr Informationen über den Zustand.

Dieser Callback wird ausgelöst, wenn sich ein Tastzustand ändert.