MQTT - API Bindings¶

Vom APT Repository¶

Die Bindings stehen in unserem APT Repository für Debian basierte Linux Distributionen bereit. Zuerst das APT Repository einrichten dann die Bindings installieren:

sudo apt install tinkerforge-mqtt

Das Debian Package installiert und startet auch den systemd Service tinkerforge_mqtt der die MQTT Bindings ausführt.

Dann ist auch schon alles bereit, um Beispiele testen zu können. Das Debian Package beinhaltet keine Beispiele. Diese sind als Teil der ZIP Datei der Bindings verfügbar.

Händische Installation¶

Die MQTT-Bindings können installiert werden, können aber auch ohne Installation verwendet werden.

Zur Installation wird die tinkerforge_mqtt Datei in einen Ordner kopiert der sich im PATH befindet. Das kann unter Linux und macOS folgender Ordner sein:

/usr/local/bin/

Unter Windows bietet sich der Scripts/ Ordner der Python Installation an:

C:\Python\Scripts\

Damit die Bindings unter Windows direkt aufgerufen werden können muss noch eine tinkerforge_mqtt.bat Datei im Scripts/ Ordner mit folgendem Inhalt angelegt werden:

@"C:\Python\python.exe" "C:\Python\Scripts\tinkerforge_mqtt" %*

Wenn sich die Python-Installation nicht im C:\Python\ Ordner befindet, dann ist natürlich der Inhalt der tinkerforge_mqtt.bat Datei entsprechend abzuändern.

MQTT-Topics¶

Die Struktur der MQTT-Topics ist wie folgt: [<GLOBAL_PREFIX>/]<OPERATION>/<DEVICE>[/<UID>]/<FUNCTION>[/<SUFFIX>]

[<GLOBAL_PREFIX>/] ist der globale Präfix aller Topics (Standardeinstellung: tinkerforge/). Er kann mit dem --global-topic-prefix Kommandozeilenargument geändert werden. Der Präfix kann verwendet werden um zwischen mehreren Instanzen der MQTT-Bindings zu unterscheiden. Außerdem kann er mehrere Topic-Levels beinhalten, zum Beispiel tinkerforge/wohnzimmer/sensoren. Wenn der konfiguriere Präfix nicht mit einem / endet, wird es von den Bindings eingefügt, es sei denn ein leerer Prefix wurde konfiguriert. Dann beginnen alle Topics mit der Operation. Dieses Vorgehen wird wegen möglichen Namenskonflikten nicht empfohlen. Außerdem ist zu beachten, dass / ein gültiger Präfix ist.

<OPERATION> ist der Typ der Anfrage. Dieser kann request, response, register oder callback sein. Die Bindings subscriben auf request- und register-Topics und publishen Antworten auf request- unter response-Topics, Antworten auf register- unter callback-Topics.

<DEVICE> ist der Typ des Gerätes mit dem interagiert werden soll. Dies kann der Name eines Bricks oder Bricklets in snake_case, oder ip_connection sein. Siehe die Dokumentation der Geräte für die genaue Schreibweise.

[/<UID>] ist die UID des Gerätes. Wenn das Gerät die ip_connection ist, muss die UID leer und ohne / sein, zum Beispiel .../ip_connection/enumerate.

<FUNCTION> ist die Funktion, die aufgerufen, oder das Callback, das registriert werden soll (in snake_case).

</[SUFFIX]> ist der optionale Suffix der an Antworten angehangen wird. Dieser kann verwendet werden, um Nachrichten zu filtern. Siehe hier für Details.

Ein typisches Request-Topic sieht aus wie folgt: tinkerforge/request/rgb_led_button_bricklet/Dod/get_color. Die Antwort auf diesen Request wird von den Bindungs unter tinkerforge/response/rgb_led_button_bricklet/Dod/get_color zurückgegeben.

