Shell - API Bindings – 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
        - Bash Completion
      - Testing an Example
      - API Reference and Examples
        - IP Connection
        - 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 - API Bindings

The Shell bindings allow you to control Bricks and Bricklets from your shell scripts. The ZIP file for the bindings contains:

- `tinkerforge`, a Python script that acts as a shell command
- `tinkerforge-bash-completion.sh`, a Bash completion script
- in `examples/` the examples for every Brick and Bricklet

The Shell bindings are based on the Python bindings.

## Requirements

- Python 2.5 or newer with `argparse` module, Python 3 is also supported

## Installation

The Shell bindings can be installed, but can also be used without installation.

To install the bindings copy the `tinkerforge` file to a folder that is in the `PATH`. For example, this folder on Linux and Mac OS X:

    /usr/local/bin/

On Windows the `Scripts/` folder of the Python installation is a good choice:

    C:\Python27\Scripts\

To be able to call the bindings directly on Windows you have to create a `tinkerforge.bat` file in the `Scripts/` folder with the following content:

    @"C:\Python27\python.exe" "C:\Python27\Scripts\tinkerforge"

If your Python is not installed in `C:\Python27\` then you have to adapt the content of the `tinkerforge.bat` file accordingly.

### Bash Completion

IF you're using Bash as your shell then you can use the Bash completion script `tinkerforge-bash-completion.sh`. To install it copy the `tinkerforge-bash-completion.sh` file to the `/etc/bash_completion.d/` an reload the Bash completions with the following command:

    . /etc/bash_completion

The Bash completion for `tinkerforge` can complete options, UIDs, Brick and Bricklet names as well as function and callback names.

## Testing an Example

To test a Shell example Brick Daemon and Brick Viewer have to be installed first. Brick Daemon acts as a proxy between the USB interface of the Bricks and the API bindings. Brick Viewer connects to Brick Daemon and helps to figure out basic information about the connected Bricks and Bricklets.

All examples are meant for typical Unix shells such as Bash. They will work on Linux and Mac OS X as they are. There are Bash ports for Windows that allow to run the examples unmodified, too.

As an example let's test the configuration example for the Stepper Brick. For this copy the `example-configuration.sh` file from the `examples/brick/stepper/` folder into a new folder:

    example_project/
     -> example-configuration.sh

If you did not install the bindings then you have to copy the `tinkerforge` file to the `example_project/` folder too:

    example_project/
     -> tinkerforge
     -> example-configuration.sh

To make the example find the non-installed `tinkerforge` file all occurrences of the `tinkerforge` command in the `example-configuration.sh` file have to be replaced by `./tinkerforge`.

The example starts with a comment about changing the network address using the `--host` and `--port` option if it differs from `localhost:4223`. If the Stepper Brick is connected locally to USB then `localhost` and 4223 is correct.

    # connects to localhost:4223 by default, use --host and --port to change it

To control a Stepper Brick that can be found at host `foobar` and port 5678 the examples has to be changed as follows: each occurrence of the `tinkerforge` command has to be replaced by this:

    tinkerforge --host foobar --port 5678

The `UID` value has to be changed to the UID of the connected Stepper Brick, which you can figure out using Brick Viewer:

    # change to your UID
    uid=XYZ

Now you're ready to test this example:

    ./example-configuration.sh

## API Reference and Examples

Links to the API reference for the IP Connection, Bricks and Bricklets as well as the examples from the ZIP file of the bindings are listed in the following table. Further project descriptions can be found in the Starter Kits section.

| API | Examples
--- | --- | ---
IP Connection | API | Examples
Bricks |  |
DC | API | Examples
IMU | API | Examples
Master | API | Examples
RED | API | Examples
Servo | API | Examples
Stepper | API | Examples
Bricklets |  |
Ambient Light | API | Examples
Analog In | API | Examples
Analog Out | API | Examples
Barometer | API | Examples
Color | API | Examples
Current12 | API | Examples
Current25 | API | Examples
Distance IR | API | Examples
Distance US | API | Examples
Dual Button | API | Examples
Dual Relay | API | Examples
GPS | API | Examples
Hall Effect | API | Examples
Humidity | API | Examples
Industrial Digital In 4 | API | Examples
Industrial Digital Out 4 | API | Examples
Industrial Dual 0-20mA | API | Examples
Industrial Quad Relay | API | Examples
IO-16 | API | Examples
IO-4 | API | Examples
Joystick | API | Examples
LCD 16x2 | API | Examples
LCD 20x4 | API | Examples
LED Strip | API | Examples
Line | API | Examples
Linear Poti | API | Examples
Moisture | API | Examples
Motion Detector | API | Examples
Multi Touch | API | Examples
NFC/RFID | API | Examples
Piezo Buzzer | API | Examples
Piezo Speaker | API | Examples
PTC | API | Examples
Remote Switch | API | Examples
Rotary Encoder | API | Examples
Rotary Poti | API | Examples
Segment Display 4x7 | API | Examples
Solid State Relay | API | Examples
Sound Intensity | API | Examples
Temperature | API | Examples
Temperature IR | API | Examples
Tilt | API | Examples
Voltage | API | Examples
Voltage/Current | API | Examples

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