MQTT Topics

The structure of MQTT topics is as follows:

[<GLOBAL_PREFIX>/]<OPERATION>/<DEVICE>[/<UID>]/<FUNCTION>[/<SUFFIX>]

Overview of MQTT Topic Elements

Global Prefix

[<GLOBAL_PREFIX>/] is the global prefix for all topics (default setting: tinkerforge/).

• It can be modified using the --global-topic-prefix command line argument.
• The prefix is utilised to differentiate between multiple instances of the MQTT bindings.
• Furthermore, it may contain multiple topic levels, for example tinkerforge/iotnodes/sensors.
• If the configured prefix does not end with a /, the bindings will append one, unless an empty prefix is configured, in which case all topics will begin with the operation. This approach, however, is not recommended due to potential naming conflicts.

Operation

<OPERATION> represents the type of request. This may be request, response, register, or callback. The bindings subscribe to request and register topics, and publish responses under response topics for requests and callback topics for registers.

Device

<DEVICE> is the type of device with which the interaction is intended. This may be the name of a Brick or Bricklet in snake_case, or ip_connection. Refer to the documentation for the precise naming conventions of the devices.

UID

[/<UID>] represents the UID of the device. If the device is ip_connection, the UID must be empty and should not include a /, for example, .../ip_connection/enumerate.

Function

<FUNCTION> is the function to be called, or the callback to be registered (in snake_case).

Suffix

</[SUFFIX]> is the optional suffix appended to responses. This can be used to filter messages. See the documentation for further details.

Requests

Given are two example requests using MQTT and tinkerforge_mqtt:

Typical Request

A typical request topic would look like this: tinkerforge/request/rgb_led_button_bricklet/Dod/get_color.

The response to this request will be returned by the bindings at tinkerforge/response/rgb_led_button_bricklet/Dod/get_color.

Callback Registration

A callback registration topic would appear as follows: tinkerforge/register/rgb_led_button_bricklet/Dod/button_state_changed.

By subscribing to tinkerforge/callback/rgb_led_button_bricklet/Dod/button_state_changed, a message will be received each time the button is pressed or released.