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
    is_enabled
    pwm_frequency
    stack_input_voltage
    external_input_voltage
    current_consumption
    drive_mode
    is_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
    are_leds_on
    convergence_speed
    acceleration
    magnetic_field
    angular_velocity
    all_data
    imu_temperature
    acceleration_range
    magnetometer_range
    is_orientation_calculation_on
    is_status_led_enabled
    chip_temperature
    leds_on/set
    leds_off/set
    convergence_speed/set
    acceleration_range/set
    magnetometer_range/set
    calibration/set
    get_calibration/set (calls get_calibration with the parameters provided by the get_calibration/set topic and the output of the getter being published to the calibration topic)
    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
    are_leds_on
    acceleration
    magnetic_field
    angular_velocity
    temperature
    save_calibration
    sensor_configuration
    sensor_fusion_mode
    is_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
    is_rs485_present
    rs485_address
    rs485_error_log
    rs485_configuration
    is_wifi_present
    wifi_configuration
    wifi_encryption
    wifi_status
    wifi_power_mode
    wifi_buffer_info
    wifi_regulatory_domain
    usb_voltage
    long_wifi_key
    wifi_hostname
    is_ethernet_present
    ethernet_configuration
    ethernet_status
    ethernet_websocket_configuration
    ethernet_authentication_secret
    wifi_authentication_secret
    connection_type
    is_wifi2_present
    wifi2_authentication_secret
    wifi2_configuration
    wifi2_status
    wifi2_client_configuration
    wifi2_client_hostname
    wifi2_client_password
    wifi2_ap_configuration
    wifi2_ap_password
    wifi2_firmware_version
    is_wifi2_status_led_enabled
    wifi2_mesh_configuration
    wifi2_mesh_router_ssid
    wifi2_mesh_router_password
    wifi2_mesh_common_status
    wifi2_mesh_client_status
    wifi2_mesh_ap_status
    is_status_led_enabled
    chip_temperature
    extension_type/set
    get_extension_type/set (calls get_extension_type with the parameters provided by the get_extension_type/set topic and the output of the getter being published to the extension_type topic)
    rs485_address/set
    rs485_slave_address/set
    get_rs485_slave_address/set (calls get_rs485_slave_address with the parameters provided by the get_rs485_slave_address/set topic and the output of the getter being published to the rs485_slave_address topic)
    rs485_configuration/set
    wifi_configuration/set
    wifi_encryption/set
    refresh_wifi_status/set
    wifi_certificate/set
    get_wifi_certificate/set (calls get_wifi_certificate with the parameters provided by the get_wifi_certificate/set topic and the output of the getter being published to the wifi_certificate topic)
    wifi_power_mode/set
    wifi_regulatory_domain/set
    long_wifi_key/set
    wifi_hostname/set
    ethernet_configuration/set
    ethernet_hostname/set
    ethernet_mac_address/set
    ethernet_websocket_configuration/set
    ethernet_authentication_secret/set
    wifi_authentication_secret/set
    wifi2_authentication_secret/set
    wifi2_configuration/set
    wifi2_client_configuration/set
    wifi2_client_hostname/set
    wifi2_client_password/set
    wifi2_ap_configuration/set
    wifi2_ap_password/set
    save_wifi2_configuration/set (calls save_wifi2_configuration with the parameters provided by the save_wifi2_configuration/set topic and the output of the getter being published to the save_wifi2_configuration topic)
    enable_wifi2_status_led/set
    disable_wifi2_status_led/set
    wifi2_mesh_configuration/set
    wifi2_mesh_router_ssid/set
    wifi2_mesh_router_password/set
    enable_status_led/set
    disable_status_led/set
    reset/set
     
Servo Brick brick/servo output_voltage
    overall_current
    stack_input_voltage
    external_input_voltage
    is_status_led_enabled
    chip_temperature
    enable/set
    disable/set
    is_enabled/set (calls is_enabled with the parameters provided by the is_enabled/set topic and the output of the getter being published to the is_enabled topic)
    position/set
    get_position/set (calls get_position with the parameters provided by the get_position/set topic and the output of the getter being published to the position topic)
    get_current_position/set (calls get_current_position with the parameters provided by the get_current_position/set topic and the output of the getter being published to the current_position topic)
    velocity/set
    get_velocity/set (calls get_velocity with the parameters provided by the get_velocity/set topic and the output of the getter being published to the velocity topic)
    get_current_velocity/set (calls get_current_velocity with the parameters provided by the get_current_velocity/set topic and the output of the getter being published to the current_velocity topic)
    acceleration/set
    get_acceleration/set (calls get_acceleration with the parameters provided by the get_acceleration/set topic and the output of the getter being published to the acceleration topic)
    output_voltage/set
    pulse_width/set
    get_pulse_width/set (calls get_pulse_width with the parameters provided by the get_pulse_width/set topic and the output of the getter being published to the pulse_width topic)
    degree/set
    get_degree/set (calls get_degree with the parameters provided by the get_degree/set topic and the output of the getter being published to the degree topic)
    period/set
    get_period/set (calls get_period with the parameters provided by the get_period/set topic and the output of the getter being published to the period topic)
    get_servo_current/set (calls get_servo_current with the parameters provided by the get_servo_current/set topic and the output of the getter being published to the servo_current topic)
    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
    is_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
    is_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
