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
DC Brick brick/dc velocity
    current_velocity
    acceleration
    enabled
    pwm_frequency
    stack_input_voltage
    external_input_voltage
    current_consumption
    drive_mode
    status_led_enabled
    chip_temperature
    velocity/set
    acceleration/set
    full_brake/set
    enable/set
    disable/set
    pwm_frequency/set
    drive_mode/set
    enable_status_led/set
    disable_status_led/set
    reset/set
     
IMU Brick brick/imu orientation
    quaternion
    leds_on
    convergence_speed
    acceleration
    magnetic_field
    angular_velocity
    all_data
    imu_temperature
    acceleration_range
    magnetometer_range
    get_calibration/set
    orientation_calculation_on
    status_led_enabled
    chip_temperature
    leds_on/set
    leds_off/set
    convergence_speed/set
    acceleration_range/set
    magnetometer_range/set
    calibration/set
    orientation_calculation_on/set
    orientation_calculation_off/set
    enable_status_led/set
    disable_status_led/set
     
IMUV2 Brick brick/imu_v2 orientation
    linear_acceleration
    gravity_vector
    quaternion
    all_data
    leds_on
    acceleration
    magnetic_field
    angular_velocity
    temperature
    sensor_configuration
    sensor_fusion_mode
    status_led_enabled
    chip_temperature
    leds_on/set
    leds_off/set
    sensor_configuration/set
    sensor_fusion_mode/set
    enable_status_led/set
    disable_status_led/set
    reset/set
     
Master Brick brick/master stack_voltage
    stack_current
    usb_voltage
    connection_type
    status_led_enabled
    chip_temperature
    enable_status_led/set
    disable_status_led/set
    reset/set
     
Servo Brick brick/servo enabled
    position
    current_position
    velocity
    current_velocity
    acceleration
    output_voltage
    pulse_width
    degree
    period
    servo_current
    overall_current
    stack_input_voltage
    external_input_voltage
    status_led_enabled
    chip_temperature
    enable/set
    disable/set
    position/set
    velocity/set
    acceleration/set
    output_voltage/set
    pulse_width/set
    degree/set
    period/set
    enable_status_led/set
    disable_status_led/set
    reset/set
     
Silent Stepper Brick brick/silent_stepper max_velocity
    current_velocity
    speed_ramping
    steps
    remaining_steps
    motor_current
    enabled
    basic_configuration
    current_position
    target_position
    step_configuration
    stack_input_voltage
    external_input_voltage
    spreadcycle_configuration
    stealth_configuration
    coolstep_configuration
    misc_configuration
    driver_status
    time_base
    all_data
    status_led_enabled
    chip_temperature
    max_velocity/set
    speed_ramping/set
    full_brake/set
    steps/set
    drive_forward/set
    drive_backward/set
    stop/set
    motor_current/set
    enable/set
    disable/set
    basic_configuration/set
    current_position/set
    target_position/set
    step_configuration/set
    spreadcycle_configuration/set
    stealth_configuration/set
    coolstep_configuration/set
    misc_configuration/set
    time_base/set
    enable_status_led/set
    disable_status_led/set
    reset/set
     
Stepper Brick brick/stepper max_velocity
    current_velocity
    speed_ramping
    steps
    remaining_steps
    motor_current
    enabled
    current_position
    target_position
    step_mode
    stack_input_voltage
    external_input_voltage
    current_consumption
    decay
    sync_rect
    time_base
    all_data
    status_led_enabled
    chip_temperature
    max_velocity/set
    speed_ramping/set
    full_brake/set
    steps/set
    drive_forward/set
    drive_backward/set
    stop/set
    motor_current/set
    enable/set
    disable/set
    current_position/set
    target_position/set
    step_mode/set
    decay/set
    sync_rect/set
    time_base/set
    enable_status_led/set
    disable_status_led/set
    reset/set
     
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 In Bricklet 3.0 bricklet/analog_in_v3 voltage
     
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
     
CAN Bricklet bricklet/can read_frame
    configuration
    read_filter
    error_log
    write_frame/set (calls write_frame with the parameters provided by the write_frame/set topic and the output of the getter being published to the write_frame topic)
    configuration/set
    read_filter/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
     
