MQTT - Multi Touch Bricklet

Dies ist die Beschreibung der MQTT 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 MQTT API Bindings ist Teil deren allgemeine Beschreibung.

Beispiele

Der folgende Beispielcode ist Public Domain (CC0 1.0).

Callback

Download (example-callback.txt)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# Change XYZ to the UID of your Multi Touch Bricklet

setup:
    # Handle incoming touch state callbacks
    subscribe to tinkerforge/callback/multi_touch_bricklet/XYZ/touch_state
        if a message arrives:
            # message contains state as int
            set result_string to ""
            if bit 12 of state is set
                append "In proximity, " to result_string
            endif

            if bits 0 to 11 of state are not set
                append "No electrodes touched" to result_string
            elseif
                append "Electrodes " to result_string
                for i in 0..12
                    if bit i of state is set
                        append i and " " to result_string
                    endif
                endfor
            endif

            print result_string
        endif
    endsubscribe

    publish '{"register": true}' to tinkerforge/register/multi_touch_bricklet/XYZ/touch_state # Register touch_state callback

Simple

Download (example-simple.txt)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# Change XYZ to the UID of your Multi Touch Bricklet

setup:
    # Get current touch state
    subscribe to tinkerforge/response/multi_touch_bricklet/XYZ/get_touch_state
        if a message arrives:
            # message contains state as int
            set result_string to ""
            if bit 12 of state is set
                append "In proximity, " to result_string
            endif

            if bits 0 to 11 of state are not set
                append "No electrodes touched" to result_string
            elseif
                append "Electrodes " to result_string
                for i in 0..12
                    if bit i of state is set
                        append i and " " to result_string
                    endif
                endfor
            endif

            print result_string
        endif
    endsubscribe

    publish '' to tinkerforge/request/multi_touch_bricklet/XYZ/get_touch_state

API

Alle veröffentlichten Payloads an die und von den MQTT-Bindings sind im JSON Format.

Falls ein Fehler auftritt, veröffentlichen die Bindings ein JSON-Objekt, das die Fehlermeldung als _ERROR-Member enthält. Das Objekt wird auf dem zugehörigen Antwort-Topic veröffentlicht: .../response/... für .../request/... und .../callback/... für .../register/....

Grundfunktionen

request/multi_touch_bricklet/<UID>/get_touch_state
Anfrage:
  • keine Nutzdaten
Antwort:
  • state – Typ: int, Wertebereich: [0 bis 213 - 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.

request/multi_touch_bricklet/<UID>/recalibrate
Anfrage:
  • keine Nutzdaten
Antwort:
  • keine Antwort

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

request/multi_touch_bricklet/<UID>/set_electrode_config
Anfrage:
  • enabled_electrodes – Typ: int, Wertebereich: [0 bis 213 - 1], Standardwert: 213 - 1
Antwort:
  • keine Antwort

Aktiviert/deaktiviert Elektroden mit einem Bitfeld (siehe request/multi_touch_bricklet/<UID>/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 register/multi_touch_bricklet/<UID>/touch_state Callback ausgelöst wird.

Eine deaktivierte Elektrode verringert zusätzlich den Stromverbrauch.

Standardwert: 8191 = 0x1FFF = 0b1111111111111 (alle Elektroden und Proximity-Feature aktiviert)

request/multi_touch_bricklet/<UID>/get_electrode_config
Anfrage:
  • keine Nutzdaten
Antwort:
  • enabled_electrodes – Typ: int, Wertebereich: [0 bis 213 - 1], Standardwert: 213 - 1

Gibt die Elektrodenkonfiguration zurück, wie von request/multi_touch_bricklet/<UID>/set_electrode_config gesetzt.

request/multi_touch_bricklet/<UID>/set_electrode_sensitivity
Anfrage:
  • sensitivity – Typ: int, Wertebereich: [5 bis 201], Standardwert: 181
Antwort:
  • keine Antwort

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 request/multi_touch_bricklet/<UID>/recalibrate aufzurufen damit die Elektroden mit der neu definierten Empfindlichkeit kalibriert werden.

request/multi_touch_bricklet/<UID>/get_electrode_sensitivity
Anfrage:
  • keine Nutzdaten
Antwort:
  • sensitivity – Typ: int, Wertebereich: [5 bis 201], Standardwert: 181

Gibt die aktuelle Empfindlichkeit zurück, wie von request/multi_touch_bricklet/<UID>/set_electrode_sensitivity gesetzt.

Fortgeschrittene Funktionen

request/multi_touch_bricklet/<UID>/get_identity
Anfrage:
  • keine Nutzdaten
Antwort:
  • uid – Typ: string, Länge: bis zu 8
  • connected_uid – Typ: string, Länge: bis zu 8
  • position – Typ: char, Wertebereich: ["a" bis "h", "z"]
  • hardware_version – Typ: [int, ...], Länge: 3
    • 0: major – Typ: int, Wertebereich: [0 bis 255]
    • 1: minor – Typ: int, Wertebereich: [0 bis 255]
    • 2: revision – Typ: int, Wertebereich: [0 bis 255]
  • firmware_version – Typ: [int, ...], Länge: 3
    • 0: major – Typ: int, Wertebereich: [0 bis 255]
    • 1: minor – Typ: int, Wertebereich: [0 bis 255]
    • 2: revision – Typ: int, Wertebereich: [0 bis 255]
  • device_identifier – Typ: int, Wertebereich: [0 bis 216 - 1]
  • _display_name – Typ: string

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 ist 'a', 'b', 'c', 'd', 'e', 'f', 'g' oder 'h' (Bricklet Anschluss). Ein Bricklet hinter einem Isolator Bricklet ist immer an Position 'z'.

Eine Liste der Device Identifier Werte ist hier zu finden. Falls die symbolische Ausgabe nicht deaktiviert wurde, wird der Device Identifier auf den entsprechenden Namen im Format, welches die Topics verwenden, abgebildet.

Der Display Name enthält den Anzeigenamen des Multi Touch.

Callbacks

Callbacks können registriert werden um zeitkritische oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung kann mit dem entsprechenden .../register/...-Topic und einem optionalen Suffix durchgeführt werden. Mit diesem Suffix kann das Callback später deregistriert werden.

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.

register/multi_touch_bricklet/<UID>/touch_state
Registrierungsanfrage:
  • register – Typ: bool
Callback-Antwort:
  • state – Typ: int, Wertebereich: [0 bis 213 - 1]

Ein Callback für dieses Event kann durch Senden des Payloads "true" an das .../register/multi_touch_bricklet/<UID>/touch_state[/<SUFFIX>]-Topic hinzugefügt werden. Ein hinzugefügtes Callback kann durch Senden des Payloads "false" an das selbe Topic wieder entfernt werden. Um mehrere (De-)Registrierungen zu unterstützen, z.B. um Nachrichten filtern zu können, kann ein optionaler Suffix verwendet werden.

Wenn das Callback ausgelöst wird, wird dessen Payload für jeden Suffix auf dem entsprechenden .../callback/multi_touch_bricklet/<UID>/touch_state[/<SUFFIX>]-Topic veröffentlicht.

Gibt den aktuellen Tastzustand zurück, siehe request/multi_touch_bricklet/<UID>/get_touch_state für mehr Informationen über den Zustand.

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