PHP - IP Connection¶

Enumerate¶

Download (ExampleEnumerate.php)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

<?php

require_once('Tinkerforge/IPConnection.php');

use Tinkerforge\IPConnection;

const HOST = 'localhost';
const PORT = 4223;

// Print incoming enumeration
function cb_enumerate($uid, $connectedUid, $position,
                      $hardwareVersion, $firmwareVersion,
                      $deviceIdentifier, $enumerationType)
{
    echo "UID:               $uid\n";
    echo "Enumeration Type:  $enumerationType\n";

    if($enumerationType == IPConnection::ENUMERATION_TYPE_DISCONNECTED) {
        echo "\n";
        return;
    }

    echo "Connected UID:     $connectedUid\n";
    echo "Position:          $position\n";
    echo "Hardware Version:  $hardwareVersion[0].$hardwareVersion[1].$hardwareVersion[2]\n";
    echo "Firmware Version:  $firmwareVersion[0].$firmwareVersion[1].$firmwareVersion[2]\n";
    echo "Device Identifier: $deviceIdentifier\n";
    echo "\n";
}

// Create IP connection and connect to brickd
$ipcon = new IPConnection();
$ipcon->connect(HOST, PORT);

// Register enumerate callback to "cb_enumerate"
$ipcon->registerCallback(IPConnection::CALLBACK_ENUMERATE, 'cb_enumerate');

$ipcon->enumerate();

echo "Press ctrl+c to exit\n";
$ipcon->dispatchCallbacks(-1); // Dispatch callbacks forever

?>

Authenticate¶

Download (ExampleAuthenticate.php)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

<?php

require_once('Tinkerforge/IPConnection.php');

use Tinkerforge\IPConnection;
use Tinkerforge\TinkerforgeException;

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

// Authenticate each time the connection got (re-)established
function cb_connected($connectReason, $userData)
{
    $ipcon = $userData;

    switch ($connectReason) {
    case IPConnection::CONNECT_REASON_REQUEST:
        echo "Connected by request\n";
        break;
    }

    // Authenticate first...
    try {
        $ipcon->authenticate(SECRET);
        echo "Authentication succeeded\n";
    } catch (TinkerforgeException $e) {
        echo "Could not authenticate\n";
        return;
    }

    // ...then trigger enumerate
    $ipcon->enumerate();
}

// Print incoming enumeration
function cb_enumerate($uid, $connectedUid, $position,
                      $hardwareVersion, $firmwareVersion,
                      $deviceIdentifier, $enumerationType)
{
    echo "UID: $uid, Enumeration Type: $enumerationType\n";
}

// Create IP connection and connect to brickd
$ipcon = new IPConnection();

// Register connected callback to "cb_connected"
$ipcon->registerCallback(IPConnection::CALLBACK_CONNECTED, 'cb_connected', $ipcon);

// Register enumerate callback to "cb_enumerate"
$ipcon->registerCallback(IPConnection::CALLBACK_ENUMERATE, 'cb_enumerate');

$ipcon->connect(HOST, PORT);

echo "Press ctrl+c to exit\n";
$ipcon->dispatchCallbacks(-1); // Dispatch callbacks forever

?>

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

Neu in Version 2.1.0.

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

void IPConnection::setTimeout(float $seconds)¶

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

Standardwert ist 2,5.

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.

void IPConnection::dispatchCallbacks(float $seconds)¶

Liefert eingehende Callbacks für die gegebene Dauer in Sekunden aus (negative Werte bedeuten unendlich). Da PHP keine Threads unterstützt muss diese Methode periodisch aufgerufen werden, um sicherzustellen, dass eingehende Callbacks behandelt werden. Falls keine Callbacks benutzt werden braucht diese Methode nicht aufgerufen zu werden.

Die empfohlene Auslieferungsdauer ist 0. Dadurch werden nur die Callbacks ausgeliefert die noch auf Auslieferung warten. Es wird jedoch nicht auf den Eingang weitere Callbacks gewartet.

Konfigurationsfunktionen für Callbacks¶

void IPConnection::registerCallback(int $callback_id, callable $function, mixed $user_data=NULL)¶

Registriert die $function für die gegebene $callback_id. Die optionalen $user_data werden der Funktion als letztes Parameter mit übergeben.

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 registerCallback() durchgeführt. Die Parameter bestehen aus der Callback ID, der Callback Funktion und optionalen Benutzer Daten:

<?php

function my_callback($param)
{
    echo $param . "\n";
}

$ipcon->registerCallback(IPConnection::CALLBACK_EXAMPLE, 'my_callback');

?>

Die verfügbaren Konstanten mit den zugehörigen Callback Funktionssignaturen werden im Folgenden beschrieben.

int IPConnection::CALLBACK_ENUMERATE¶

<?php   void callback(string $uid, string $connectedUid, char $position, array $hardwareVersion, array $firmwareVersion, int $deviceIdentifier, int $enumerationType [, mixed $userData])   ?>

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: BrickMaster::DEVICE_IDENTIFIER oder BrickletAmbientLight::DEVICE_IDENTIFIER.

int IPConnection::CALLBACK_CONNECTED¶

<?php   void callback(int $connectReason [, mixed $userData])   ?>

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.

int IPConnection::CALLBACK_DISCONNECTED¶

<?php   void callback(int $disconnectReason [, mixed $userData])   ?>

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.