MQTT - API Bindings

The MQTT bindings allow you to control Bricks and Bricklets using the MQTT protocol. The ZIP file for the bindings contains:

  • tinkerforge_mqtt a Python script that acts as a translation proxy between a MQTT broker and a Brick Daemon
  • in examples/ the examples for every Brick and Bricklet

The MQTT bindings are based on the Python bindings.

Requirements

  • Python 2.7.9 or newer with argparse module, Python 3.4 or newer is also supported.
  • Paho's Python library 1.3.1 or newer.

Installation

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

To install the bindings copy the tinkerforge_mqtt file to a folder that is in the PATH. For example, this folder on Linux and macOS:

/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_mqtt.bat file in the Scripts\ folder with the following content:

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

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

Testing an Example

To test a MQTT 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.

Then run the tinkerforge_mqtt script, configured to connect to your Brick Daemon and MQTT broker, using the command line switches. See the output of tinkerforge_mqtt --help.

All examples are written in pseudo code, you have to translate them to your favorite programming language before running them. Alternatively you can use the mosquitto_pub and mosquitto_sub commands, which are part of the Mosquitto MQTT broker.

The examples consist of a setup and a cleanup block. The setup block configures devices and callbacks, the cleanup block stops them. Not all examples have a cleanup block.

The pseudo code denotes MQTT publish operations as publish <PAYLOAD> to <TOPIC> and subscribe operations as subscribe to <TOPIC>. Subscriptions optionally contain logic which should be run if a message arrives. These blocks end with endsubscribe.

MQTT Topics

MQTT topics are structured as follows: [<GLOBAL_PREFIX>/]<OPERATION>/<DEVICE>[/<UID>]/<FUNCTION>[/<SUFFIX>]

[<GLOBAL_PREFIX>/] is the global prefix for all topics (default: tinkerforge/). It can be changed using the --global-topic-prefix command line flag. The prefix can be used to disambiguate multiple instances of the MQTT Bindings. It can contain multiple topic levels, for example tinkerforge/living_room/sensors/. If the prefix does not end with a '/', one is inserted, except if you select an empty prefix. Then all topics start with the operation. Note that this is not recommended. Also note, that '/' is a valid prefix.

<OPERATION> denotes the type of request. It can be one of request, response, register or callback. The bindings subscribe to request and register topics and will publish answers to requests under response, answers to register under callback topics.

<DEVICE> is the type of device you want to interact with. This can be the name of a Brick or Bricklet in snake_case, for example oled_64x48_bricklet, or ip_connection. See the documentation of devices for the exact spelling.

[/<UID>] is the UID of the device. If the device is the ip_connection, this has to be empty and with no slashes, for example: .../ip_connection/enumerate

<FUNCTION> is the function to call, or the callback to register to, written in snake_case.

[/<SUFFIX>] is the optional suffix to attach to responses. This can be used to allow message filtering, for example by setting it to /STATUS for requests or callback registrations which query status information. Another MQTT client can then register to [<GLOBAL_PREFIX>/]+/+/+/+/STATUS to receive all status information tagged as such.

A typical request topic looks like this: tinkerforge/request/rgb_led_button_bricklet/Dod/get_color. The response to this request (or an error) will be published under tinkerforge/response/rgb_led_button_bricklet/Dod/get_color by the bindings.

A callback registration topic looks like this: tinkerforge/register/rgb_led_button_bricklet/Dod/button_state_changed. If you subscribe to tinkerforge/callback/rgb_led_button_bricklet/Dod/button_state_changed you will receive a message each time the button is pressed or released.

MQTT Payload

All MQTT payload is encoded as JSON objects, each member maps to a parameter or return value of the corresponding function in the Python bindings. Occurred errors are logged to stdout as well as inserted into returned JSON objects under the _ERROR field.

If symbolic output is not disabled (using the --no-symbolic-response command line flag), integer constants are translated to strings. For example the button_state_changed callback of the RGB LED Button Bricklet will be {"state": "pressed"} instead of {"state:" 0}.

Integer constants in request payloads can also be replaced by their associated symbols. For example publishing {"config": "show_heartbeat"} to tinkerforge/request/rgb_led_button_bricklet/Dod/set_status_led_config is equivalent to publishing {"config": 2}.

Symbols for constants are documented where they are available.

Callback (de)registrations can use either {"register": true/false} or true/false as payload.

Requests and Responses

To call a Brick or Bricklet function, publish a JSON encoded message under the corresponding 'request' topic. For example to set the color of a RGB LED Button Bricklet with UID Enx to yellow using the mosquitto_pub tool:

mosquitto_pub -t tinkerforge/request/rgb_led_button_bricklet/Enx/set_color -m '{"red":255, "green":127, "blue":0}'

