Shell - IP Connection – Tinkerforge

- Getting Started
  - Primer
  - Tutorials
  - FAQ
- Hardware
  - Bricks
  - Bricklets
  - Master Extensions
  - Power Supplies
  - Accessories
  - Timeline
- Software
  - Brick Daemon (brickd)
  - Brick Viewer (brickv)
  - API Bindings
    - C/C++
    - C/C++ (iOS)
    - C#
    - C# (Windows Phone)
    - Delphi/Lazarus
    - Java
    - Java (Android)
    - JavaScript
    - LabVIEW
    - Mathematica
    - MATLAB/Octave
    - Perl
    - PHP
    - Python
    - Ruby
    - Shell
      - Requirements
      - Installation
      - Testing an Example
      - API Reference and Examples
        - IP Connection
          - Examples
            - Enumerate
            - Authenticate
          - API
            - Basic Functions
            - Advanced Functions
              - NetIO Controller App Setup
            - Output Formatting
              - Advanced Options
        - Bricks
        - Bricklets
    - Visual Basic .NET
  - Firmwares and Plugins
  - Device Identifier
  - Source Code and Bug Tracking
  - Programming Interface
- Starter Kits
  - Weather Station
  - Hardware Hacking
  - Server Room Monitoring
  - Blinkenlights
  - Internet of Things
  - Camera Slider
- Embedded Boards
  - Raspberry Pi
- Specifications
  - Technical Data
  - TCP/IP Protocol
  - Modbus Protocol
  - Wireshark Dissector

# Shell - IP Connection

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.

## Examples

The example code below is Public Domain (CC0 1.0).

### Enumerate

Download (example-enumerate.sh)

    1
    2

    #!/bin/sh
    tinkerforge enumerate

### Authenticate

Download (example-authenticate.sh)

    1
    2

    #!/bin/sh
    tinkerforge --secret "My Authentication Secret" enumerate

## API

At first some information about the general command structure:

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

  Parameters:

  - <command> -- string

  The basic command can take several options:

  - `--help` shows general help and exits
  - `--version` shows version number and exits
  - `--host <host>` IP address or hostname to connect to, default: `localhost`
  - `--port <port>` port number to connect to, default: 4223
  - `--secret <secret>` secret for authentication (new in version 2.1.0)
  - `--item-separator <item-separator>` separator for array items, default: `,` (comma)
  - `--group-separator <group-separator>` separator for output groups, default: `\n` (newline)
  - `--no-symbolic-input` disables symbolic input of values
  - `--no-symbolic-output` disables symbolic output of values

  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`

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

  Parameters:

  - <device> -- string
  - <uid> -- string
  - <function> -- string

  The `call` command is used to call a function of a Brick or Bricklet. It can take several options:

  - `--help` shows help for the `call` command and exits
  - `--list-devices` shows a list of known devices and exits
  - `--timeout <timeout>` maximum time (ms) to wait for response, default: 2500

  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.

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

  Parameters:

  - <device> -- string
  - <uid> -- string
  - <callback> -- string

  The `dispatch` command is used handle incoming callbacks of a Brick or Bricklet. It can take several options:

  - `--help` shows help for the `dispatch` command and exits
  - `--list-devices` shows a list of known devices and exits
  - `--duration <duration>` time (ms) to dispatch incoming callbacks (0: exit after first, -1: forever), default: -1

  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.

### Basic Functions

`tinkerforge` `enumerate` [<option>..]

  Output:

  - uid -- string
  - connected-uid -- string
  - position -- char
  - hardware-version -- int,int,int
  - firmware-version -- int,int,int
  - device-identifier -- int (has symbols)
  - enumeration-type -- int (has symbols)

  The `enumerate` command is used to discover the connected Bricks and Bricklets. It can take several options:

  - `--help` shows help for the `enumerate` command and exits
  - `--duration <duration>` time (ms) to dispatch incoming responses (0: exit after first, -1: forever), default: 250
  - `--types <types>` array of enumeration types to dispatch, default: `available`
  - `--execute <command>` shell command to execute for each incoming response

  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:

  - `uid` is the UID of the device.
  - `connected-uid` is the UID where the device is connected to. For a Bricklet this will be a UID of the Brick where it is connected to. For a Brick it will be the UID of the bottom Master Brick in the stack. For the bottom Master Brick in a stack this will be "0". With this information it is possible to reconstruct the complete network topology.
  - `position` is position in stack (0 - 8) for Bricks or the position on Brick (a - d) for Bricklets.
  - `hardware-version` is in major, minor and release format.
  - `firmware-version` is in major, minor and release format.
  - `device-identifier` is the name of the device as known from the `--list-devices` option of the `call` and `dispatch` commands. With symbolic output disabled it is a number that represents the device.
  - `enumeration-type` is the type of enumeration.

  Possible enumeration types are:

  - `available` = 0, the device is available (enumeration triggered by user).
  - `connected` = 1, the device is newly connected (automatically send by Brick after establishing a communication connection). This indicates that the device has potentially lost its previous configuration and needs to be reconfigured.
  - `disconnected` = 2, the device is disconnected (only possible for USB connection). In this case only `uid` and `enumeration-type` are valid.

  The device identifier numbers can be found here.

### Advanced Functions

`tinkerforge` `listen` [<option>..]

  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:

  - `--help` shows help for the `listen` command and exits
  - `--address <address>` IP address to listen to, default: `0.0.0.0`
  - `--port <port>` port number to listen to, default: `4217`
  - `--enable-host` enables `--host` option to override IP address or hostname to connect to
  - `--enable-port` enables `--port` option to override port number to connect to
  - `--enable-execute` enables `--execute` option for getters and callbacks

  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.

### Output Formatting

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:

- no group separator is included in the output and the `--group-separator` option is ignored
- output lines in a group are separated by `\t` instead of `\n`

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

#### Advanced Options

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.

The content of this page is licensed under Creative Commons Attribution 3.0 Unported License.