Deutsch
English
Menu

MATLAB/Octave - IP Connection

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

Beispiele

Der folgende Beispielcode ist Public Domain (CC0 1.0).

Enumerate (MATLAB)

Download (matlab_example_enumerate.m)

 1function matlab_example_enumerate()
 2    import com.tinkerforge.IPConnection;
 3
 4    HOST = 'localhost';
 5    PORT = 4223;
 6
 7    ipcon = handle(IPConnection(), 'CallbackProperties'); % Create IP connection
 8
 9    ipcon.connect(HOST, PORT); % Connect to brickd
10
11    % Register Enumerate Callback
12    set(ipcon, 'EnumerateCallback', @(h, e) cb_enumerate(e));
13
14    % Trigger Enumerate
15    ipcon.enumerate();
16
17    input('Press any key to exit...\n', 's');
18    ipcon.disconnect();
19end
20
21% Print incoming enumeration
22function cb_enumerate(e)
23    ipcon = e.getSource();
24
25    fprintf('UID: %s\n', char(e.uid));
26    fprintf('Enumeration Type: %d\n', e.enumerationType);
27
28    if e.enumerationType == ipcon.ENUMERATION_TYPE_DISCONNECTED
29        fprintf('\n');
30        return;
31    end
32
33    fprintf('Connected UID: %s\n', char(e.connectedUid));
34    fprintf('Position: %s\n', e.position);
35    fprintf('Hardware Version: ');
36    fprintf('%d', rot90(e.hardwareVersion));
37    fprintf('\n');
38    fprintf('Firmware Version: ');
39    fprintf('%d', rot90(e.firmwareVersion));
40    fprintf('\n');
41    fprintf('Device Identifier: %d\n', e.deviceIdentifier);
42    fprintf('\n');
43end

Authenticate (MATLAB)

Download (matlab_example_authenticate.m)

 1function matlab_example_authenticate()
 2    import com.tinkerforge.IPConnection;
 3
 4    global SECRET;
 5
 6    HOST = 'localhost';
 7    PORT = 4223;
 8    SECRET = 'My Authentication Secret!';
 9
10    ipcon = handle(IPConnection(), 'CallbackProperties'); % Create IP connection
11
12    % Disable auto reconnect mechanism, in case we have the wrong secret.
13    % If the authentication is successful, reenable it.
14    ipcon.setAutoReconnect(false)
15
16    % Register Connected Callback
17    set(ipcon, 'ConnectedCallback', @(h, e) cb_connected(e));
18
19    % Register Enumerate Callback
20    set(ipcon, 'EnumerateCallback', @(h, e) cb_enumerate(e));
21
22    ipcon.connect(HOST, PORT); % Connect to brickd
23
24    input('Press any key to exit...\n', 's');
25    ipcon.disconnect();
26end
27
28% Authenticate each time the connection got (re-)established
29function cb_connected(e)
30    ipcon = e.getSource();
31
32    global SECRET;
33
34    if e.connectReason == ipcon.CONNECT_REASON_REQUEST
35        fprintf('Connected by request\n');
36    elseif e.connectReason == ipcon.CONNECT_REASON_AUTO_RECONNECT
37        fprintf('Auto-Reconnect\n');
38    end
39
40    % Authenticate first...
41    try
42        ipcon.authenticate(SECRET);
43        fprintf('Authentication succeeded\n');
44    catch ex
45        fprintf('Could not authenticate\n');
46        return
47    end
48
49    % ...reenable auto reconnect mechanism, as described above...
50    ipcon.setAutoReconnect(true)
51
52    % ...then trigger enumerate
53    ipcon.enumerate();
54end
55
56% Print incoming enumeration
57function cb_enumerate(e)
58    fprintf('UID: %s, Enumeration Type: %g\n', char(e.uid), e.enumerationType);
59end

Enumerate (Octave)

