Shell - IP Connection¶

Beispiele¶

Der folgende Beispielcode ist Public Domain (CC0 1.0).

1
2
3
4
5
6
7
8
9

#!/bin/sh
# Connects to localhost:4223 by default, use --host and --port to change this

# Trigger enumerate
tinkerforge enumerate &

echo "Press key to exit"; read dummy

kill -- -$$ # Stop callback dispatch in background

1
2
3
4
5
6
7
8
9

#!/bin/sh
# Connects to localhost:4223 by default, use --host and --port to change this

# Trigger enumerate with authentication
tinkerforge --secret "My Authentication Secret" enumerate &

echo "Press key to exit"; read dummy

kill -- -$$ # Stop callback dispatch in background

API¶

Als erstes einige Information über die allgemeine Struktur der Befehle:

tinkerforge [<option>..] <command> [<argument>..]¶

Parameter:	<command> -- string

Der Grundbefehl kennt mehrere Optionen:

• --help zeigt allgemeine Hilfe an und endet dann
• --version zeigt die Versionsnummer an und endet dann
• --host <host> IP Adresse oder Hostname des Verbindungsziels, Standard: localhost
• --port <port> Port-Nummer des Verbindungsziels, Standard: 4223
• --secret <secret> Geheimnis für die Authentifizierung (neu in Version 2.1.0)
• --item-separator <item-separator> Trennzeichen für Array-Einträge, Standard: , (Komma)
• --group-separator <group-separator> Trennzeichen für Ausgabegruppen, Standard: \n (neue Zeile)
• --array-ellipsis <array-ellipsis> Auslassung für Arrays, Standard: .. (zwei Punkte) (neu in Version 2.1.5)
• --no-escaped-input deaktiviert escapte Eingabe von Werten (neu in Version 2.1.5)
• --no-escaped-output deaktiviert escapte Ausgabe von Werten (neu in Version 2.1.5)
• --no-symbolic-input deaktiviert symbolische Eingabe von Werten
• --no-symbolic-output deaktiviert symbolische Ausgabe von Werten

Alle Befehle, außer die --help oder --version Option sind angegeben, erstellen eine TCP/IP Verbindung zum gegebenen host und port. Host und Port können auf einen Brick Daemon oder eine WIFI/Ethernet Extension verweisen.

Seit Version 2.1.0 kann die --secret Option angegeben werden, um ein Authentifizierungs-Handshake mit dem verbundenen Brick Daemon oder WIFI/Ethernet Extension durchgeführt. 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.

Das Trennzeichen für Array-Einträge wird beim Parse und Formatieren von Arrays verwendet. Ein Array mit den drei Werten 1, 2 und 3 wird als 1,2,3 formatiert.

Das Trennzeichen für Ausgabegruppen wird beim Formatieren der Ausgabe von Callbacks verwendet. Das Trennzeichen wird vor jeder Callback-Ausgabe mit mehr als einer Zeile ausgegeben, außer der ersten, um die Ausgabe von mehreren Callback-Aufrufen zu trennen. Siehe den Abschnitt über Ausgabeformatierung für mehr Details.

Seit Version 2.1.5 kann ein Auslassungszeichen für Arrays verwendet werden, um unvollständig Arrays anzugeben. Zum Beispiel nimmt die write Funktion des RS232 Bricklets einen Array mit 60 Zeichen entgegen. Normalerweise, müssten immer alle 60 Zeichen angegeben werden. Mit einem Auslassungszeichen kann der Array unvollständig angegeben werden (z.B. t,e,s,t,..) und der fehlende Teil wird automatisch mit '\0' Zeichen aufgefüllt.

Seit Version 2.1.5 ist die escapte Eingabe und Ausgabe standardmäßig aktiviert. Zum Beispiel nimmt die write-line Funktion des LCD 20x4 Bricklet einen String entgegen. Dieser muss entsprechend des speziellen Zeichensatzes des LCDs angegeben werden. Zum Beispiel wird das Gradzeichen (°) durch ein nicht-ASCII Zeichen mit dem Wert 0xDF repräsentiert. Mit escapter Eingabe kann diese Zeichen als "\xDF" im Befehl angegeben werden. Achte darauf solche Strings in Anführungszeichen zu setzen, damit die Shell diesen nicht interpretiert. Bei aktiver escapter Ausgabe werden nicht-ASCII Zeichen in String-Werten als \x Escape-Sequenzen dargestellt.

