Deutsch
English
Menu

Visual Basic .NET - IP Connection

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

Beispiele

Der folgende Beispielcode ist Public Domain (CC0 1.0).

Enumerate

Download (ExampleEnumerate.vb)

 1Imports Tinkerforge
 2
 3Module ExampleEnumerate
 4    Const HOST As String = "localhost"
 5    Const PORT As Integer = 4223
 6
 7    Sub EnumerateCB(ByVal sender As IPConnection, _
 8                    ByVal uid As String, _
 9                    ByVal connectedUid As String, _
10                    ByVal position As Char, _
11                    ByVal hardwareVersion() As Short, _
12                    ByVal firmwareVersion() As Short, _
13                    ByVal deviceIdentifier As Integer, _
14                    ByVal enumerationType As Short)
15        System.Console.WriteLine("UID:               {0}", uid)
16        System.Console.WriteLine("Enumeration Type:  {0}", enumerationType)
17
18        If enumerationType = IPConnection.ENUMERATION_TYPE_DISCONNECTED Then
19            System.Console.WriteLine("")
20            Return
21        End If
22
23        System.Console.WriteLine("Connected UID:     {0}", connectedUid)
24        System.Console.WriteLine("Position:          {0}", position)
25        System.Console.WriteLine("Hardware Version:  {0}.{1}.{2}", _
26                                 hardwareVersion(0), hardwareVersion(1), hardwareVersion(2))
27        System.Console.WriteLine("Firmware Version:  {0}.{1}.{2}", _
28                                 firmwareVersion(0), firmwareVersion(1), firmwareVersion(2))
29        System.Console.WriteLine("Device Identifier: {0}", deviceIdentifier)
30        System.Console.WriteLine("")
31    End Sub
32
33    Sub Main()
34        ' Create connection and connect to brickd
35        Dim ipcon As New IPConnection()
36        ipcon.Connect(HOST, PORT)
37
38        ' Register Enumerate Callback
39        AddHandler ipcon.EnumerateCallback, AddressOf EnumerateCB
40
41        ' Trigger Enumerate
42        ipcon.Enumerate()
43
44        System.Console.WriteLine("Press key to exit")
45        System.Console.ReadLine()
46        ipcon.Disconnect()
47    End Sub
48End Module

Authenticate

Download (ExampleAuthenticate.vb)

 1Imports Tinkerforge
 2
 3Module ExampleAuthenticate
 4    Const HOST As String = "localhost"
 5    Const PORT As Integer = 4223
 6    Const SECRET As String = "My Authentication Secret!"
 7
 8    Sub ConnectedCB(ByVal sender As IPConnection, _
 9                    ByVal connectReason As Short)
10        Select Case connectReason
11            Case IPConnection.CONNECT_REASON_REQUEST
12                System.Console.WriteLine("Connected by request")
13            Case IPConnection.CONNECT_REASON_AUTO_RECONNECT
14                System.Console.WriteLine("Auto-Reconnect")
15        End Select
16
17        ' Authenticate first...
18        Try
19            sender.Authenticate(SECRET)
20            System.Console.WriteLine("Authentication succeeded")
21        catch
22            System.Console.WriteLine("Could not authenticate")
23            Exit Sub
24        End Try
25
26        ' ...reenable auto reconnect mechanism, as described below...
27        sender.SetAutoReconnect(true)
28
29        ' ...then trigger enumerate
30        sender.Enumerate()
31    End Sub
32
33    Sub EnumerateCB(ByVal sender As IPConnection, _
34                    ByVal uid As String, _
35                    ByVal connectedUid As String, _
36                    ByVal position As Char, _
37                    ByVal hardwareVersion() As Short, _
38                    ByVal firmwareVersion() As Short, _
39                    ByVal deviceIdentifier As Integer, _
40                    ByVal enumerationType As Short)
41        System.Console.WriteLine("UID: {0}, Enumeration Type: {1}", uid, enumerationType)
42    End Sub
43
44    Sub Main()
45        ' Create IPConnection and connect to brickd
46        Dim ipcon As New IPConnection()
47
48        ' Register Connected Callback
49        AddHandler ipcon.Connected, AddressOf ConnectedCB
50
51        ' Register Enumerate Callback
52        AddHandler ipcon.EnumerateCallback, AddressOf EnumerateCB
53
54        ' Disable auto reconnect mechanism, in case we have the wrong secret.
55        ' If the authentication is successful, reenable it.
56        ipcon.SetAutoReconnect(false)
57
58        ' Connect to brickd
59        ipcon.Connect(HOST, PORT)
60
61        System.Console.WriteLine("Press key to exit")
62        System.Console.ReadLine()
63        ipcon.Disconnect()
64    End Sub
65End Module

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.

Sub IPConnection.Connect(ByVal host As String, ByVal port As Integer)

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.

Sub IPConnection.Disconnect()

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

Sub IPConnection.Authenticate(ByVal secret As String)

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.

Function IPConnection.GetConnectionState() As Short

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.

Sub IPConnection.SetAutoReconnect(ByVal autoReconnect As 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.

Function IPConnection.GetAutoReconnect() As Boolean

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

Sub IPConnection.SetTimeout(ByVal timeout As Integer)

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

Standardwert ist 2500.

Function IPConnection.GetTimeout() As Integer

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

Sub IPConnection.Enumerate()

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

Sub IPConnection.Wait()

Hält den aktuellen Thread an bis IPConnection.Unwait() aufgerufen wird.

Dies ist nützlich falls ausschließlich auf Callbacks reagiert werden soll oder wenn auf einen spezifischen Callback gewartet werden soll oder wenn die IP Connection in einem Thread gestartet wird.

Wait und Unwait agieren auf die gleiche Weise wie Acquire und Release einer Semaphore.

Sub IPConnection.Unwait()

Startet einen Thread der vorher mit IPConnection.Wait() angehalten wurde wieder.

Wait und Unwait agieren auf die gleiche Weise wie Acquire und Release einer Semaphore.

Callbacks

Callbacks können registriert werden um über Ereignisse informiert zu werden. Die Registrierung geschieht durch Anhängen des Callback Handlers an den passenden Event:

Sub MyCallback(ByVal sender As IPConnection, ByVal value As Short)
    Console.WriteLine("Value: {0}", value)
End Sub

AddHandler ipcon.ExampleCallback, AddressOf MyCallback

Die verfügbaren Events werden im Folgenden beschrieben.

Event IPConnection.EnumerateCallback(ByVal sender As IPConnection, ByVal uid As String, ByVal connectedUid As String, ByVal position As Char, ByVal hardwareVersion() As Short, ByVal firmwareVersion() As Short, ByVal deviceIdentifier As Integer, ByVal enumerationType As Short)

Der Event 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: IPConnection.Enumerate()). Diese Enumerierungsart kann mehrfach für das selbe Gerät auftreten.

  • IPConnection.ENUMERATION_TYPE_CONNECTED = 1: Gerät ist 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 Event 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.

Event IPConnection.ConnectedCallback(ByVal sender As IPConnection, ByVal connectReason As Short)

Dieser Event wird ausgelöst 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.

Event IPConnection.DisconnectedCallback(ByVal sender As IPConnection, ByVal disconnectReason As Short)

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