Go - IP Connection

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

Beispiele

Der folgende Beispielcode ist Public Domain (CC0 1.0).

Enumerate

Download (example_enumerate.go)

 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
package main

import (
    "fmt"
    "github.com/Tinkerforge/go-api-bindings/ipconnection"
)

const ADDR string = "localhost:4223"

func main() {
    ipcon := ipconnection.New()
    defer ipcon.Close()

    ipcon.Connect(ADDR) // Connect to brickd.
    defer ipcon.Disconnect()
    // Don't use device before ipcon is connected.

    ipcon.RegisterEnumerateCallback(func(uid string, connectedUid string, position rune, hardwareVersion [3]uint8,
                                         firmwareVersion [3]uint8, deviceIdentifier uint16, enumerationType ipconnection.EnumerationType) {
        fmt.Printf("UID:               %s\n", uid)
        switch enumerationType {
        case ipconnection.EnumerationTypeAvailable:
            fmt.Printf("Enumeration Type:  Available\n")
        case ipconnection.EnumerationTypeConnected:
            fmt.Printf("Enumeration Type:  Connected\n")
        case ipconnection.EnumerationTypeDisconnected:
            fmt.Printf("Enumeration Type:  Disconnected\n")
            return
        }

        fmt.Printf("Connected UID:     %s\n", connectedUid)
        fmt.Printf("Position:          %c\n", position)
        fmt.Printf("Hardware Version:  %d.%d.%d\n", hardwareVersion[0], hardwareVersion[1], hardwareVersion[2])
        fmt.Printf("Firmware Version:  %d.%d.%d\n", firmwareVersion[0], firmwareVersion[1], firmwareVersion[2])
        fmt.Printf("Device Identifier: %d\n", deviceIdentifier)
        fmt.Println("")
    })

    ipcon.Enumerate()
    fmt.Println("Press enter to exit.")
    fmt.Scanln()
}

Authenticate

Download (example_authenticate.go)

 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
59
60
61
62
63
package main

import (
    "fmt"
    "github.com/Tinkerforge/go-api-bindings/ipconnection"
)

const ADDR string = "localhost:4223"
const SECRET string = "My Authentication Secret!"

func main() {
    ipcon := ipconnection.New()
    defer ipcon.Close()

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

    ipcon.RegisterConnectCallback(func(reason ipconnection.ConnectReason) {
        if reason == ipconnection.ConnectReasonRequest {
            fmt.Println("Connected by request")
        } else if reason == ipconnection.ConnectReasonAutoReconnect {
            fmt.Println("Auto-Reconnected")
        }

        // Authenticate first...
        err := ipcon.Authenticate(SECRET)
        if err != nil {
            fmt.Println("Could not authenticate:", err)
            return
        }

        fmt.Println("Authentication succeded")
        ipcon.SetAutoReconnect(true) // ...reenable auto reconnect mechanism, as described above,
        ipcon.Enumerate()            // then trigger enumerate.
    })

    ipcon.RegisterEnumerateCallback(func(uid string, connectedUid string, position rune, hardwareVersion [3]uint8,
                                         firmwareVersion [3]uint8, deviceIdentifier uint16, enumerationType ipconnection.EnumerationType) {
        fmt.Printf("UID:               %s\n", uid)
        switch enumerationType {
        case ipconnection.EnumerationTypeAvailable:
            fmt.Printf("Enumeration Type:  Available\n")
        case ipconnection.EnumerationTypeConnected:
            fmt.Printf("Enumeration Type:  Connected\n")
        case ipconnection.EnumerationTypeDisconnected:
            fmt.Printf("Enumeration Type:  Disconnected\n")
            return
        }

        fmt.Printf("Connected UID:     %s\n", connectedUid)
        fmt.Printf("Position:          %c\n", position)
        fmt.Printf("Hardware Version:  %d.%d.%d\n", hardwareVersion[0], hardwareVersion[1], hardwareVersion[2])
        fmt.Printf("Firmware Version:  %d.%d.%d\n", firmwareVersion[0], firmwareVersion[1], firmwareVersion[2])
        fmt.Printf("Device Identifier: %d\n", deviceIdentifier)
        fmt.Println("")
    })

    ipcon.Connect(ADDR) // Connect to brickd.
    defer ipcon.Disconnect()

    fmt.Println("Press enter to exit.")
    fmt.Scanln()
}

