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™ Cloud server from any MQTT 5.0 client, as if you were connecting to a standard MQTT broker.
Diffusion Cloud accepts WebSocket connections only.
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).
- Port: 443
- Username and password: use a Diffusion Cloud principal and password (or configure Diffusion Cloud to allow anonymous connections on the topic path you require)
- URL path: diffusion
MQTT protocol support and limitations
Diffusion Cloud currently supports only MQTT 5.0. Earlier versions of the protocol (such as MQTT 3.1.1) are not supported.
MQTT wildcard filters are supported.
All topics are ordered topics.
- Subscribing to topics with an MQTT client: QoS 0.
- Publishing from an MQTT client to Diffusion Cloud: 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 Cloud 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.
- 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 Cloud SDK.
Session properties
MQTT sessions can be distinguished by their session properties:
- $ClientType: MQTT
- $Transport: 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 Cloud
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.
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 |
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