Software API 1.0 Provider

Mit der "Software API" hat NeuroomNet einen Dienst (Provider) zur Anbindung generischer Komponenten über allgemeine Schnittstellen wie TCP erhalten. Im aktuellen Stand (1.0) ist hierbei zunächst die Schnittstelle TCP implementiert, weitere folgen ggf. in der Zukunft.

Allgemeines Kommunikationsmodell

Die Software API basiert auf einem wohldefinierten Kommunikationsmodell, bei dem Datenpakete über eine Schnittstelle ausgetauscht werden - für die genauen Abläufe siehe Kommunikationsprotokoll. Dabei muss man zwischen den physikalischen Datenaustausch (TCP/IP Datenstrom, UDP/IP Pakete, Web Sockets, HTTP, ...) und dem Protokollschema (JSON Zeichenkette, Zeichenkette, Binärdaten, ...) unterscheiden.

Viele der aufgeführten Schnittstellen arbeiten bereits mit dem Austausch von Paketen und kommen dem Kommunikationsmodell der NeuroomNet Software API entgegen. Die wichtigste Ausnahme ist TCP/IP, das auf einem Datenstrom basiert, der von Natur aus erst einmal keine feinere Unterteilung aufweist. In der aktuellen Version 1.0 der Software API wird TCP (ursprünglich unter anderem zu Test- / Evaluierungszwecken) zur Kommunikation verwendet.

Pakete und Datenströme

Für die Übertragung von Paketen der Software API über einen Datenstrom wird das Paket in eine Zeichenkette gewandelt und vor der Übertragung den Nutzdaten vier Bytes mit der Größe des Paketes in Bytes vorangestellt. Die Übertragung erfolgt Little Endian, sprich das erste Byte ist das unterste Byte der Größe (modulo 256) und so weiter. Vorerst ist das oberste (vierte und letzte Byte) reserviert und muss immer 0 sein - spätere Erweiterungen der Software API werden dieses eventuell zur Übermittelung besonderer Einstellungen verwenden. Die maximale Größe eines Paketes ist damit 16.777.215 Bytes, was aber mehr als ausreichend sein sollte.

Pakete als Zeichenketten

Auf der nächsten Ebene wird ein Paket letztlich immer als Bytefolge übermittelt. Für viele Anbindungen wird dies einfach die originale Beschreibung des Pakets als JavaScript Objekt sein - JSON.stringify. Für sehr einfache Komponenten kann die Auswertung von JSON aber eine gewisse Herausforderung sein, daher bietet der Dienst auch eine alternative Codierung als Zeichenkette, die für TCP/IP Verbindungen genutzt wird - eine Umschaltung pro Komponente ist zurzeit nicht möglich, grundsätzlich für spätere Versionen der API aber angedacht. In dieser Codierung würde ein JSON der Art { "command": "DoAction", "id": "explode" } als Zeichenkette "DoAction**<TAB>**explode" übertragen. <TAB> ist der "Tabulator" - ein einzelnes Zeichen mit dem Code 0x09 (oder '\t'). Die genaue Codierung ist bei den entsprechenden Befehlen gesondert erläutert - siehe etwa Codierung String bei DoAction. In allen Fällen werden Zeichen in der UTF-8 Notation ohne gesonderten Präfix (BOM Header) übermittelt.

Anmelden von Komponenten

Die Software API unterstützt ausschließlich sogenannte aktive Komponenten. Eine aktive Komponente verbindet sich selbstständig mit dem NeuroomNet Software API Server über das entsprechende Protokoll. Aktuell werden folgende physikalische Zugänge angeboten:

• TCP/IP (Protokollname tcp) mit Codierung String: Port 15400

Der auf NeuroomNet-Seite verwendete Port (Default = 15400) lässt sich konfigurativ auf eine andere Portnummer ändern.

Die Komponente stellt eine entsprechende Verbindung her und wartet dann auf Pakete des Dienstes, die dann geeignet beantwortet werden müssen. In der Beschreibung der Komponente sollte immer als id ein global eindeutiger Name der Komponente übermittelt werden. Bleibt dieser leer, wird er auf auf die TCP/IP Adresse des Rechners fixiert, der die Komponente anbietet. Diese Kennung ist in NeuroomNet global eindeutig und kann auch nicht mehr verändert werden - eine andere id ist aus Sicht von NeuroomNet eine andere Komponente. Das bedeutet aber insbesondere auch, dass ohne Meldung eines eindeutigen Namens pro Rechner (Adresse) nur eine Komponente ausgeführt werden kann - das ist in vielen Fällen unproblematisch, etwa bei einem RFID Lesegerät.

Stellt eine aktive Komponente fest, dass die Verbindung zum Dienst unterbrochen wurde (etwa weil dieser neu gestartet wurde), so muss diese selbstverständlich zeitnah neu aufgebaut werden. Dabei sind allerdings Maßnahmen zur Beschränkung der Netzlast zu berücksichtigen - etwa Pausen zwischen Wiederholungen des Anmeldeversuchs. Selbstverständlich gilt dies auch bei der Erstanmeldung: ist zu diesem Zeitpunkt der Dienst nicht erreichbar, so muss die Anmeldung erneut probiert werden, bis sie erfolgreich war.

Ein praktisches Beispiel zur Verwendung der Software-API befindet sich hier: Link.