MQTT 5 protocol binding

You use the MQTT 5 binding to connect Ditto with MQTT 5 brokers, gaining access to user-defined properties and enhanced message metadata.

Overview

The MQTT 5 protocol binding lets you consume messages from MQTT 5 brokers via sources and publish messages via targets.

MQTT payloads should be UTF-8 encoded strings when sent in Ditto Protocol format. For other formats, configure a payload mapping.

MQTT 5 properties

Ditto interprets these MQTT 5 properties:

Connection URI format

tcp://hostname:1883

Use ssl:// for TLS-secured connections.

Source configuration

The common source configuration applies, with these specifics:

• addresses are MQTT topics to subscribe to (wildcards + and # allowed)
• authorizationContext may contain {{ header:<name> }} placeholders (via user-defined properties)
• qos (required) sets the maximum QoS: 0 (at-most-once), 1 (at-least-once), or 2 (exactly-once)

{
  "addresses": ["device/telemetry/#"],
  "authorizationContext": ["ditto:inbound-auth-subject"],
  "qos": 2
}

Source header mapping

MQTT 5 supports user-defined properties. Ditto also extracts these headers from each consumed message:

{
  "headerMapping": {
    "topic": "{{ header:mqtt.topic }}",
    "correlation-id": "{{ header:correlation-id }}",
    "device-id": "{{ header:device-id-user-defined-property }}"
  }
}

Source acknowledgement handling

When you configure acknowledgement requests:

• Successful – Ditto acknowledges the MQTT 5 message
• Failed with redelivery needed – depends on reconnectForRedelivery: either reconnects or withholds the ACK
• Failed without redelivery – Ditto acknowledges the message

To enable acknowledgement processing only for QoS 1/2 messages:

{
  "addresses": ["device/#"],
  "authorizationContext": ["ditto:inbound-auth-subject"],
  "qos": 1,
  "acknowledgementRequests": {
    "includes": [],
    "filter": "fn:filter(header:mqtt.qos,'ne','0')"
  }
}

Target configuration

The common target configuration applies. The target address is the MQTT topic to publish to. The qos field sets the publishing QoS level:

{
  "address": "mqtt/topic/of/my/device/{{ thing:id }}",
  "topics": [
    "_/_/things/twin/events",
    "_/_/things/live/messages"
  ],
  "authorizationContext": ["ditto:outbound-auth-subject"],
  "qos": 0
}

Target header mapping

MQTT 5 supports user-defined properties in the header mapping. These special headers are applied directly to the published message:

Target acknowledgement handling

When you configure issued acknowledgement labels:

Specific configuration options

{
  "specificConfig": {
    "clientId": "my-mqtt5-client-id",
    "reconnectForRedelivery": false,
    "cleanSession": false,
    "separatePublisherClient": false,
    "publisherId": "my-mqtt5-publisher-id",
    "reconnectForRedeliveryDelay": "5s",
    "keepAlive": "60s",
    "lastWillTopic": "my/last/will/topic",
    "lastWillQos": 1,
    "lastWillRetain": false,
    "lastWillMessage": "connection lost"
  }
}

clientId

Overwrites the default MQTT client ID. Default: the Ditto connection ID.

If the connection’s clientCount is 2 or more, the ID of each connectivity service instance is appended to the client ID to prevent clients from having the same ID. Otherwise the broker will disconnect the already-connected client every time another client with the same ID connects.

reconnectForRedelivery

When true, the MQTT connection reconnects whenever a consumed QoS 1 (“at least once”) or 2 (“exactly once”) message cannot be acknowledged successfully. The MQTT broker will then re-publish the message after reconnection. When false, the MQTT message is simply acknowledged (PUBACK or PUBREC, PUBREL). Default: false.

Handle with care:

• When true, incoming QoS 0 messages are lost during the reconnection phase
• When true and an MQTT target is also configured, outbound messages are lost during reconnection – to fix this, set separatePublisherClient to true to publish via a separate MQTT connection
• When false, MQTT messages with QoS 1 and 2 are redelivered based on the MQTT broker’s strategy, but may not be redelivered at all as the MQTT specification does not require unacknowledged messages to be redelivered without reconnection of the client

cleanSession

Sets the MQTT 5 cleanStart flag. (The flag is called cleanStart in MQTT 5 but the option is named cleanSession for consistency with MQTT 3.1.1.) Default: false.

separatePublisherClient

When true, Ditto opens two MQTT connections: one for subscribing and one for publishing. Default: false.

publisherId

MQTT client ID for the publisher when separatePublisherClient is enabled. Default: clientId + "p" (or connectionId + "p").

reconnectForRedeliveryDelay

Wait time before reconnecting for redelivery (minimum 1s). Default: 2s.

keepAlive

Ping interval to check if the connection is still up. Default: 60s.

Last Will configuration

Configure a Last Will message to notify other clients of an ungraceful disconnect:

Example connection JSON

{
  "id": "mqtt5-example-connection-12",
  "connectionType": "mqtt-5",
  "connectionStatus": "open",
  "failoverEnabled": true,
  "uri": "tcp://test.mosquitto.org:1883",
  "sources": [{
    "addresses": ["eclipse-ditto-sandbox/#"],
    "authorizationContext": ["ditto:inbound-auth-subject"],
    "qos": 0
  }],
  "targets": [{
    "address": "eclipse-ditto-sandbox/{{ thing:id }}",
    "topics": ["_/_/things/twin/events"],
    "authorizationContext": ["ditto:outbound-auth-subject"],
    "qos": 0
  }]
}

Client-certificate authentication

Ditto supports certificate-based authentication for MQTT 5 connections. See TLS certificates for setup instructions.

{
  "id": "mqtt5-example-connection-124",
  "connectionType": "mqtt-5",
  "connectionStatus": "open",
  "failoverEnabled": true,
  "uri": "ssl://test.mosquitto.org:8884",
  "validateCertificates": true,
  "ca": "-----BEGIN CERTIFICATE-----\n<broker certificate>\n-----END CERTIFICATE-----",
  "credentials": {
    "type": "client-cert",
    "cert": "-----BEGIN CERTIFICATE-----\n<client certificate>\n-----END CERTIFICATE-----",
    "key": "-----BEGIN PRIVATE KEY-----\n<client private key>\n-----END PRIVATE KEY-----"
  },
  "sources": [{
    "addresses": ["eclipse-ditto-sandbox/#"],
    "authorizationContext": ["ditto:inbound-auth-subject"],
    "qos": 0
  }],
  "targets": [{
    "address": "eclipse-ditto-sandbox/{{ thing:id }}",
    "topics": ["_/_/things/twin/events"],
    "authorizationContext": ["ditto:outbound-auth-subject"],
    "qos": 0
  }]
}

Further reading

• Connections overview – connection model and configuration
• Payload mapping – transform message payloads
• Header mapping – map external headers
• TLS certificates – secure connections with TLS