DMX Bricklet bricklet/dmx dmx_mode
    read_frame
    frame_duration
    frame_error_count
    communication_led_config
    error_led_config
    status_led_config
    chip_temperature
    dmx_mode/set
    write_frame/set
    frame_duration/set
    communication_led_config/set
    error_led_config/set
    status_led_config/set
    reset/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
     
GPS Bricklet 2.0 bricklet/gps_v2 coordinates
    status
    altitude
    motion
    date_time
    satellite_system_status
    satellite_status
    fix_led_config
    sbas_config
    status_led_config
    chip_temperature
    restart/set
    fix_led_config/set
    sbas_config/set
    status_led_config/set
    reset/set
     
Hall Effect Bricklet bricklet/hall_effect value
    edge_count_config
    edge_count_config/set
     
Humidity Bricklet bricklet/humidity humidity
     
Humidity Bricklet 2.0 bricklet/humidity_v2 humidity
    temperature
    heater_config
    moving_average_configuration
    status_led_config
    chip_temperature
    heater_configuration/set
    moving_average_configuration/set
    status_led_config/set
    reset/set
     
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
     
Motion Detector Bricklet 2.0 bricklet/motion_detector_v2 motion_detected
     
Motorized Linear Poti Bricklet bricklet/motorized_linear_poti position
    motor_position
    status_led_config
    chip_temperature
    motor_position/set
    calibrate/set
    status_led_config/set
    reset/set
     
Multi Touch Bricklet bricklet/multi_touch touch_state
    electrode_config
    electrode_config/set
    electrode_sensitivity
    electrode_sensitivity/set
    recalibrate/set
     
NFC RFID Bricklet bricklet/nfc_rfid tag_id
    state
    page
    request_tag_id/set
    authenticate_mifare_classic_page/set
    write_page/set
    request_page/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 Buzzer Bricklet bricklet/piezo_buzzer beep/set
    morse_code/set
     
Piezo Speaker Bricklet bricklet/piezo_speaker beep/set
    morse_code/set
     
Outdoor Weather Bricklet bricklet/outdoor_weather station_data
    sensor_data
     
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
Remote Switch Bricklet 2.0 | bricklet/remote_switch_v2 | switching_state
RGB LED Bricklet | bricklet/rgb_led | rgb_value
RGB LED Button Bricklet | bricklet/rgb_led_button | color
RGB LED Matrix Bricklet | bricklet/rgb_led_matrix | red
Rotary Encoder Bricklet | bricklet/rotary_encoder | count (calls get_count with false)
| get_count/set (calls get_count with the parameters provided by the get_count/set topic and the output of the getter being published to the count topic)
Rotary Encoder Bricklet 2.0 | bricklet/rotary_encoder_v2 | count (calls get_count with false)
| get_count/set (calls get_count with the parameters provided by the get_count/set topic and the output of the getter being published to the count topic)

Rotary Poti Bricklet | bricklet/rotary_poti | position

RS232 Bricklet | bricklet/rs232 | read
| write/set (calls write with the parameters provided by the write/set topic and the output of the getter being published to the write topic)
RS485 Bricklet | bricklet/rs485 | rs485_configuration
| write/set (calls write with the parameters provided by the write/set topic and the output of the getter being published to the write topic)
| read/set (calls read with the parameters provided by the read/set topic and the output of the getter being published to the read topic)
Solid State Relay Bricklet | bricklet/solid_state_relay | state
Solid State Relay Bricklet 2.0 | bricklet/solid_state_relay_v2 | state

Sound Intensity Bricklet | bricklet/sound_intensity | intensity

Temperature Bricklet | bricklet/temperature | temperature
Temperature IR Bricklet | bricklet/temperature_ir | ambient_temperature
Temperature IR Bricklet 2.0 | bricklet/temperature_ir_v2 | ambient_temperature
Thermal Imaging Bricklet | bricklet/thermal_imaging | high_contrast_image
Thermocouple Bricklet | bricklet/thermocouple | temperature

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

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.