Ein Callback-Registrierungs-Topic sieht aus wie folgt: tinkerforge/register/rgb_led_button_bricklet/Dod/button_state_changed. Durch subscriben von tinkerforge/callback/rgb_led_button_bricklet/Dod/button_state_changed wird jedes Mal, wenn der Button gedrückt, oder losgelassen wird, eine Nachricht empfangen.

MQTT-Payload¶

Jeglicher MQTT-Payload wird als JSON-Objekt enkodiert, dabei bildet fast jedes Feld auf einen Parameter oder Rückgabewert der Python-Bindings ab. Aufgetretene Fehler werden auf stdout geloggt, außerdem werden sie als _ERROR-Feld im JSON-Objekt zurückgegeben.

Falls die symbolische Ausgabe nicht durch das --no-symbolic-response Kommandozeilenargument deaktiviert wurde, werden Integer-Konstanten zu Strings übersetzt. Zum Beispiel gibt dann das button_state_changed-Callback des RGB-LED-Button-Bricklets {"state": "pressed"} anstelle von {"state:" 0} zurück.

Integer-Konstanten im Request-Payload können auch durch die zugehörigen Symbole ersetzt werden. Zum Beispiel ist es äquivalent, {"config": "show_heartbeat"} oder {"config": 2} auf das Thema tinkerforge/request/rgb_led_button_bricklet/Dod/set_status_led_config zu publishen.

Symbole für Konstanten sind dokumentiert, wenn sie verfügbar sind.

Callback-(De)registrierungen können entweder {"register": true/false} oder true/false als Payload haben.

Requests und Responses¶

Um eine Funktion eines Bricks oder Bricklets aufzurufen, muss eine Nachricht im JSON-Format im entsprechenden request-Topic gepublisht werden. Um zum Beispiel mit mosquitto_pub die Farbe des RGB LED Button Bricklets mit der UID Enx auf Gelb zu setzen, kann folgender Befehl verwendet werden:

mosquitto_pub -t tinkerforge/request/rgb_led_button_bricklet/Enx/set_color -m '{"red":255, "green":127, "blue":0}'

Funktionen geben Werte unter response-Topics zurück. Folgendermaßen kann die aktuelle Farbe des selben Bricklets abgefragt werden:

mosquitto_sub -t tinkerforge/response/rgb_led_button_bricklet/Enx/get_color
mosquitto_pub -t tinkerforge/request/rgb_led_button_bricklet/Enx/get_color -m ''

Auch aufgetretene Fehler werden unter response-Topics gepublisht, zum Beispiel wird, falls ein Parameter fehlt:

mosquitto_sub -t tinkerforge/response/rgb_led_button_bricklet/Enx/set_color
mosquitto_pub -t tinkerforge/request/rgb_led_button_bricklet/Enx/set_color -m '{"red":255, "blue":0}'

die Nachricht:

{"_ERROR": "The arguments ['green'] where missing for a call of set_color of device Enx of type rgb_led_button_bricklet."}

auf dem Topic tinkerforge/response/rgb_led_button_bricklet/Enx/set_color zurückgegeben. Fehler werden auch auf der Standardausgabe der Bindings ausgegeben.

Callbacks¶

Callbacks können auf register-Topics registriert werden:

mosquitto_pub -t tinkerforge/register/rgb_led_button_bricklet/Enx/button_state_changed -m 'true'

und werden auf den entsprechenden callback-Topics ausgelöst:

mosquitto_sub -t tinkerforge/callback/rgb_led_button_bricklet/Enx/button_state_changed

gibt Nachrichten der Form:

{"state": 0}
{"state": 1}

zurück, wenn der Taster gedrückt und losgelassen wird.

Um ein Callback zu deregistrieren, kann als Payload false statt true verwendet werden. Außerdem ist es möglich, stattdessen {"register":  true} und {"register": false} zu verwenden.

Die Callback-Konfiguration funktioniert analog zu den anderen Bindings. Wenn ein Callback aktiviert und/oder konfiguriert werden muss, müssen folgende Schritte durchgeführt werden:

