Ruby - IP Connection

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

Beispiele

Der folgende Beispielcode ist Public Domain (CC0 1.0).

Enumerate

Download (example_enumerate.rb)

 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
#!/usr/bin/env ruby
# -*- ruby encoding: utf-8 -*-

require 'tinkerforge/ip_connection'

include Tinkerforge

HOST = 'localhost'
PORT = 4223

# Create IP connection to brickd
ipcon = IPConnection.new
ipcon.connect HOST, PORT

# Enumerate Bricks and Bricklets
ipcon.register_callback(IPConnection::CALLBACK_ENUMERATE) do |uid, connected_uid, position,
                                                              hardware_version, firmware_version,
                                                              device_identifier, enumeration_type|
  puts "UID:               #{uid}"
  puts "Enumeration Type:  #{enumeration_type}"

  if enumeration_type != IPConnection::ENUMERATION_TYPE_DISCONNECTED
    puts "Connected UID:     #{connected_uid}"
    puts "Position:          #{position}"
    puts "Hardware Version:  #{hardware_version}"
    puts "Firmware Version:  #{firmware_version}"
    puts "Device Identifier: #{device_identifier}"
  end

  puts ''
end

ipcon.enumerate

puts 'Press key to exit'
$stdin.gets
ipcon.disconnect

Authenticate

Download (example_authenticate.rb)

 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
#!/usr/bin/env ruby
# -*- ruby encoding: utf-8 -*-

require 'tinkerforge/ip_connection'

include Tinkerforge

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

# Create IP connection
ipcon = IPConnection.new

# Disable auto reconnect mechanism, in case we have the wrong secret.
# If the authentication is successful, reenable it.
ipcon.set_auto_reconnect false

# Authenticate each time the connection got (re-)established
ipcon.register_callback(IPConnection::CALLBACK_CONNECTED) do |connect_reason|
  case connect_reason
    when IPConnection::CONNECT_REASON_REQUEST
      puts 'Connected by request'
    when IPConnection::CONNECT_REASON_AUTO_RECONNECT
      puts 'Auto-Reconnect'
  end

  # Authenticate first...
  begin
    ipcon.authenticate SECRET
    puts 'Authentication succeeded'

    # ...reenable auto reconnect mechanism, as described above...
    ipcon.set_auto_reconnect true

    # ...then trigger enumerate
    ipcon.enumerate
  rescue
    puts 'Could not authenticate'
  end
end

# Print incoming enumeration
ipcon.register_callback(IPConnection::CALLBACK_ENUMERATE) do |uid, connected_uid, position,
                                                              hardware_version, firmware_version,
                                                              device_identifier, enumeration_type|
  puts "UID: #{uid}, Enumeration Type: #{enumeration_type}"
end

# Connecte to brickd
ipcon.connect HOST, PORT

puts 'Press key to exit'
$stdin.gets
ipcon.disconnect

API

Grundfunktionen

IPConnection::new → ipcon

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) → nil
Parameter:
  • host -- str
  • port -- int

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.

IPConnection#disconnect → nil

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

IPConnection#authenticate(secret) → nil
Parameter:secret -- str

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.

IPConnection#get_connection_state → 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#set_auto_reconnect(auto_reconnect) → nil
Parameter:auto_reconnect -- 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.

IPConnection#get_auto_reconnect → bool

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

IPConnection#set_timeout(timeout) → nil
Parameter:timeout -- float

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

Standardwert ist 2.5.

IPConnection#get_timeout → float

Gibt den Timeout zurück, wie er von #set_timeout gesetzt wurde.

IPConnection#enumerate → nil

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

IPConnection#wait → nil

Hält den aktuellen Thread an bis #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.

IPConnection#unwait → nil

Startet einen Thread der vorher mit #wait angehalten wurde wieder.

wait und unwait agieren auf die gleiche Weise wie "acquire" und release einer Semaphore.

Konfigurationsfunktionen für Callbacks

IPConnection#register_callback(callback_id) { |param [, ...]| block } → nil
Parameter:callback_id -- int

Registriert den block 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 kann mit der Funktion #register_callback durchgeführt werden. Der erste Parameter ist der Callback ID und der zweite Parameter der Block:

ipcon.register_callback IPConnection::CALLBACK_EXAMPLE, do |param|
  puts "#{param}"
end

Die verfügbaren IDs mit der dazugehörigen Parameteranzahl und -typen werden weiter unten beschrieben.

IPConnection::CALLBACK_ENUMERATE
Parameter:
  • uid -- str
  • connected_uid -- str
  • position -- chr
  • hardware_version -- [int, int, int]
  • firmware_version -- [int, int, int]
  • device_identifier -- int
  • enumeration_type -- int

Der Callback empfängt sieben Parameter:

  • uid: Die UID des Bricks/Bricklets.
  • connected_uid: 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).
  • hardware_version: Major, Minor und Release Nummer der Hardwareversion.
  • firmware_version: Major, Minor und Release Nummer der Firmwareversion.
  • device_identifier: Eine Zahl, welche den Brick/Bricklet repräsentiert.
  • enumeration_type: 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 enumeration_type 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.

IPConnection::CALLBACK_CONNECTED
Parameter:connect_reason -- 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:disconnect_reason -- 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.