Standardmäßig ist die symbolische Eingabe und Ausgabe aktiviert. Zum Beispiel kann die set-i2c-mode Funktion des Temperature Bricklets mit zwei verschiedenen Werten aufgerufen werden: 0 und 1. Wenn symbolische Eingabe aktiviert ist, dann werden auch noch die beiden Symbole fast (0) und slow (1) als Eingabe für diese Werte akzeptiert. Das gleiche gilt für die get-i2c-mode Funktion: Die gleichen Symbole werden für symbolische Ausgabe verwendet, wenn diese aktiviert ist.

Es gibt vier Unterbefehle: call, dispatch, enumerate und listen

tinkerforge call [<option>..] <device> <uid> <function> [<argument>..]¶

Parameter:	<device> -- string <uid> -- string <function> -- string

Der call Befehl wird verwendet um eine Funktion eines Bricks oder Bricklets aufzurufen. Der Befehl kennt mehrere Optionen:

• --help zeigt Hilfe für den spezifischen call Befehl an und endet dann
• --list-devices zeigt eine Liste der bekannten Geräte an und enden dann
• --timeout <timeout> maximale Zeit (msec) für die auf eine Antwort gewartet wird, Standard: 2500

Wenn die --list-devices Option angegeben ist werden alle bekannten Gerätenamen für das <device> Argument aufgelistet. Zum Beispiel master-brick und ambient-light-bricklet.

Die --timeout Option erlaubt es die maximale Zeit in msec festzulegen für die auf einen Antwort auf einen Funktionsaufruf gewartet wird. Falls eine Antwort nicht rechtzeitig eintrifft, dann wird das Programm mit einem Fehler beendet.

Das <uid> Argument nimmt eine UID entsprechend dem gewählten Gerätetypen. Dies erlaubt es ein spezifisches Gerät auszuwählen. Alle verbundenen Bricks und Bricklets können mittels des enumerate Befehls entdeckt werden.

Das <function> Argument gibt an welche Funktion aufgerufen werden soll. Welche weiteren Argumente angegeben werden müssen hängt von der ausgewählten Funktion ab.

tinkerforge dispatch [<option>..] <device> <uid> <callback>¶

Parameter:	<device> -- string <uid> -- string <callback> -- string

Der dispatch Befehl wird verwendet um eingehende Callbacks eines Bricks oder Bricklets abzufertigen. Der Befehl kennt mehrere Optionen:

• --help zeigt Hilfe für den spezifischen dispatch Befehl an und endet dann
• --list-devices zeigt eine Liste der bekannten Geräte an und enden dann
• --duration <duration> die Zeit (msec) für die eingehende Callbacks abgefertigt werden (0: Ende nach dem ersten Callback, -1: unbegrenzt), Standard: -1

Wenn die --list-devices Option angegeben ist werden alle bekannten Gerätenamen für das <device> Argument aufgelistet. Zum Beispiel master-brick und ambient-light-bricklet.

Die --duration Option erlaubt es die Zeit in msec festzulegen für die eingehende Callbacks abgefertigt werden.

Das <uid> Argument nimmt eine UID entsprechend dem gewählten Gerätetypen. Dies erlaubt es ein spezifisches Gerät auszuwählen. Alle verbundenen Bricks und Bricklets können mittels des enumerate Befehls entdeckt werden.

Das <callback> Argument gibt an welcher Callback abgefertigt werden soll.

$ tinkerforge enumerate
uid=68yjBL
connected-uid=0
position=0
hardware-version=1,0,0
firmware-version=2,0,6
device-identifier=master-brick
enumeration-type=available

uid=eN3
connected-uid=68yjBL
position=a
hardware-version=1,1,0
firmware-version=2,0,0
device-identifier=distance-ir-bricklet
enumeration-type=available

uid=68yjBL\tconnected-uid=0\tposition=0\thardware-version=1,0,0\tfirmware-version=2,0,6\tdevice-identifier=master-brick\tenumeration-type=available\n
uid=eN3\tconnected-uid=68yjBL\tposition=a\thardware-version=1,1,0\tfirmware-version=2,0,0\tdevice-identifier=distance-ir-bricklet\tenumeration-type=available\n

$ tinkerforge call distance-ir-bricklet eN3 get-distance
distance=473

$ tinkerforge call distance-ir-bricklet eN3 get-distance\
  --execute "echo 'scale=2; {distance} / 10' | bc | xargs printf 'current distance is %.1fcm\n'"
current distance is 46.3cm