Brick MQTT Proxy

MQTT is a machine-to-machine (M2M) and Internet of Things (IoT) publish/subscribe message transport protocol. The Brick MQTT Proxy provides access to Bricks and Bricklets over MQTT. It is written in Python and translates messages between the Tinkerforge TCP/IP Protocol (TFP) and MQTT.

Setup and Usage

The proxy is provided as Python script and can be downloaded from its Brick MQTT Proxy GitHub Repository:

wget https://raw.githubusercontent.com/Tinkerforge/brick-mqtt-proxy/master/brick-mqtt-proxy.py

As dependencies the Brick Daemon, the Python API Bindings and the Eclipse Paho MQTT Python client library has to be installed. See the Brick Daemon and Python API Bindings documentation about how to install them. On Linux the Paho MQTT Python client library can be installed using the following command:

sudo pip install paho-mqtt

Afterwards the proxy can be startet with:

python brick-mqtt-proxy.py

Enter the following to get a list of command line arguments for host and port configuration for Brick Daemon and the MQTT broker, data update interval and debug output:

python brick-mqtt-proxy.py --help

Examples

In the following examples we use mosquitto as broker and client. Other broker and clients can be used similarly. To install the broker and client software under Linux do the following:

sudo apt-get install mosquitto mosquitto-clients

Afterwards start the Brick MQTT Proxy and execute the following examples. The structure is described below. Keep in mind to change the UID in the path to that of your Bricklet.

# enumerate all available devices
mosquitto_sub -v -t tinkerforge/enumerate/available/#

# enumerate all available Laser Range Finder Bricklets
mosquitto_sub -v -t tinkerforge/enumerate/available/bricklet/laser_range_finder

# enable laser
mosquitto_pub -t tinkerforge/bricklet/laser_range_finder/vbM/enable_laser/set -m ''

# get distance
mosquitto_sub -v -t tinkerforge/bricklet/laser_range_finder/vbM/distance

# enumerate all available Analog Out 2.0 Bricklets
mosquitto_sub -v -t tinkerforge/enumerate/available/bricklet/analog_out_v2

# get input voltage
mosquitto_sub -v -t tinkerforge/bricklet/analog_out_v2/7xwQ9g/input_voltage

# get output voltage
mosquitto_sub -v -t tinkerforge/bricklet/analog_out_v2/7xwQ9g/output_voltage

# set output voltage to 2.5V
mosquitto_pub -t tinkerforge/bricklet/analog_out_v2/7xwQ9g/input_voltage -m '{"voltage":2500}'

Topic and Payload Structure

The topics are split into device (currently only bricklet/) and enumerate/ topics.

Devices

The proxy publishes retained messages about value and configuration changes of supported devices on topics with the following pattern:

tinkerforge/<prefix>/<uid>/<suffix>

For example, for a Temperature Bricklet with UID XYZ the temperature value is published on:

tinkerforge/bricklet/temperature/XYZ/temperature

The value and configuration information is represented in JSON with the following format:

{
  "_timestamp": <timestamp>,
  "<key>": <value>
}

All messages published by the proxy include a UNIX timestamp to indicate the age of the provided information. The naming and meaning of the key-value pairs matches the payload definition of our TCP/IP protocol. All key-value pairs added by the proxy start with an underscore to avoid name collisions. For example, for a Temperature Bricklet with UID XYZ the temperature value is published as:

{
  "_timestamp": 1440083842.785104,
  "temperature": 2343
}

The proxy subscribes to topics ending in /set allows you to change the configuration of a device. For example, to change the configuration of an Ambient Light Bricklet 2.0 with UID ABC the following JSON payload:

{
  "illuminance_range": 1,
  "integration_time": 2
}

Can be published to this topic:

tinkerforge/bricklet/ambient_light_v2/ABC/configuration/set

The proxy parse the payload and call the configuration setter accordingly.

Again, the naming and meaning of the key-value pairs matches the payload definition of our TCP/IP protocol. In this case the illuminance range is set to 32000lux and the integration time is set to 150ms.

Enumerate

There are three major enumerate/ subtopics the proxy will publish enumerate events on:

  • tinkerforge/enumerate/available/<device-topic-prefix>: If the list of available devices with a matching topic prefix changes then a retained message with the updated list of all now available devices is published.
  • tinkerforge/enumerate/connected/<device-topic-prefix>: If a new device with a matching topic prefix gets connected then a message with information about the connected device is published.
  • tinkerforge/enumerate/disconnected/<device-topic-prefix>: If a known device with a matching topic prefix gets disconnected then a message with information about the disconnected device is published.

