MQTT 3.1.1 protocol binding

You use the MQTT 3.1.1 binding to connect Ditto with MQTT brokers for lightweight, publish-subscribe messaging.

Overview

The MQTT 3.1.1 protocol binding lets you consume messages from MQTT 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 3.1.1 properties

MQTT 3.1.1 has no application headers. Set transmission-relevant properties in the "headers" field of the Ditto protocol message payload.

Supported property:

• correlation-id – correlates request messages and events

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 not contain {{ header:<name> }} placeholders (MQTT 3.1.1 has no application headers)
• qos (required) sets the maximum QoS to request: 0 (at-most-once), 1 (at-least-once), or 2 (exactly-once). Support of any QoS level depends on the external MQTT broker; AWS IoT for example does not acknowledge subscriptions with qos=2.

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

Source header mapping

Although MQTT 3.1.1 has no protocol headers, Ditto extracts these from each consumed message:

{
  "headerMapping": {
    "topic": "{{ header:mqtt.topic }}",
    "the-qos": "{{ header:mqtt.qos }}"
  }
}

Source acknowledgement handling

When you configure acknowledgement requests:

• Successful – Ditto acknowledges the MQTT message
• Failed with redelivery needed – depends on reconnectForRedelivery: either reconnects or withholds the ACK
• Failed without redelivery – Ditto acknowledges the message (redelivery does not help)

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

Generic header mapping is not available for MQTT 3.1.1 (no application headers). However, these special headers are applied directly to the published MQTT message:

Target acknowledgement handling

When you configure issued acknowledgement labels:

Specific configuration options

{
  "specificConfig": {
    "clientId": "my-mqtt-client-id",
    "reconnectForRedelivery": false,
    "cleanSession": false,
    "separatePublisherClient": false,
    "publisherId": "my-mqtt-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.

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 cleanSession flag. 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": "mqtt-example-connection-123",
  "connectionType": "mqtt",
  "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 connections. See TLS certificates for setup instructions.

{
  "id": "mqtt-example-connection-124",
  "connectionType": "mqtt",
  "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
• TLS certificates – secure connections with TLS