Deutsch
English
Menu

Java - IP Connection

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

Beispiele

Der folgende Beispielcode ist Public Domain (CC0 1.0).

Enumerate

Download (ExampleEnumerate.java)

 1import com.tinkerforge.IPConnection;
 2
 3public class ExampleEnumerate {
 4    private static final String HOST = "localhost";
 5    private static final int PORT = 4223;
 6
 7    // Note: To make the example code cleaner we do not handle exceptions. Exceptions you
 8    //       might normally want to catch are described in the documentation
 9    public static void main(String args[]) throws Exception {
10        // Create connection and connect to brickd
11        IPConnection ipcon = new IPConnection();
12        ipcon.connect(HOST, PORT);
13
14        // Register enumerate listener and print incoming information
15        ipcon.addEnumerateListener(new IPConnection.EnumerateListener() {
16            public void enumerate(String uid, String connectedUid, char position,
17                                  short[] hardwareVersion, short[] firmwareVersion,
18                                  int deviceIdentifier, short enumerationType) {
19                System.out.println("UID:               " + uid);
20                System.out.println("Enumeration Type:  " + enumerationType);
21
22                if(enumerationType == IPConnection.ENUMERATION_TYPE_DISCONNECTED) {
23                    System.out.println("");
24                    return;
25                }
26
27                System.out.println("Connected UID:     " + connectedUid);
28                System.out.println("Position:          " + position);
29                System.out.println("Hardware Version:  " + hardwareVersion[0] + "." +
30                                                           hardwareVersion[1] + "." +
31                                                           hardwareVersion[2]);
32                System.out.println("Firmware Version:  " + firmwareVersion[0] + "." +
33                                                           firmwareVersion[1] + "." +
34                                                           firmwareVersion[2]);
35                System.out.println("Device Identifier: " + deviceIdentifier);
36                System.out.println("");
37            }
38        });
39
40        ipcon.enumerate();
41
42        System.out.println("Press key to exit"); System.in.read();
43        ipcon.disconnect();
44    }
45}

Authenticate

Download (ExampleAuthenticate.java)

 1import com.tinkerforge.IPConnection;
 2import com.tinkerforge.TinkerforgeException;
 3import java.security.SignatureException;
 4
 5public class ExampleAuthenticate {
 6    private static final String HOST = "localhost";
 7    private static final int PORT = 4223;
 8    private static final String SECRET = "My Authentication Secret!";
 9
10    // Note: To make the example code cleaner we do not handle exceptions. Exceptions you
11    //       might normally want to catch are described in the documentation
12    public static void main(String args[]) throws Exception {
13        // Note: Declare ipcon final, so the listener can access it
14        final IPConnection ipcon = new IPConnection(); // Create IP Connection
15
16        // Disable auto reconnect mechanism, in case we have the wrong secret.
17        // If the authentication is successful, reenable it.
18        ipcon.setAutoReconnect(false);
19
20        // Register enumerate listener and print incoming information
21        ipcon.addConnectedListener(new IPConnection.ConnectedListener() {
22            public void connected(short connectReason) {
23                switch(connectReason) {
24                case IPConnection.CONNECT_REASON_REQUEST:
25                    System.out.println("Connected by request");
26                    break;
27
28                case IPConnection.CONNECT_REASON_AUTO_RECONNECT:
29                    System.out.println("Auto-Reconnect");
30                    break;
31                }
32
33                // Authenticate first...
34                try {
35                    ipcon.authenticate(SECRET);
36                    System.out.println("Authentication succeeded");
37                } catch(TinkerforgeException e) {
38                    System.out.println("Could not authenticate: " + e.getMessage());
39                    return;
40                }
41
42                // ...reenable auto reconnect mechanism, as described below...
43                ipcon.setAutoReconnect(true);
44
45                // ...then trigger enumerate
46                try {
47                    ipcon.enumerate();
48                } catch(TinkerforgeException e) {
49                }
50            }
51        });
52
53        // Register enumerate listener and print incoming information
54        ipcon.addEnumerateListener(new IPConnection.EnumerateListener() {
55            public void enumerate(String uid, String connectedUid, char position,
56                                  short[] hardwareVersion, short[] firmwareVersion,
57                                  int deviceIdentifier, short enumerationType) {
58                System.out.println("UID: " + uid + ", Enumeration Type: " + enumerationType);
59            }
60        });
61
62        // Connect to brickd
63        ipcon.connect(HOST, PORT);
64
65        System.out.println("Press key to exit"); System.in.read();
66        ipcon.disconnect();
67    }
68}

API

Grundfunktionen

class IPConnection()

Erzeugt ein IP Connection Objekt das verwendet werden kann um die verfügbar Geräte zu enumerieren. Es wird auch für den Konstruktor von Bricks und Bricklets benötigt.

void IPConnection.connect(String host, int port)

Erstellt eine TCP/IP Verbindung zum gegebenen host und port. Host und Port können auf einen Brick Daemon oder eine WIFI/Ethernet Extension verweisen.

Bricks/Bricklets können erst gesteuert werden, wenn die Verbindung erfolgreich aufgebaut wurde.

Blockiert bis die Verbindung aufgebaut wurde und wirft eine Exception, falls kein Brick Daemon oder WIFI/Ethernet Extension auf dem gegebenen Host und Port horcht.

void IPConnection.disconnect()

Trennt die TCP/IP Verbindung zum Brick Daemon oder einer WIFI/Ethernet Extension.

void IPConnection.authenticate(String secret)

