JavaScript - IP Connection¶

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

Beispiele¶

Der folgende Beispielcode ist Public Domain (CC0 1.0).

Enumerate (Node.js)¶

Download (ExampleEnumerate.js)

var Tinkerforge = require('tinkerforge');

var HOST = 'localhost';
var PORT = 4223;

ipcon = new Tinkerforge.IPConnection(); // Create IP connection
ipcon.connect(HOST, PORT,
    function(error) {
        console.log('Error: '+error);
    }
); // Connect to brickd

// Register Connected Callback
ipcon.on(Tinkerforge.IPConnection.CALLBACK_CONNECTED,
    function(connectReason) {
        // Trigger Enumerate
        ipcon.enumerate();
    }
);

// Register Enumerate Callback
ipcon.on(Tinkerforge.IPConnection.CALLBACK_ENUMERATE,
    // Print incoming enumeration
    function(uid, connectedUid, position, hardwareVersion, firmwareVersion,
             deviceIdentifier, enumerationType) {
        console.log('UID:               '+uid);
        console.log('Enumeration Type:  '+enumerationType);

        if(enumerationType === Tinkerforge.IPConnection.ENUMERATION_TYPE_DISCONNECTED) {
            console.log('');
            return;
        }

        console.log('Connected UID:     '+connectedUid);
        console.log('Position:          '+position);
        console.log('Hardware Version:  '+hardwareVersion);
        console.log('Firmware Version:  '+firmwareVersion);
        console.log('Device Identifier: '+deviceIdentifier);
        console.log('');
    }
);

console.log("Press any key to exit ...");
process.stdin.on('data',
    function(data) {
        ipcon.disconnect();
        process.exit(0);
    }
);

Authenticate (Node.js)¶

Download (ExampleAuthenticate.js)

var Tinkerforge = require('tinkerforge');

var HOST = 'localhost';
var PORT = 4223;
var SECRET = 'My Authentication Secret!';

ipcon = new Tinkerforge.IPConnection(); // Create IP connection
ipcon.connect(HOST, PORT,
    function(error) {
        console.log('Error: '+error);
    }
); // Connect to brickd

// Disable auto reconnect mechanism, in case we have the wrong secret.
// If the authentication is successful, reenable it.
ipcon.setAutoReconnect(false);

// Register Connected Callback
ipcon.on(Tinkerforge.IPConnection.CALLBACK_CONNECTED,
    // Authenticate each time the connection got (re-)established
    function(connectReason) {
        switch(connectReason) {
        case Tinkerforge.IPConnection.CONNECT_REASON_REQUEST:
            console.log('Connected by request');
            break;
        case Tinkerforge.IPConnection.CONNECT_REASON_AUTO_RECONNECT:
            console.log('Auto-Reconnected');
            break;
        }
        ipcon.authenticate(SECRET,
            function() {
                console.log('Authentication succeeded');

                // ...reenable auto reconnect mechanism, as described above...
                ipcon.setAutoReconnect(true);

                // ...then trigger Enumerate
                ipcon.enumerate();
            },
            function(error) {
                console.log('Could not authenticate: '+error);
            }
        );
    }
);

// Register Enumerate Callback
ipcon.on(Tinkerforge.IPConnection.CALLBACK_ENUMERATE,
    // Print incoming enumeration
    function(uid, connectedUid, position, hardwareVersion, firmwareVersion,
             deviceIdentifier, enumerationType) {
        console.log('UID: '+uid+', Enumeration Type: '+enumerationType);
    }
);

console.log("Press any key to exit ...");
process.stdin.on('data',
    function(data) {
        ipcon.disconnect();
        process.exit(0);
    }
);

Enumerate (HTML)¶

Download (ExampleEnumerate.html), Test (ExampleEnumerate.html)