Functions which return values do so under the corresponding 'response' topic. To query the current color of the same Bricklet use:

mosquitto_sub -t tinkerforge/response/rgb_led_button_bricklet/Enx/get_color
mosquitto_pub -t tinkerforge/request/rgb_led_button_bricklet/Enx/get_color -m ''

Occured errors are published under the 'response' topic. If for example a parameter is missing:

mosquitto_sub -t tinkerforge/response/rgb_led_button_bricklet/Enx/set_color
mosquitto_pub -t tinkerforge/request/rgb_led_button_bricklet/Enx/set_color -m '{"red":255, "blue":0}'

The message:

{"_ERROR": "The arguments ['green'] where missing for a call of set_color of device Enx of type rgb_led_button_bricklet."}

is published under tinkerforge/response/rgb_led_button_bricklet/Enx/set_color. Error messages are also printed to the binding's stdout.

Callbacks

Callbacks can be registered under the 'register' topic:

mosquitto_pub -t tinkerforge/register/rgb_led_button_bricklet/Enx/button_state_changed -m 'true'

and will be published under the 'callback' topic:

mosquitto_sub -t tinkerforge/callback/rgb_led_button_bricklet/Enx/button_state_changed

returns:

{"state": 0}
{"state": 1}

whenever the button is pressed and released.

To deregister a callback, pass 'false' as payload instead of 'true'. It is also possible to use {"register":  true} and {"register": false} as (de)registration arguments.

Callback configuration functions work exactly like in other bindings, so if a callback has to be activated and/or configured you need to:

  • subscribe to the 'callback' topic
  • publish the registation to the callback using the 'register' topic
  • publish the configuration of the callbacks properties such as period
  • publish the callback activation with the corresponding 'request' topic

Loading initial messages from a file

Messages to be processed when the bindings are started, can be read from a file. Use the --init-file /path/to/file command line argument to specify one. These files can (for example) be used to configure and register callbacks. The file is expected to contain a JSON object with MQTT topics as attribute names. The attribute values are JSON objects as used as MQTT payload. The following example shows a file which registers the all_data callback of a IMU Brick 2.0 and configures the period of the callback to 100ms:

{
    "tinkerforge/register/imu_v2_brick/XXYYZZ/all_data": {"register": true},
    "tinkerforge/request/imu_v2_brick/XXYYZZ/set_all_data_period": {"period": 100}
}

Topic prefix

The bindings can be configured to use another global prefix for all topics using the '--global-topic-prefix' parameter. The prefix can be used to disambiguate between two or more binding instances connected to the same broker. The prefix can be as long as needed, for example tf/instance/1/foo/bar.

Topic suffixes

The bindings support arbitrary suffixes per topic. For example you can tag all messages of devices located in the same room with a room number:

mosquitto_pub -t tinkerforge/register/rgb_led_button_bricklet/Enx/button_state_changed/room/1 -m 'true'
mosquitto_pub -t tinkerforge/register/rgb_led_button_bricklet/gBs/button_state_changed/room/2 -m 'true'
mosquitto_pub -t tinkerforge/register/rgb_led_button_bricklet/Dod/button_state_changed/room/1 -m 'true'

To receive all callbacks sent from devices in room 1 subscribe to:

mosquitto_sub -t tinkerforge/callback/+/+/+/room/1

This subscription will receive callback events generated by 'Enx' and 'Dod' but not 'gBs'.

To receive all messages subscribe to:

mosquitto_sub -t tinkerforge/callback/#
mosquitto_sub -t tinkerforge/response/#

Start up

The bindings will publish a message to [GLOBAL_PREFIX]/callback/bindings/restart with 'null' as payload. This message can be used as a signal that the bindings where restarted. You then need to re-register all required callbacks.

Command line arguments

  • -h, --help show this help message and exit
  • --ipcon-host <IPCON_HOST> hostname or IP address of Brick Daemon, WIFI or Ethernet Extension (default: localhost)
  • --ipcon-port <IPCON_PORT> port number of Brick Daemon, WIFI or Ethernet Extension (default: 4223)
  • --ipcon-auth-secret <IPCON_AUTH_SECRET> authentication secret of Brick Daemon, WIFI or Ethernet Extension
  • --ipcon-timeout <IPCON_TIMEOUT> timeout in milliseconds for communication with Brick Daemon, WIFI or Ethernet Extension (default: 2500)
  • --broker-host <BROKER_HOST> hostname or IP address of MQTT broker (default: localhost)
  • --broker-port <BROKER_PORT> port number of MQTT broker (default: 1883)
  • --broker-username <BROKER_USERNAME> username for the MQTT broker connection
  • --broker-password <BROKER_PASSWORD> password for the MQTT broker connection
  • --broker-certificate <BROKER_CERTIFICATE> Certificate Authority certificate file used for SSL/TLS connections to the broker
  • --broker-tls-insecure disable verification of the server hostname in the server certificate for the MQTT broker connection
  • --global-topic-prefix <GLOBAL_TOPIC_PREFIX> global MQTT topic prefix (default: tinkerforge/)
  • --debug enable debug output
  • --no-symbolic-response disable translation into string constants for responses
  • --show-payload show received payload if JSON parsing fails
  • --init-file <INIT_FILE> file from where to load initial messages to publish

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.