Accelerometer Bricklet | bricklet/accelerometer | acceleration

Ambient Light Bricklet | bricklet/ambient_light | illuminance

Ambient Light Bricklet 2.0 | bricklet/ambient_light_v2 | illuminance
Analog In Bricklet | bricklet/analog_in | voltage
Analog In Bricklet 2.0 | bricklet/analog_in_v2 | voltage
Analog Out Bricklet | bricklet/analog_out | voltage
Analog Out Bricklet 2.0 | bricklet/analog_out_v2 | output_voltage
Barometer Bricklet | bricklet/barometer | air_pressure
CAN Bricklet | bricklet/can | read_frame
| 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)

CO2 Bricklet | bricklet/co2 | co2_concentration

Current12 Bricklet | bricklet/current12 | current
Current25 Bricklet | bricklet/current25 | current

Distance IR Bricklet | bricklet/distance_ir | distance

Distance US Bricklet | bricklet/distance_us | distance_value
DMX Bricklet | bricklet/dmx | dmx_mode
Dual Button Bricklet | bricklet/dual_button | button_state
Dual Relay Bricklet | bricklet/dual_relay | state
Dust Detector Bricklet | bricklet/dust_detector | dust_density
GPS Bricklet | bricklet/gps | status
GPS Bricklet 2.0 | bricklet/gps_v2 | coordinates
| satellite_system_status
| get_satellite_status/set (calls get_satellite_status with the parameters provided by the get_satellite_status/set topic and the output of the getter being published to the satellite_status topic)
Hall Effect Bricklet | bricklet/hall_effect | value

Humidity Bricklet | bricklet/humidity | humidity

Humidity Bricklet 2.0 | bricklet/humidity_v2 | humidity
Industrial Analog Out Bricklet | bricklet/industrial_analog_out | voltage
Industrial Digital In 4 Bricklet | bricklet/industrial_digital_in_4 | value
Industrial Digital Out 4 Bricklet | bricklet/industrial_digital_out_4 | value
Industrial Dual 0-20mA Bricklet | bricklet/industrial_dual_0_20ma | sample_rate
Industrial Dual Analog In Bricklet | bricklet/industrial_dual_analog_in | sample_rate
Industrial Quad Relay Bricklet | bricklet/industrial_quad_relay | value
IO-16 Bricklet | bricklet/io16 | port
IO-4 Bricklet | bricklet/io4 | value
Joystick Bricklet | bricklet/joystick | position
Laser Range Finder Bricklet | bricklet/laser_range_finder | distance
LCD 16x2 Bricklet | bricklet/lcd_16x2 | write_line/set
LCD 20x4 Bricklet | bricklet/lcd_20x4 | write_line/set
LED Strip Bricklet | bricklet/led_strip | rgb_values

Line Bricklet | bricklet/line | reflectivity

Linear Poti Bricklet | bricklet/linear_poti | position

Load Cell Bricklet | bricklet/load_cell | weight
Moisture Bricklet | bricklet/moisture | moisture_value

Motion Detector Bricklet | bricklet/motion_detector | motion_detected

Motorized Linear Poti Bricklet | bricklet/motorized_linear_poti | position
Multi Touch Bricklet | bricklet/multi_touch | touch_state
NFC RFID Bricklet | bricklet/nfc_rfid | tag_id
OLED 128x64 Bricklet | bricklet/oled_128x64 | write/set
OLED 64x48 Bricklet | bricklet/oled_64x48 | write/set
Piezo Buzzer Bricklet | bricklet/piezo_buzzer | beep/set
Piezo Speaker Bricklet | bricklet/piezo_speaker | beep/set
PTC Bricklet | bricklet/ptc | temperature
Real-Time Clock Bricklet | bricklet/real_time_clock | date_time
Remote Switch Bricklet | bricklet/remote_switch | 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 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)
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)
Solid State Relay Bricklet | bricklet/solid_state_relay | state

Sound Intensity Bricklet | bricklet/sound_intensity | intensity

Temperature Bricklet | bricklet/temperature | temperature
Temperature IR Bricklet | bricklet/temperature_ir | 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.