<!DOCTYPE html>
<html>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <head>
        <title>Tinkerforge | JavaScript Example</title>
    </head>
    <body>
        <div style="text-align:center;">
            <h1>Enumerate Example</h1>
            <p>
                <input value="localhost" id="host" type="text" size="20">:
                <input value="4280" id="port" type="text" size="5">
                <input value="Start Example" id="start" type="button" onclick="startExample();">
            </p>
            <p>
                <textarea id="text" cols="80" rows="24" style="resize:none;"
                          >Press "Start Example" to begin ...</textarea>
            </p>
        </div>
        <script src="./Tinkerforge.js" type='text/javascript'></script>
        <script type='text/javascript'>
            var ipcon;
            var textArea = document.getElementById("text");
            function startExample() {
                textArea.value = "";
                var HOST = document.getElementById("host").value;
                var PORT = parseInt(document.getElementById("port").value);
                if(ipcon !== undefined) {
                    ipcon.disconnect();
                }
                ipcon = new Tinkerforge.IPConnection(); // Create IP connection
                ipcon.connect(HOST, PORT,
                    function(error) {
                        textArea.value += 'Error: '+error+ '\n';
                    }
                ); // Connect to brickd
                // Don't use device before ipcon is connected

                // Register Connected Callback
                ipcon.on(Tinkerforge.IPConnection.CALLBACK_CONNECTED,
                    function(connectReason) {
                        // Trigger Enumerate
                        ipcon.enumerate();
                    }
                );
                // Register Enumerate Callback
                ipcon.on(Tinkerforge.IPConnection.CALLBACK_ENUMERATE,
                    // Print incoming enumeration
                    function(uid, connectedUid, position, hardwareVersion,
                             firmwareVersion, deviceIdentifier, enumerationType) {
                        textArea.value += 'UID:               '+uid+'\n';
                        textArea.value += 'Enumeration Type:  '+enumerationType+'\n';
                        if(enumerationType === Tinkerforge.IPConnection.ENUMERATION_TYPE_DISCONNECTED) {
                            textArea.value += '\n';
                            textArea.scrollTop = textArea.scrollHeight;
                            return;
                        }
                        textArea.value += 'Connected UID:     '+connectedUid+'\n';
                        textArea.value += 'Position:          '+position+'\n';
                        textArea.value += 'Hardware Version:  '+hardwareVersion+'\n';
                        textArea.value += 'Firmware Version:  '+firmwareVersion+'\n';
                        textArea.value += 'Device Identifier: '+deviceIdentifier+'\n';
                        textArea.value += '\n';
                        textArea.scrollTop = textArea.scrollHeight;
                    }
                );
            }
        </script>
    </body>
</html>

Authenticate (HTML)¶

Download (ExampleAuthenticate.html), Test (ExampleAuthenticate.html)

<!DOCTYPE html>
<html>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <head>
        <title>Tinkerforge | JavaScript Example</title>
    </head>
    <body>
        <div style="text-align:center;">
            <h1>Authenticate Example</h1>
            <p>
                <input value="localhost" id="host" type="text" size="20">:
                <input value="4280" id="port" type="text" size="5">,
                <input value="My Authentication Secret!" id="secret" type="text" size="30">:
                <input value="Start Example" id="start" type="button" onclick="startExample();">
            </p>
            <p>
                <textarea id="text" cols="80" rows="24" style="resize:none;"
                          >Press "Start Example" to begin ...</textarea>
            </p>
        </div>
        <script src="./Tinkerforge.js" type='text/javascript'></script>
        <script type='text/javascript'>
            var ipcon;
            var textArea = document.getElementById("text");
            function startExample() {
                textArea.value = "";
                var HOST = document.getElementById("host").value;
                var PORT = parseInt(document.getElementById("port").value);
                var SECRET = document.getElementById("secret").value;
                if(ipcon !== undefined) {
                    ipcon.disconnect();
                }
                ipcon = new Tinkerforge.IPConnection(); // Create IP connection

                // Disable auto reconnect mechanism, in case we have the wrong secret.
                // If the authentication is successful, reenable it.
                ipcon.setAutoReconnect(false);

                ipcon.connect(HOST, PORT,
                    function(error) {
                        textArea.value += 'Error: '+error+ '\n';
                    }
                ); // Connect to brickd
                // Don't use device before ipcon is connected

                // Register Connected Callback
                ipcon.on(Tinkerforge.IPConnection.CALLBACK_CONNECTED,
                    // Authenticate each time the connection got (re-)established
                    function(connectReason) {
                        switch(connectReason) {
                        case Tinkerforge.IPConnection.CONNECT_REASON_REQUEST:
                            textArea.value += 'Connected by request\n';
                            break;
                        case Tinkerforge.IPConnection.CONNECT_REASON_AUTO_RECONNECT:
                            textArea.value += 'Auto-Reconnected\n';
                            break;
                        }
                        ipcon.authenticate(SECRET,
                            function() {
                                textArea.value += 'Authentication succeeded\n';

                                // ...reenable auto reconnect mechanism, as described above...
                                ipcon.setAutoReconnect(true);

                                // ...then trigger Enumerate
                                ipcon.enumerate();
                            },
                            function(error) {
                                textArea.value += 'Could not authenticate: '+error+'\n';
                            }
                        );
                    }
                );
                // Register Enumerate Callback
                ipcon.on(Tinkerforge.IPConnection.CALLBACK_ENUMERATE,
                    // Print incoming enumeration
                    function(uid, connectedUid, position, hardwareVersion, firmwareVersion,
                             deviceIdentifier, enumerationType) {
                        textArea.value += 'UID: '+uid+', Enumeration Type: '+enumerationType+'\n';
                        textArea.scrollTop = textArea.scrollHeight;
                    }
                );
            }
        </script>
    </body>