Download (octave_example_enumerate.m)

 1function octave_example_enumerate()
 2    more off;
 3
 4    HOST = "localhost";
 5    PORT = 4223;
 6
 7    ipcon = javaObject("com.tinkerforge.IPConnection"); % Create IP connection
 8
 9    ipcon.connect(HOST, PORT); % Connect to brickd
10
11    % Register Enumerate Callback
12    ipcon.addEnumerateCallback(@cb_enumerate);
13
14    % Trigger Enumerate
15    ipcon.enumerate();
16
17    input("Press any key to exit...\n", "s");
18    ipcon.disconnect();
19end
20
21% Print incoming enumeration
22function cb_enumerate(e)
23    ipcon = e.getSource();
24
25    fprintf("UID: %s\n", e.uid);
26    fprintf("Enumeration Type: %d\n", java2int(e.enumerationType));
27
28    if java2int(e.enumerationType) == java2int(ipcon.ENUMERATION_TYPE_DISCONNECTED)
29        fprintf("\n");
30        return;
31    end
32
33    hardwareVersion = e.hardwareVersion;
34    firmwareVersion = e.firmwareVersion;
35
36    fprintf("Connected UID: %s\n", e.connectedUid);
37    fprintf("Position: %s\n", e.position);
38    fprintf("Hardware Version: %d.%d.%d\n", java2int(hardwareVersion(1)), ...
39                                            java2int(hardwareVersion(2)), ...
40                                            java2int(hardwareVersion(3)));
41    fprintf("Firmware Version: %d.%d.%d\n", java2int(firmwareVersion(1)), ...
42                                            java2int(firmwareVersion(2)), ...
43                                            java2int(firmwareVersion(3)));
44    fprintf("Device Identifier: %d\n", e.deviceIdentifier);
45    fprintf("\n");
46end
47
48function int = java2int(value)
49    if compare_versions(version(), "3.8", "<=")
50        int = value.intValue();
51    else
52        int = value;
53    end
54end

Authenticate (Octave)

Download (octave_example_authenticate.m)

 1function octave_example_authenticate()
 2    more off;
 3
 4    global SECRET;
 5
 6    HOST = "localhost";
 7    PORT = 4223;
 8    SECRET = "My Authentication Secret!";
 9
10    ipcon = javaObject("com.tinkerforge.IPConnection"); % Create IP connection
11
12    % Disable auto reconnect mechanism, in case we have the wrong secret.
13    % If the authentication is successful, reenable it.
14    ipcon.setAutoReconnect(false)
15
16    % Register Connected Callback
17    ipcon.addConnectedCallback(@cb_connected);
18
19    % Register Enumerate Callback
20    ipcon.addEnumerateCallback(@cb_enumerate);
21
22    ipcon.connect(HOST, PORT); % Connect to brickd
23
24    input("Press any key to exit...\n", "s");
25    ipcon.disconnect();
26end
27
28% Authenticate each time the connection got (re-)established
29function cb_connected(e)
30    ipcon = e.getSource();
31
32    global SECRET;
33
34    if java2int(e.connectReason) == java2int(ipcon.CONNECT_REASON_REQUEST)
35        fprintf("Connected by request\n");
36    elseif java2int(e.connectReason) == java2int(ipcon.CONNECT_REASON_AUTO_RECONNECT)
37        fprintf("Auto-Reconnect\n");
38    end
39
40    % Authenticate first...
41    try
42        ipcon.authenticate(SECRET);
43        fprintf("Authentication succeeded\n");
44    catch ex
45        fprintf("Could not authenticate\n");
46        return
47    end
48
49    % ...reenable auto reconnect mechanism, as described above...
50    ipcon.setAutoReconnect(true)
51
52    % ...then trigger enumerate
53    ipcon.enumerate();
54end
55
56% Print incoming enumeration
57function cb_enumerate(e)
58    fprintf("UID: %s, Enumeration Type: %d\n", e.uid, e.enumerationType);
59end
60
61function int = java2int(value)
62    if compare_versions(version(), "3.8", "<=")
63        int = value.intValue();
64    else
65        int = value;
66    end
67end

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.