Führt einen Authentifizierungs-Handshake mit dem verbundenen Brick Daemon oder WIFI/Ethernet Extension durch. Ist der Handshake erfolgreich dann wechselt die Verbindung vom nicht-authentifizierten in den authentifizierten Zustand und die Kommunikation kann normal weitergeführt werden. Schlägt der Handshake fehl wird die Verbindung durch die Gegenseite geschlossen. Die Authentifizierung kann fehlschlagen wenn das Authentifizierungsgeheimnis nicht übereinstimmt oder Authentifizierung für den Brick Daemon oder die WIFI/Ethernet Extension nicht aktiviert ist.

Für mehr Informationen zur Authentifizierung siehe das dazugehörige Tutorial.

Added in version 2.1.0.

short IPConnection.getConnectionState()

Kann die folgenden Zustände zurückgeben:

  • IPConnection.CONNECTION_STATE_DISCONNECTED = 0: Keine Verbindung aufgebaut.

  • IPConnection.CONNECTION_STATE_CONNECTED = 1: Eine Verbindung zum Brick Daemon oder der WIFI/Ethernet Extension ist aufgebaut.

  • IPConnection.CONNECTION_STATE_PENDING = 2: IP Connection versucht im Moment eine Verbindung aufzubauen.

void IPConnection.setAutoReconnect(boolean autoReconnect)

Aktiviert oder deaktiviert Auto-Reconnect. Falls Auto-Reconnect aktiviert ist, versucht die IP Connection eine Verbindung zum vorher angegebenen Host und Port wieder herzustellen, falls die aktuell bestehende Verbindung verloren geht. Auto-Reconnect greift also erst nach einem erfolgreichen Aufruf von connect().

Standardwert ist true.

boolean IPConnection.getAutoReconnect()

Gibt true zurück wenn Auto-Reconnect aktiviert ist und false sonst.

void IPConnection.setTimeout(int timeout)

Setzt den Timeout in Millisekunden für Getter und für Setter die das Response-Expected-Flag aktiviert haben.

Standardwert ist 2500.

int IPConnection.getTimeout()

Gibt den Timeout zurück, wie er von setTimeout() gesetzt wurde.

void IPConnection.enumerate()

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

Listener

Listeners können registriert werden um über Ereignisse informiert zu werden. Die Registrierung kann mit "addListener" Funktionen des IPConnection Objekts durchgeführt werden.

Der Parameter ist ein Listener Klassen Objekt, z.B.:

ipcon.addExampleListener(new IPConnection.ExampleListener() {
    public void property(int value) {
        System.out.println("Value: " + value);
    }
});

Die verfügbaren Listener Klassen mit den Methoden welche überschrieben werden können werden unterhalb beschrieben. Es ist möglich mehrere Listener hinzuzufügen und auch mit einem korrespondierenden "removeListener" wieder zu entfernen.

class IPConnection.EnumerateListener()

Dieser Listener kann mit der Funktion addEnumerateListener() hinzugefügt werde. Ein hinzugefügter Listener kann mit der Funktion removeEnumerateListener() wieder entfernt werden.

void enumerate(String uid, String connectedUid, char position, short[] hardwareVersion, short[] firmwareVersion, int deviceIdentifier, short enumerationType)

Der Listener empfängt sieben Parameter:

  • uid: Die UID des Bricks/Bricklets.

  • connectedUid: 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).

  • hardwareVersion: Major, Minor und Release Nummer der Hardwareversion.

  • firmwareVersion: Major, Minor und Release Nummer der Firmwareversion.

  • deviceIdentifier: Eine Zahl, welche den Brick/Bricklet repräsentiert.

  • enumerationType: Art der Enumerierung.

Mögliche Enumerierungsarten sind:

  • IPConnection.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.

  • IPConnection.ENUMERATION_TYPE_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.

  • IPConnection.ENUMERATION_TYPE_DISCONNECTED = 2: Gerät wurde getrennt (Nur bei USB-Verbindungen möglich). In diesem Fall haben nur uid und enumerationType einen gültigen Wert.

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

Die Device Identifier Werte sind hier zu finden. Es gibt auch Konstanten für diese Werte, welche nach dem folgenden Muster benannt sind:

<device-class>.DEVICE_IDENTIFIER

Zum Beispiel: BrickMaster.DEVICE_IDENTIFIER oder BrickletAmbientLight.DEVICE_IDENTIFIER.

class IPConnection.ConnectedListener()

Dieser Listener kann mit der Funktion addConnectedListener() hinzugefügt werde. Ein hinzugefügter Listener kann mit der Funktion removeConnectedListener() wieder entfernt werden.

void connected(short connectReason)

Dieser Listener wird aufgerufen wenn die IP Connection eine Verbindung zu einem Brick Daemon oder einer WIFI/Ethernet Extension aufgebaut hat, mögliche Gründe sind:

  • IPConnection.CONNECT_REASON_REQUEST = 0: Verbindung aufgebaut nach Anfrage vom Benutzer.

  • IPConnection.CONNECT_REASON_AUTO_RECONNECT = 1: Verbindung aufgebaut durch Auto-Reconnect.

class IPConnection.DisconnectedListener()

Dieser Listener kann mit der Funktion addDisconnectedListener() hinzugefügt werde. Ein hinzugefügter Listener kann mit der Funktion removeDisconnectedListener() wieder entfernt werden.

void disconnected(short disconnectReason)

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

  • IPConnection.DISCONNECT_REASON_REQUEST = 0: Trennung wurde vom Benutzer angefragt.

  • IPConnection.DISCONNECT_REASON_ERROR = 1: Trennung aufgrund eines unlösbaren Problems.

  • IPConnection.DISCONNECT_REASON_SHUTDOWN = 2: Trennung wurde vom Brick Daemon oder WIFI/Ethernet Extension eingeleitet.