MQTT - IP Connection¶

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

Basic Functions¶

request/ip_connection/enumerate¶

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

request/ip_connection/get_connection_state¶

Response payload:	connection_state -- int (has symbols)

Can return the following states:

• "disconnected" = 0: No connection is established.
• "connected" = 1: A connection to the Brick Daemon or the WIFI/Ethernet Extension is established.
• "pending" = 2: IP Connection is currently trying to connect.

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.

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 its 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 is the UID of the Brick or Bricklet it is connected to. For a Brick it is the UID of the bottommost Brick in the stack. For the bottommost Brick in a stack it is "0". With this information it is possible to reconstruct the complete network topology.
• position: For Bricks: '0' - '8' (position in stack). For Bricklets: 'a' - 'h' (position on Brick) or 'i' (position of the Raspberry Pi (Zero) HAT) or 'z' (Bricklet on Isolator Bricklet).
• 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:

• "available" = 0: Device is available (enumeration triggered by user: enumerate). This enumeration type can occur multiple times for the same device.
• "connected" = 1: 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.
• "disconnected" = 2: 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 its 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:

• "request" = 0: Connection established after request from user.
• "auto-reconnect" = 1: 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 its 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:

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