Expand Collapse
Just a second...

Using MQTT

MQTT 5.0 clients can publish and subscribe to Diffusion topics and support is enabled by default.

Connecting via MQTT

By default, you can connect to a Diffusion™ server from any MQTT 5.0 client, as if you were connecting to a standard MQTT broker.

For a TCP connection, you will need to provide:
  • Port: 8080 by default, or as configured in Connectors.xml
  • Username and password: use a Diffusion principal and password (or configure Diffusion to allow anonymous connections on the topic path you require)
For a WebSocket connection, you will also need to provide:
  • URL path: diffusion

Connect your MQTT client to the host name provided in your Cloud service dashboard (the same one that you would use to connect using an SDK client).

You will need to provide:
  • Port: 443
  • Username and password: use a Diffusion principal and password (or configure Diffusion to allow anonymous connections on the topic path you require)
  • URL path: diffusion

MQTT protocol support and limitations

Diffusion currently supports only MQTT 5.0. Earlier versions of the protocol (such as MQTT 3.1.1) are not supported.

MQTT clients can connect by either TCP or WebSocket.

Secure connections are supported. TLS support is the same as for SDK client connections, including TLS 1.3. See SSL and TLS support for details.

MQTT wildcard filters are supported.

All topics are ordered topics.

Quality of service (QoS) support:
  • Subscribing to topics with an MQTT client: QoS 0.
  • Publishing from an MQTT client to Diffusion: QoS 0 or 1.

We recommend you use QoS 1 when publishing from MQTT. This enables Diffusion to notify the MQTT client if an update fails, and is also used for flow control.

Diffusion feature support

MQTT clients can publish and subscribe to Diffusion topics.

Diffusion security authorization rules are applied to publication and subscription via MQTT.

MQTT sessions will trigger automatic topic removal and missing topic notifications like other sessions.

Diffusion clients written with the SDK can control MQTT sessions.

MQTT clients cannot use:
  • request-response messaging
  • topic control, session control and server administration features
  • recordV2 topics
  • advanced time series topic features (subscribing to a time series and appending an event are supported)
  • delta streaming
  • topic compression
  • reliable reconnection

These features are only supported by clients developed with a Diffusion SDK.

Session properties

MQTT sessions can be distinguished by their session properties:

  • $ClientType: MQTT
  • $Transport: TCP or WebSocket
  • $MQTTClientId (new session property): the client identifier provided by the client; if this is empty, the $SessionId is used as a client identifier

Translating between MQTT and Diffusion

MQTT 5.0 clients can both publish and subscribe to Diffusion topics.

Paths containing the MQTT wildcard filter characters (# and +) or starting with $ are not valid MQTT topic names. MQTT clients cannot subscribe to Diffusion topics with such paths.

Table 1. Subscribing (updates from Diffusion to MQTT client)
Diffusion topic type MQTT payload format PUBLISH content type Conversion If conversion fails
binary unspecified not set Publish value. -
string utf8 not set Convert payload to UTF-8. Replace malformed-input and unmappable character sequences with ?. -
double utf8 application/json Convert to decimal representation in ASCII, as per java.lang.Double.toString(double). Log warning and send as unspecified payload.
int64 utf8 application/json Convert to decimal representation in ASCII, as per java.lang.Long.toString(long). Log warning and send as unspecified payload.
json utf8 application/json Convert CBOR to JSON string. Log warning and send as unspecified payload.
recordv2 - - None - subscriptions will not resolve. -
time series unspecified or UTF-8 depends on event type Send event value according to the rules above. MQTT subscribers are not sent event metadata (author, timestamp). depends on conversion
Table 2. Publishing (updates from MQTT client to Diffusion)
Diffusion topic type Conversion If conversion fails
topic does not exist Create topic (see below) -
binary Update topic with payload. -
string Convert payload to UTF-8, then CBOR. Replace malformed-input and unmappable character sequences with ?. -
double Interpret as decimal representation in ASCII and convert using java.lang.Double.valueOf(String), then CBOR. Log warning and fail with 0x83 (implementation specific error).
int64 Interpret as decimal representation in ASCII and convert using java.lang.Long.valueOf(String), then CBOR. Log warning and fail with 0x83 (implementation specific error).
json Interpret as JSON string, then CBOR. Log warning and fail with 0x83 (implementation specific error).
recordv2 Log warning and fail with 0x83 (implementation specific error). -
time series Convert payload according to the rules above. Append to the time series using the current principal and timestamp. MQTT publishers cannot provide event metadata nor edit events. depends on conversion

Creating a Diffusion topic from MQTT

If an MQTT client publishes an update to a topic path which has no existing Diffusion topic, the topic is automatically created.

The Diffusion topic type created is determined as follows:

  • if the MQTT PUBLISH packet contains a content type property of application/json, a JSON topic is created (this fails if the payload can't be parsed as JSON).
  • otherwise, if the payload format property is UTF-8, a string topic is created
  • otherwise, a binary topic is created
Note: MQTT supports zero-length (empty) levels of a topic path but these cannot be published to Diffusion. For example, a/b//c (with an empty level between b and c) is a valid MQTT topic, but trying to use it to publish to Diffusion will fail.