• Subscriben des callback-Topics
• Publishen der Registrierung auf das register-Topic
• Publishen der Konfiguration der Callback-Eigenschaften wie z.B. der Periode
• Publishen der Aktivierung des Callbacks über das request-Topic

Um alle Callbacks der Devices und IP-Connection zu deregistrieren, kann folgendes Topic benutzt werden:

mosquitto_pub -t tinkerforge/request/bindings/reset_callbacks -m ''

Laden initialer Nachrichten aus einer Datei¶

Um die Konfiguration zu vereinfachen, können Nachrichten, die einmal beim Start der Bindings verarbeitet werden sollen, aus einer Datei geladen werden. Hierzu wird das Kommandozeilenargument --init-file /pfad/zur/datei verwendet. Mit dieser Datei können z.B. Callbacks konfiguriert und registriert werden. Das Dateiformat entspricht einem JSON-Objekt, dessen Attributsnamen MQTT-Topics sind. Die Attributswerte werden als weitere JSON-Objekte, die dem MQTT-Payload entsprechen, behandelt. Folgendes Beispiel zeigt eine Datei, die das all_data-Callback eines IMU Brick 2.0 registriert und dessen Periode auf 100ms konfiguriert:

{
    "tinkerforge/register/imu_v2_brick/XXYYZZ/all_data": {"register": true},
    "tinkerforge/request/imu_v2_brick/XXYYZZ/set_all_data_period": {"period": 100}
}

Seit Version 2.0.8 kann zwischen Nachrichten, die vor oder nach dem Verbindungsaufbau zum Brick Daemon, der Wifi oder der Ethernet Extension verarbeitet werden sollen, unterschieden weden. Das erlaubt es, Callback zu registrieren, bevor eine Verbindung besteht (zum Beispiel das connected-Callback der IP-Connection). Die Syntax ist wie folgt:

{
    "pre_connect": {
        "tinkerforge/register/ip_connection/connected": {"register": true},
        "tinkerforge/register/ip_connection/enumerate": {"register": true}
    },
    "post_connect": {
        "tinkerforge/request/ip_connection/enumerate": ""
    }
}

Diese Datei registriert das connected- und enumerate-Callback vor dem Verbindungsaufbau und löst sofort danach eine Enumerierung aus.

Init-Dateien, die die alte Syntax ohne pre/post_connect verwenden, werden ausgeführt, nachdem die Verbindung hergestellt wurde.

Topic-Präfixe¶

Die Bindings können mit dem --global-topic-prefix-Parameter auf einen anderen globalen Präfix konfiguriert werden. Der Präfix kann beispielsweise verwendet werden, um mehrere Binding-Instanzen die mit dem selben Broker verbunden sind zu trennen. Der Präfix kann beliebig lang sein, zum Beispiel tf/instance/1/foo/bar.

Topic-Suffixe¶

Die Bindings unterstützen beliebige Suffixe pro Topic. Mit diesen können zum Beispiel alle Bricks/Bricklets in einem Raum mit einer Raumnummer markiert werden:

mosquitto_pub -t tinkerforge/register/rgb_led_button_bricklet/Enx/button_state_changed/room/1 -m 'true'
mosquitto_pub -t tinkerforge/register/rgb_led_button_bricklet/gBs/button_state_changed/room/2 -m 'true'
mosquitto_pub -t tinkerforge/register/rgb_led_button_bricklet/Dod/button_state_changed/room/1 -m 'true'

Um alle Callbacks von Bricks/Bricklets in Raum 1 zu empfangen, kann auf folgendes Topic subscribt werden:

mosquitto_sub -t tinkerforge/callback/+/+/+/room/1

Es werden dann Callback-Nachrichten von Enx und Dod empfangen, aber nicht von gBs.

Um alle Nachrichten zu erhalten kann sich auf:

mosquitto_sub -t tinkerforge/callback/#
mosquitto_sub -t tinkerforge/response/#

subscribt werden.