For example, if an LCD 20x4 Bricklet gets connected then this is published on:

tinkerforge/enumerate/connected/bricklet/lcd_20x4

Also, the retained message on tinkerforge/enumerate/available/bricklet/lcd_20x4 is updated. The device information is represented in JSON for all subtopics with the following format:

{
  "_timestamp": <timestamp>,
  "uid": "<uid>",
  "connected_uid": "<connected_uid>",
  "position": "<position>",
  "hardware_version": [<major>, <minor>, <release>],
  "firmware_version": [<major>, <minor>, <release>],
  "device_identifier": <device_identifier>
}

For a Temperature Bricklet it looks like this:

{
  "_timestamp": 1440143404.176469,
  "uid": "se3",
  "connected_uid": "5VihSm",
  "position": "c",
  "hardware_version": [1, 1, 0],
  "firmware_version": [2, 0, 3],
  "device_identifier": 216
}

Supported Device Topics

The table below shows all supported devices with their names, suffixes and links to the corresponding TCP/IP protocol documentation for details about the payloads.

Device Prefix Suffix
Accelerometer Bricklet bricklet/accelerometer acceleration
    temperature
    led_on
    led_on/set
    led_off/set
    configuration
    configuration/set
     
Ambient Light Bricklet bricklet/ambient_light illuminance
     
Ambient Light Bricklet 2.0 bricklet/ambient_light_v2 illuminance
    configuration
    configuration/set
     
Analog In Bricklet bricklet/analog_in voltage
    averaging
    averaging/set
    range
    range/set
     
Analog In Bricklet 2.0 bricklet/analog_in_v2 voltage
    moving_average
    moving_average/set
     
Analog Out Bricklet bricklet/analog_out voltage
    voltage/set
    mode
    mode/set
     
Analog Out Bricklet 2.0 bricklet/analog_out_v2 output_voltage
    output_voltage/set
    input_voltage
     
Barometer Bricklet bricklet/barometer air_pressure
    altitude
    chip_temperature
    reference_air_pressure
    reference_air_pressure/set
    averaging
    averaging/set
     
CO2 Bricklet bricklet/co2 co2_concentration
     
Current12 Bricklet bricklet/current12 current
    over_current
    calibrate/set
     
Current25 Bricklet bricklet/current25 current
    over_current
    calibrate/set
     
Distance IR Bricklet bricklet/distance_ir distance
     
Distance US Bricklet bricklet/distance_us distance_value
    moving_average
    moving_average/set
     
Dual Button Bricklet bricklet/dual_button button_state
    led_state
    led_state/set
    selected_led_state/set
     
Dual Relay Bricklet bricklet/dual_relay state
    state/set
    monoflop/set
    selected_state/set
     
Dust Detector Bricklet bricklet/dust_detector dust_density
    moving_average
    moving_average/set
     
GPS Bricklet bricklet/gps status
    coordinates
    altitude
    motion
    date_time
    restart/set
     
Hall Effect Bricklet bricklet/hall_effect value
    edge_count_config
    edge_count_config/set
     
Humidity Bricklet bricklet/humidity humidity
     
Industrial Analog Out Bricklet bricklet/industrial_analog_out voltage
    voltage/set
    current
    current/set
    configuration
    configuration/set
    enabled
    enable/set
    disable/set
     
Industrial Digital In 4 Bricklet bricklet/industrial_digital_in_4 value
    edge_count_config/set
    available_for_group
    group
    group/set
     
Industrial Digital Out 4 Bricklet bricklet/industrial_digital_out_4 value
    value/set
    selected_values/set
    monoflop/set
    available_for_group
    group
    group/set
     
Industrial Dual 0-20mA Bricklet bricklet/industrial_dual_0_20ma sample_rate
    sample_rate/set
     
Industrial Dual Analog In Bricklet bricklet/industrial_dual_analog_in sample_rate
    sample_rate/set
    calibration
    calibration/set
    adc_values
     
Industrial Quad Relay Bricklet bricklet/industrial_quad_relay value
    value/set
    selected_values/set
    monoflop/set
    available_for_group
    group
    group/set
     
