MQTT - IP Connection

Dies ist die Beschreibung der MQTT API Bindings für die IP Connection. Die IP Connection kümmert sich um die Kommunikation zwischen einem Brick Daemon oder einer WIFI/Ethernet Extension. Bevor Bricks und Bricklets über deren API angesprochen werden können muss eine IP Connection erzeugt und die TCP/IP Verbindung hergestellt werden.

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

Beispiele

Der folgende Beispielcode ist Public Domain (CC0 1.0).

Enumerate

Download (example_enumerate.txt)

1
2
3
4
5
6
setup:
    # Handle incoming enumerate callbacks
    subscribe to tinkerforge/callback/ip_connection/enumerate
    publish '{"register": true}' to tinkerforge/register/ip_connection/enumerate # Register enumerate callback 
    
    publish '' to tinkerforge/request/ip_connection/enumerate # Trigger enumeration

Authenticate

Download (example_authenticate.txt)

1
2
3
4
5
6
7
8
# Start the MQTT-Bindings executable with the --ipcon-auth-secret "[YOUR SECRET HERE]" flag to use authentication.

setup:
    # Handle incoming enumerate callbacks
    subscribe to tinkerforge/callback/ip_connection/enumerate
    publish '{"register": true}' to tinkerforge/register/ip_connection/enumerate # Register enumerate callback

    publish '' to tinkerforge/request/ip_connection/enumerate # Trigger enumeration

API

Grundfunktionen

request/ip_connection/enumerate

Broadcast einer Enumerierungsanfrage. Alle Bricks und Bricklets werden mit einem Enumerate Callback antworten.

request/ip_connection/get_connection_state
Response-Payload:
  • connection_state -- int (hat Symbole)

Die folgenden Symbole sind für diese Funktion verfügbar:

für connection_state:

  • "disconnected" = 0: Keine Verbindung aufgebaut.
  • "connected" = 1: Eine Verbindung zum Brick Daemon oder der WIFI/Ethernet Extension ist aufgebaut.
  • "pending" = 2: IP-Connection versucht im Moment eine Verbindung aufzubauen.

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/ip_connection/enumerate
Request-Payload:
  • register -- bool
Response-Payload:
  • uid -- string
  • connected_uid -- string
  • position -- string
  • hardware_version -- [int,int,int]
  • firmware_version -- [int,int,int]
  • device_identifier -- int (hat Symbole)
  • enumeration_type -- int (hat Symbole)
  • _display_name -- string

Ein Callback für dieses Event kann durch Senden des Payloads "true" an das .../register/ip_connection/enumerate[/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/ip_connection/enumerate[/SUFFIX]-Topic veröffentlicht.

Dieses Callback empfängt ein JSON-Objekt mit acht Feldern:

  • uid: Die UID des Bricks/Bricklets.
  • connected_uid: Die UID des Gerätes mit dem der Brick/das Bricklet verbunden ist. Für ein Bricklet ist dies die UID des Bricks oder Bricklets mit dem es verbunden ist. Für einen Brick ist es die UID des untersten Bricks im Stapel. Der unterste Master Brick hat die Connected-UID "0". Mit diesen Informationen sollte es möglich sein die komplette Netzwerktopologie zu rekonstruieren.
  • position: Für Bricks: 0 - 8 (Position in Stapel). Für Bricklets: a - h (Position an Brick) oder i (Position des Raspberry Pi (Zero) HAT) oder z (Bricklet an Isolator Bricklet).
  • hardware_version: Major, Minor und Release Nummer der Hardwareversion.
  • firmware_version: Major, Minor und Release Nummer der Firmwareversion.
  • device_identifier: Eine Zahl, welche den Brick/Bricklet repräsentiert. Falls die symbolische Ausgabe nicht deaktiviert ist, wird diese auf den entsprechenden Gerätenamen in der Form, wie sie in Topics verwendet wird, gemappt.
  • enumeration_type: Art der Enumerierung.
  • _display_name: Der Anzeigenamen des Gerätes.

Die folgenden Symbole sind für diese Funktion verfügbar:

für device_identifier: siehe hier.

für enumeration_type:

  • "available" = 0: Gerät ist verfügbar (Enumerierung vom Benutzer ausgelöst: enumerate). Diese Enumerierungsart kann mehrfach für das selbe Gerät auftreten.
  • "connected" = 1: Gerät wurde neu verbunden (Automatisch vom Brick gesendet nachdem die Kommunikation aufgebaut wurde). Dies kann bedeuten, dass das Gerät die vorher eingestellte Konfiguration verloren hat und neu konfiguriert werden muss.
  • "disconnected" = 2: Gerät wurde getrennt (Nur bei USB-Verbindungen möglich). In diesem Fall haben nur uid und enumeration_type einen gültigen Wert.

Es sollte möglich sein Plug-and-Play-Funktionalität mit diesem Callback zu implementieren (wie es im Brick Viewer geschieht).

register/ip_connection/connected
Request-Payload:
  • register -- bool
Response-Payload:
  • connect_reason -- int (hat Symbole)

Ein Callback für dieses Event kann durch Senden des Payloads "true" an das .../register/ip_connection/connected[/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/ip_connection/connected[/SUFFIX]-Topic veröffentlicht.

Dieses Callback wird aufgerufen wenn die IP-Connection eine Verbindung zu einem Brick Daemon oder einer WIFI/Ethernet Extension aufgebaut hat.

Die folgenden Symbole sind für diese Funktion verfügbar:

für connect_reason:

  • "request" = 0: Verbindung aufgebaut nach Anfrage vom Benutzer.
  • "auto-reconnect" = 1: Verbindung aufgebaut durch Auto-Reconnect.
register/ip_connection/disconnected
Request-Payload:
  • register -- bool
Response-Payload:
  • disconnect_reason -- int (hat Symbole)

Ein Callback für dieses Event kann durch Senden des Payloads "true" an das .../register/ip_connection/disconnected[/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/ip_connection/disconnected[/SUFFIX]-Topic veröffentlicht.

Dieses Callback wird aufgerufen wenn die Verbindung der IP Connection zu einem Brick Daemon oder einer WIFI/Ethernet Extension getrennt wurde, mögliche Gründe sind:

Die folgenden Symbole sind für diese Funktion verfügbar:

für disconnect_reason:

  • "request" = 0: Trennung wurde vom Benutzer angefragt.
  • "error" = 1: Trennung aufgrund eines unlösbaren Problems.
  • "shutdown" = 2: Trennung wurde vom Brick Daemon oder WIFI/Ethernet Extension eingeleitet.