Name API Examples
IP Connection API Examples
     
Bricks    
DC API Examples
IMU 2.0 API Examples
Master API Examples
RED API Examples
Servo API Examples
Silent Stepper API Examples
Stepper API Examples
     
Bricks (Discontinued)    
IMU API Examples
     
Bricklets    
Accelerometer API Examples
Accelerometer 2.0 API Examples
Air Quality API Examples
Ambient Light 3.0 API Examples
Analog In 3.0 API Examples
Analog Out 2.0 API Examples
Analog Out 3.0 API Examples
Barometer API Examples
Barometer 2.0 API Examples
CAN API Examples
CAN 2.0 API Examples
CO2 2.0 API Examples
Color API Examples
Distance IR API Examples
Distance IR 2.0 API Examples
DMX API Examples
Dual Button API Examples
Dual Button 2.0 API Examples
Dual Relay API Examples
Dust Detector API Examples
E-Paper 296x128 API Examples
GPS 2.0 API Examples
Hall Effect API Examples
Hall Effect 2.0 API Examples
Humidity 2.0 API Examples
Industrial Analog Out API Examples
Industrial Analog Out 2.0 API Examples
Industrial Counter API Examples
Industrial Digital In 4 2.0 API Examples
Industrial Digital Out 4 API Examples
Industrial Digital Out 4 2.0 API Examples
Industrial Dual 0-20mA API Examples
Industrial Dual 0-20mA 2.0 API Examples
Industrial Dual Analog In API Examples
Industrial Dual Analog In 2.0 API Examples
Industrial Dual Relay API Examples
Industrial Quad Relay 2.0 API Examples
IO-16 API Examples
IO-16 2.0 API Examples
IO-4 2.0 API Examples
Isolator API Examples
Joystick API Examples
Joystick 2.0 API Examples
Laser Range Finder 2.0 API Examples
LCD 128x64 API Examples
LCD 20x4 API Examples
LED Strip 2.0 API Examples
Line API Examples
Linear Poti API Examples
Linear Poti 2.0 API Examples
Load Cell 2.0 API Examples
Moisture API Examples
Motion Detector API Examples
Motion Detector 2.0 API Examples
Motorized Linear Poti API Examples
Multi Touch API Examples
NFC API Examples
OLED 128x64 API Examples
OLED 128x64 2.0 API Examples
OLED 64x48 API Examples
One Wire API Examples
Outdoor Weather API Examples
Particulate Matter API Examples
Piezo Speaker API Examples
Piezo Speaker 2.0 API Examples
PTC 2.0 API Examples
Real-Time Clock API Examples
Real-Time Clock 2.0 API Examples
Remote Switch 2.0 API Examples
RGB LED API Examples
RGB LED 2.0 API Examples
RGB LED Button API Examples
Rotary Encoder 2.0 API Examples
Rotary Poti API Examples
RS232 API Examples
RS232 2.0 API Examples
RS485 API Examples
Segment Display 4x7 API Examples
Segment Display 4x7 2.0 API Examples
Solid State Relay 2.0 API Examples
Sound Intensity API Examples
Sound Pressure Level API Examples
Temperature API Examples
Temperature 2.0 API Examples
Temperature IR 2.0 API Examples
Thermal Imaging API Examples
Thermocouple 2.0 API Examples
Tilt API Examples
UV Light API Examples
UV Light 2.0 API Examples
Voltage/Current 2.0 API Examples
     
Bricklets (Discontinued)    
Ambient Light API Examples
Ambient Light 2.0 API Examples
Analog In API Examples
Analog In 2.0 API Examples
Analog Out API Examples
CO2 API Examples
Current12 API Examples
Current25 API Examples
Distance US API Examples
GPS API Examples
Humidity API Examples
Industrial Digital In 4 API Examples
Industrial Quad Relay API Examples
IO-4 API Examples
Laser Range Finder API Examples
LCD 16x2 API Examples
LED Strip API Examples
Load Cell API Examples
NFC/RFID API Examples
Piezo Buzzer API Examples
PTC API Examples
Remote Switch API Examples
RGB LED Matrix API Examples
Rotary Encoder API Examples
Solid State Relay API Examples
Temperature IR API Examples
Thermocouple API Examples
Voltage API Examples
Voltage/Current API Examples