IO-16 Bricklet bricklet/io16 port
    port/set
    port_configuration
    port_configuration/set
    port_monoflop/set
    selected_values/set
    edge_count_config/set
     
IO-4 Bricklet bricklet/io4 value
    value/set
    configuration/set
    monoflop/set
    selected_values/set
    edge_count_config/set
     
Joystick Bricklet bricklet/joystick position
    pressed
    calibrate/set
     
Laser Range Finder Bricklet bricklet/laser_range_finder distance
    velocity
    mode
    mode/set
    laser_enabled
    enable_laser/set
    disable_laser/set
    moving_average
    moving_average/set
     
LCD 16x2 Bricklet bricklet/lcd_16x2 write_line/set
    clear_display/set
    backlight_on
    backlight_on/set
    backlight_off/set
    config
    config/set
    custom_character
    custom_character/set
    button_pressed
     
LCD 20x4 Bricklet bricklet/lcd_20x4 write_line/set
    clear_display/set
    backlight_on
    backlight_on/set
    backlight_off/set
    config
    config/set
    custom_character
    custom_character/set
    button_pressed
    default_text
    default_text/set
    default_text_counter
    default_text_counter/set
     
LED Strip Bricklet bricklet/led_strip rgb_values
    rgb_values/set
    frame_duration
    frame_duration/set
    supply_voltage
    clock_frequency
    clock_frequency/set
    chip_type
    chip_type/set
     
Line Bricklet bricklet/line reflectivity
     
Linear Poti Bricklet bricklet/linear_poti position
     
Load Cell Bricklet bricklet/load_cell weight
    led_on
    led_on/set
    led_off/set
    moving_average
    moving_average/set
    configuration
    configuration/set
    tare/set
     
Moisture Bricklet bricklet/moisture moisture_value
    moving_average
    moving_average/set
     
Motion Detector Bricklet bricklet/motion_detector motion_detected
     
Multi Touch Bricklet bricklet/multi_touch touch_state
    electrode_config
    electrode_config/set
    electrode_sensitivity
    electrode_sensitivity/set
    recalibrate/set
     
OLED 128x64 Bricklet bricklet/oled_128x64 write/set
    new_window/set
    clear_display/set
    write_line/set
    display_configuration
    display_configuration/set
     
OLED 64x48 Bricklet bricklet/oled_64x48 write/set
    new_window/set
    clear_display/set
    write_line/set
    display_configuration
    display_configuration/set
     
Piezo Speaker Bricklet bricklet/piezo_speaker beep/set
    morse_code/set
     
PTC Bricklet bricklet/ptc temperature
    resistance
    sensor_connected
    wire_mode
    wire_mode/set
    noise_rejection_filter
    noise_rejection_filter/set
     
Real-Time Clock Bricklet bricklet/real_time_clock date_time
    date_time/set
    timestamp
    offset
    offset/set
     
Remote Switch Bricklet bricklet/remote_switch switching_state
    repeats
    repeats/set
    switch_socket_a/set
    switch_socket_b/set
    dim_socket_b/set
    switch_socket_c/set
     
RGB LED Bricklet bricklet/rgb_led rgb_value
    rgb_value/set
     
Rotary Poti Bricklet bricklet/rotary_poti position
     
Rotary Encoder Bricklet bricklet/rotary_encoder count (calls get_count with false)
    pressed
    _reset_count/set (calls get_count with true)
     
Solid State Relay Bricklet bricklet/solid_state_relay state
    state/set
    monoflop
    monoflop/set
     
     
Sound Intensity Bricklet bricklet/sound_intensity intensity
     
Temperature Bricklet bricklet/temperature temperature
    i2c_mode
    i2c_mode/set
     
Temperature IR Bricklet bricklet/temperature_ir ambient_temperature
    object_temperature
    emissivity
    emissivity/set
     
Tilt Bricklet bricklet/tilt tilt_state
     
UV Light Bricklet bricklet/uv_light uv_light
     
Voltage Bricklet bricklet/voltage voltage
     
Voltage/Current Bricklet bricklet/voltage_current voltage
    current
    power
    configuration
    configuration/set
    calibration
    calibration/set

Adding Support for other Bricks and Bricklets

The Brick MQTT Proxy is designed to be easily extendable for other Bricks and Bricklets. Take a look in the source of the script. To add other products you will have to implement your own proxy class derived from DeviceProxy class. Comments in the code describe the necessary structure.