MQTT - IP Connection

This is the description of the MQTT API bindings for the IP Connection. The IP Connection manages the communication between the API bindings and the Brick Daemon or a WIFI/Ethernet Extension. Before Bricks and Bricklets can be controlled using their API an IP Connection has to be created and its TCP/IP connection has to be established.

An installation guide for the MQTT API bindings is part of their general description.

Examples

The example code below is Public Domain (CC0 1.0).

Enumerate

Download (example_enumerate.txt)

1
2
3
4
5
6
setup:
    # Handle incoming enumerate callbacks
    subscribe to tinkerforge/callback/ip_connection/enumerate
    publish '{"register": true}' to tinkerforge/register/ip_connection/enumerate # Register enumerate callback 
    
    publish '' to tinkerforge/request/ip_connection/enumerate # Trigger enumeration

Authenticate

Download (example_authenticate.txt)

1
2
3
4
5
6
7
8
# Start the MQTT-Bindings executable with the --ipcon-auth-secret "[YOUR SECRET HERE]" flag to use authentication.

setup:
    # Handle incoming enumerate callbacks
    subscribe to tinkerforge/callback/ip_connection/enumerate
    publish '{"register": true}' to tinkerforge/register/ip_connection/enumerate # Register enumerate callback

    publish '' to tinkerforge/request/ip_connection/enumerate # Trigger enumeration

API

Basic Functions

request/ip_connection/enumerate

Broadcasts an enumerate request. All devices will respond with an enumerate callback.

Callbacks

Callbacks can be registered to receive time critical or recurring data from the device. The registration is done with the corresponding .../register/... topic and an optional suffix. This suffix can be used to deregister the callback later.

Note

Using callbacks for recurring events is always preferred compared to using getters. It will use less USB bandwidth and the latency will be a lot better, since there is no round trip time.

register/ip_connection/enumerate
Request payload:
 
  • register -- bool
Response payload:
 
  • uid -- string
  • connected_uid -- string
  • position -- string
  • hardware_version -- [int,int,int]
  • firmware_version -- [int,int,int]
  • device_identifier -- int (has symbols)
  • enumeration_type -- int (has symbols)
  • _display_name -- string

A callback can be registered for this event by publishing to the .../register/ip_connection/enumerate[/SUFFIX] topic with the payload "true". An added callback can be removed by publishing to the same topic with the payload "false". To support multiple (de)registrations, e.g. for message filtering, an optional suffix can be used.

If the callback is triggered, a message with it's payload is published under the corresponding .../callback/ip_connection/enumerate[/SUFFIX] topic for each registered suffix.

The callback receives an JSON object with eight members:

  • uid: The UID of the device.
  • connected_uid: UID where the device is connected to. For a Bricklet this will be a UID of the Brick where it is connected to. For a Brick it will be the UID of the bottom Master Brick in the stack. For the bottom Master Brick in a stack this will be "0". With this information it is possible to reconstruct the complete network topology.
  • position: For Bricks: '0' - '8' (position in stack). For Bricklets: 'a' - 'd' (position on Brick).
  • hardware_version: Major, minor and release number for hardware version.
  • firmware_version: Major, minor and release number for firmware version.
  • device_identifier: A number that represents the device. If symbolic output is not disabled, the device identifier is mapped to the corresponding name in the format used in topics.
  • enumeration_type: Type of enumeration.
  • _display_name: The name of the device in a human readable form.

The following symbols are available for this function:

for device_identifier: see here.

for enumeration_type:

  • 0: "available": Device is available (enumeration triggered by user: enumerate). This enumeration type can occur multiple times for the same device.
  • 0: "available":: Device is newly connected (automatically send by Brick after establishing a communication connection). This indicates that the device has potentially lost its previous configuration and needs to be reconfigured.
  • 2: "disconnected": Device is disconnected (only possible for USB connection). In this case only uid and enumeration_type are valid.

It should be possible to implement plug-and-play functionality with this (as is done in Brick Viewer).

register/ip_connection/connected
Request payload:
 
  • register -- bool
Response payload:
 
  • connect_reason -- int (has symbols)

A callback can be registered for this event by publishing to the .../register/ip_connection/connected[/SUFFIX] topic with the payload "true". An added callback can be removed by publishing to the same topic with the payload "false". To support multiple (de)registrations, e.g. for message filtering, an optional suffix can be used.

If the callback is triggered, a message with it's payload is published under the corresponding .../callback/ip_connection/connected[/SUFFIX] topic for each registered suffix.

This event is triggered whenever the IP Connection got connected to a Brick Daemon or to a WIFI/Ethernet Extension.

The following symbols are available for this function:

for connect_reason:

  • 0: "request": Connection established after request from user.
  • 1: "auto-reconnect": Connection after auto-reconnect.
register/ip_connection/disconnected
Request payload:
 
  • register -- bool
Response payload:
 
  • disconnect_reason -- int (has symbols)

A callback can be registered for this event by publishing to the .../register/ip_connection/disconnected[/SUFFIX] topic with the payload "true". An added callback can be removed by publishing to the same topic with the payload "false". To support multiple (de)registrations, e.g. for message filtering, an optional suffix can be used.

If the callback is triggered, a message with it's payload is published under the corresponding .../callback/ip_connection/disconnected[/SUFFIX] topic for each registered suffix.

This event is triggered whenever the IP Connection got disconnected from a Brick Daemon or to a WIFI/Ethernet Extension.

The following symbols are available for this function:

for disconnect_reason:

  • 0: "request": Disconnect was requested by user.
  • 1: "error": Disconnect because of an unresolvable error.
  • 2: "shutdown": Disconnect initiated by Brick Daemon or WIFI/Ethernet Extension.