In MATLAB:

import com.tinkerforge.IPConnection;

ipcon = IPConnection();

In Octave:

ipcon = java_new("com.tinkerforge.IPConnection");
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 eine WIFI/Ethernet Extension verweisen.

Bricks/Bricklets können erst gesteuert werden, wenn die Verbindung erfolgreich aufgebaut wurde.

Blockiert bis die Verbindung aufgebaut wurde und gibt einen Fehlercode zurück 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.

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

  • IPConnection.CONNECTION_STATE_PENDING = 2: IP Connection versucht im Moment eine Verbindung aufzubauen.

void IPConnection.setAutoReconnect(boolean autoReconnect)

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.

boolean IPConnection.getAutoReconnect()

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

void IPConnection.setTimeout(int timeout)

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

Standardwert ist 2500.

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.

Callbacks

Callbacks können registriert werden um zeitkritische oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung wird mit MATLABs "set" Funktion durchgeführt. Die Parameter sind ein IP Connection Objekt, der Callback-Name und die Callback-Funktion. Hier ein Beispiel in MATLAB:

function my_callback(e)
    fprintf('Parameter: %s\\n', e.param);
end

set(ipcon, 'ExampleCallback', @(h, e) my_callback(e));

Die Octave Java Unterstützung unterscheidet sich hier von MATLAB, die "set" Funktion kann hier nicht verwendet werden. Die Registrierung wird in Octave mit "add*Callback" Funktionen des IP Connection Objekts durchgeführt. Hier ein Beispiel in Octave:

function my_callback(e)
    fprintf("Parameter: %s\\n", e.param);
end

ipcon.addExampleCallback(@my_callback);

Es ist möglich mehrere Callback-Funktion hinzuzufügen und auch mit einem korrespondierenden "remove*Callback" wieder zu entfernen.

Die Parameter des Callbacks werden der Callback-Funktion als Felder der Struktur e übergeben. Diese ist von der java.util.EventObject Klasse abgeleitete. Die verfügbaren Callback-Namen mit den entsprechenden Strukturfeldern werden unterhalb beschrieben.

callback IPConnection.EnumerateCallback
Parameter:

  • uid -- String

  • connectedUid -- String

  • position -- char

  • hardwareVersion -- short[]

  • firmwareVersion -- short[]

  • deviceIdentifier -- int

  • enumerationType -- short

Der Callback empfängt sieben Parameter als Felder er Struktur e:

  • 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 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-class>.DEVICE_IDENTIFIER

Zum Beispiel: BrickMaster.DEVICE_IDENTIFIER oder BrickletAmbientLight.DEVICE_IDENTIFIER.

In MATLAB kann die set() Function verwendet werden um diesem Callback eine Callback-Function zuzuweisen.

In Octave kann diesem Callback mit addEnumerateCallback() eine Callback-Function hinzugefügt werde. Eine hinzugefügter Callback-Function kann mit removeEnumerateCallback() wieder entfernt werden.

callback IPConnection.ConnectedCallback
Parameter:

connectReason -- short

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.

In MATLAB kann die set() Function verwendet werden um diesem Callback eine Callback-Function zuzuweisen.

In Octave kann diesem Callback mit addConnectedCallback() eine Callback-Function hinzugefügt werde. Eine hinzugefügter Callback-Function kann mit removeConnectedCallback() wieder entfernt werden.

callback IPConnection.DisconnectedCallback
Parameter:

disconnectReason -- short

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.

In MATLAB kann die set() Function verwendet werden um diesem Callback eine Callback-Function zuzuweisen.

In Octave kann diesem Callback mit addDisconnectedCallback() eine Callback-Function hinzugefügt werde. Eine hinzugefügter Callback-Function kann mit removeDisconnectedCallback() wieder entfernt werden.