This is the description of the Shell API bindings for the IP Connection. The IP Connection manages the communication between the API bindings and the Brick Daemon or a WIFI/Ethernet Extension. Before Bricks and Bricklets can be controlled using their API an IP Connection has to be created and its TCP/IP connection has to be established.
An installation guide for the Shell API bindings is part of their general description.
The example code below is Public Domain (CC0 1.0).
Download (example-authenticate.sh)
1 2 | #!/bin/sh
tinkerforge --secret "My Authentication Secret" enumerate
|
At first some information about the general command structure:
Parameters: |
|
---|
The basic command can take several options:
All commands, except if the --help or --version option is present, create a TCP/IP connection to the given host and port. The host and port can refer to a Brick Daemon or to a WIFI/Ethernet Extension.
If the --secret option is present then an authentication handshake with the connected Brick Daemon or WIFI/Ethernet Extension is performed. If the handshake succeeds the connection switches from non-authenticated to authenticated state and communication can continue as normal. If the handshake fails then the connection gets closed. Authentication can fail if the wrong secret was used or if authentication is not enabled at all on the Brick Daemon or the WIFI/Ethernet Extension. See the authentication tutorial for more information.
The item separator is used for parsing and formatting arrays. An array with three values 1, 2 and 3 is formatted as 1,2,3.
The group separator is used for formatting the output of callbacks. The group separator is printed before each callback output with more than one line, except before the first one, to separate the output of multiple callback invocations. See the section about output formatting for details.
By default symbolic input and output is enabled. For example, the set-i2c-mode function of the Temperature Bricklet can take two different values: 0 and 1. With symbolic input enabled there are also two symbols fast (0) and slow (1) for this values. The same holds for the get-i2c-mode function: the same two symbols are used for symbolic output, if enabled.
There are four subcommands: call, dispatch, enumerate and listen
Parameters: |
|
---|
The call command is used to call a function of a Brick or Bricklet. It can take several options:
If the --list-devices option is present all valid device names for the <device> argument are listed. For example master-brick and ambient-light-bricklet.
The --timeout option allows to specify the maximum time in ms for waiting for the response of a function call. If a response doesn't arrive in time the program exits with an error.
The <uid> argument takes a UID corresponding to the selected device type. This allows to select a specific device. All connected Bricks and Bricklets can be found with the enumerate command.
The <function> argument allows to specify which function to call. Which additional arguments have to be specified depends on the specified device and function.
Parameters: |
|
---|
The dispatch command is used handle incoming callbacks of a Brick or Bricklet. It can take several options:
If the --list-devices option is present all valid device names for the <device> argument are listed. For example master-brick and ambient-light-bricklet.
The --duration option allows to specify the time in ms for dispatching incoming callbacks.
The <uid> argument takes a UID corresponding to the selected device type. This allows to select a specific device. All connected Bricks and Bricklets can be found with the enumerate command.
The <callback> argument allows to specify which callback to dispatch.
Output: |
|
---|
The enumerate command is used to discover the connected Bricks and Bricklets. It can take several options:
The --duration option allows to specify the time in ms for dispatch incoming enumerate responses.
The --types option allows to specify which types of enumerate callbacks to dispatch. By default only enumerate callbacks with enumeration-type=available are dispatched.
The --execute option allows for advanced output formatting. See the section about this for details.
The command has seven output values:
Possible enumeration types are:
The device identifier numbers can be found here.
The listen command is used to open a TCP/IP socket that accepts call, dispatch and enumerate commands. This enables the Shell bindings to act as a text protocol proxy for clients such as netcat, telnet or the NetIO Controller App. The listen command can take several options:
In listen mode some command line options are disabled by default for incoming commands.
The --host and --port options are disabled by default so incoming commands can only connect to the host and port given to the listen command. Use --enable-host and --enable-port to enable these options for incoming commands.
The --execute option for getter calls and callback dispatching is disabled by default so incoming command cannot execute other commands. Use --enable-execute to enable this option for incoming commands.
Incoming commands have to be terminated by \n. The output is also terminated by \n. See the output formatting section for details.
New in version 2.0.3.
By default the output of getters and callbacks is printed in <key>=<value> format. For example, the output of an enumerate callback:
$ 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
The --item-separator option affects how arrays are formatted and the --group-separator option affects how output groups are formatted. The example above contains two groups separated by a blank line.
The output in listen mode (see tinkerforge listen) differs in two aspects to simplify parsing on the client side:
This means the output for the enumerate command looks like this in listen mode:
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
For more advanced output formatting all getter functions and callbacks support the --execute option. It takes a shell command line with placeholders to be executed for each incoming response.
A simple example: getting the current distance in mm of a Distance IR Bricklet in <key>=<value> format:
$ tinkerforge call distance-ir-bricklet eN3 get-distance
distance=473
Now the --execute option is used for advanced formatting with bc and printf:
$ 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
Before the command line is executed the contained placeholders are replaced with the actual values. In the example above a call to get-distance without --execute outputs a single line with key distance. This key is also the placeholder for --execute usage wrapped in curly brackets: {distance}.
In listen mode (see tinkerforge listen) the --execute option is not available by default and has to be enabled by the --enable-execute option of the listen command.