API

Die IP Connection ist im Package github.com/Tinkerforge/go-api-bindings/ipconnection definiert.

Grundfunktionen

func ipconnection.New() (ipcon 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.

func (*IPConnection) Close()

Zerstört diese IP Connection und beendet deren interne Go-Routinen.

func (*IPConnection) Connect(addr string) (err error)

Erstellt eine TCP/IP Verbindung zur gegebenen addr in der Form "host:port", wie hier beschrieben. 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.

func (*IPConnection) Disconnect()

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

func (*IPConnection) Authenticate(secret string) (err error)

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.

func (*IPConnection) GetConnectionState() (state ConnectionState)

Kann die folgenden Zustände zurückgeben:

  • ipconnection.ConnectionStateDisconnected = 0: Keine Verbindung aufgebaut.
  • ipconnection.ConnectionStateConnected = 1: Eine Verbindung zum Brick Daemon oder der WIFI/Ethernet Extension ist aufgebaut.
  • ipconnection.ConnectionStatePending = 2: IP Connection versucht im Moment eine Verbindung aufzubauen.
func (*IPConnection) SetAutoReconnect(autoReconnectEnabled bool)

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.

func (*IPConnection) GetAutoReconnect() (autoReconnect bool)

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

func (*IPConnection) SetTimeout(timeout time.Duration)

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

Standardwert ist 2500ms.

func (*IPConnection) GetTimeout() (timeout time.Duration)

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

func (*IPConnection) Enumerate()

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

Callbacks

Callbacks können registriert werden um über Ereignisse informiert zu werden. Die Registrierung kann mit Register*Callback() Funktionen des IPConnection Objekts durchgeführt werden. Zum Beispiel:

registrationId := ipcon.RegisterExampleCallback(func(param type) {
    fmt.Println(param)
});

Die verfügbaren Ereignisse werden unterhalb beschrieben. Es ist möglich mehrere Callbacks hinzuzufügen und auch mit einem korrespondierenden Deregister*Callback()-Aufruf wieder zu entfernen. Dieser erwartet eine Registrierungs-ID, die von Register*Callback() zurückgegeben wurde

func (*IPConnection) RegisterEnumerateCallback(func(uid string, connectedUid string, position rune, hardwareVersion [3]uint8, firmwareVersion [3]uint8, deviceIdentifier uint16, enumerationType EnumerationType)) (registrationId uint64)

Dieses Callback empfängt sieben Parameter:

  • uid: Die UID des Bricks/Bricklets.
  • connectedUid: Die UID des Bricks mit dem das Brick/Bricklet verbunden ist. Für ein Bricklet ist dies die UID des Bricks mit dem es verbunden ist. Für einen Brick ist es die UID des untersten Master Bricks in einem 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.EnumerationTypeAvailable = 0: Gerät ist verfügbar (Enumerierung vom Benutzer ausgelöst: Enumerate()). Diese Enumerierungsart kann mehrfach für das selbe Gerät auftreten.
  • ipconnection.EnumerationTypeConnected = 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.EnumerationTypeDisconnected = 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-package>.DeviceIdentifier

Zum Beispiel: master_brick.DeviceIdentifier oder ambient_light_bricklet.DeviceIdentifier.

func (*IPConnection) RegisterConnectCallback(func(reason ConnectReason)) (registrationId uint64)

Dieses 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.ConnectReasonRequest = 0: Verbindung aufgebaut nach Anfrage vom Benutzer.
  • ipconnection.ConnectReasonAutoReconnect = 1: Verbindung aufgebaut durch Auto-Reconnect.
func (*IPConnection) RegisterDisconnectCallback(func(reason DisconnectReason)) (registrationId uint64)

Dieses 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.DisconnectReasonRequest = 0: Trennung wurde vom Benutzer angefragt.
  • ipconnection.DisconnectReasonError = 1: Trennung aufgrund eines unlösbaren Problems.
  • ipconnection.DisconnectReasonShutdown = 2: rennung wurde vom Brick Daemon oder WIFI/Ethernet Extension eingeleitet.