</html>

API¶

Allgemein kann jede Methode der JavaScript Bindings zwei optionale Parameter haben, returnCallback und errorCallback. Dies sind benutzerdefinierte Callback-Funktionen. Der returnCallback wird aufgerufen mit den Rückgabewerten der Methode, sofern vorhanden. Der errorCallback wird im Fehlerfall mit einem Fehlercode aufgerufen. Der Fehlercode kann einer der folgenden Werte sein:

IPConnection.ERROR_ALREADY_CONNECTED = 11
IPConnection.ERROR_NOT_CONNECTED = 12
IPConnection.ERROR_CONNECT_FAILED = 13
IPConnection.ERROR_INVALID_FUNCTION_ID = 21
IPConnection.ERROR_TIMEOUT = 31
IPConnection.ERROR_INVALID_PARAMETER = 41
IPConnection.ERROR_FUNCTION_NOT_SUPPORTED = 42
IPConnection.ERROR_UNKNOWN_ERROR = 43
IPConnection.ERROR_STREAM_OUT_OF_SYNC = 51
IPConnection.ERROR_NON_ASCII_CHAR_IN_SECRET = 71
IPConnection.ERROR_WRONG_DEVICE_TYPE = 81
IPConnection.ERROR_DEVICE_REPLACED = 82
IPConnection.ERROR_WRONG_RESPONSE_LENGTH = 83
IPConnection.ERROR_INT64_NOT_SUPPORTED = 91

Der Namespace der JavaScript Bindings ist Tinkerforge.*.

Grundfunktionen¶

new 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.

IPConnection.connect(host, port[, errorCallback])¶

Parameter:

host -- string
port -- int

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.

IPConnection.disconnect([errorCallback])¶: Trennt die TCP/IP Verbindung zum Brick Daemon oder einer WIFI/Ethernet Extension.

IPConnection.authenticate(secret[, returnCallback][, errorCallback])¶

Parameter:

secret -- string

Callback:

undefined

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.

IPConnection.getConnectionState()¶

Rückgabetyp:: int

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.

IPConnection.setAutoReconnect(autoReconnect)¶

Parameter:

auto_reconnect -- boolean

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.

IPConnection.getAutoReconnect()¶

Rückgabetyp:: boolean

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

IPConnection.setTimeout(timeout)¶

Parameter:

timeout -- int

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

Standardwert ist 2500.

IPConnection.getTimeout()¶

Rückgabetyp:: int

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

IPConnection.enumerate([errorCallback])¶: Broadcast einer Enumerierungsanfrage. Alle Bricks und Bricklets werden mit einem Enumerate Callback antworten.

Callback Configuration Functions¶

IPConnection.on(callback_id, function)¶

Parameter:

callback_id -- int
function -- function

Registriert die function für die gegebene callback_id.

Die verfügbaren Callback IDs mit zugehörenden Funktionssignaturen sind unten beschrieben.

Callbacks¶

Callbacks können registriert werden um über Ereignisse informiert zu werden. Die Registrierung wird mit der Funktion on() durchgeführt. Die Parameter bestehen aus dem IP Connection Objekt, der Callback ID, der Callback Funktion und optionalen Benutzer Daten:

ipcon.on(IPConnection.CALLBACK_EXAMPLE,
    function (param) {
        console.log(param);
    }
);

Die verfügbaren IDs mit den zugehörigen Callback Funktionssignaturen werden weiter unten beschrieben.

IPConnection.CALLBACK_ENUMERATE¶

Parameter:

uid -- string
connectedUid -- string
position -- char
hardwareVersion -- [int, int, int]
firmwareVersion -- [int, int, int]
deviceIdentifier -- int
enumerationType -- int

Der Callback 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 Callback 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: Master.DEVICE_IDENTIFIER oder AmbientLight.DEVICE_IDENTIFIER.

IPConnection.CALLBACK_CONNECTED¶

Parameter:

connectReason -- int

Dieser Callback 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.

IPConnection.CALLBACK_DISCONNECTED¶

Parameter:

disconnectReason -- int

Dieser 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:

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.