MQTT protocol endpoint
The MQTT protocol endpoint is a device facing service offering connectivity using a simple MQTT v3.1.1 and v5 based protocol.
|
This is not an MQTT broker
It is important to understand, that the MQTT endpoint is not a general purpose MQTT broker. It is an MQTT based API, providing access to Drogue Cloud specific functionality, using the MQTT protocol and existing MQTT tools. |
Simple device vs gateway device
As MQTT is a long-lived connection, it makes sense to use it in gateway device use-cases. In this case, a device connects to the MQTT endpoint, and then also performs operations for other devices (connected via the gateway) device.
Drogue Cloud supports this model. Basically every device connecting via MQTT can act as a gateway device. The devices which allow other devices to act on their behalf, must indicate this by explicitly selecting a device as their gateway.
This is done using the device configuration on the device:
metadata:
name: sensor01 (1)
application: my-app
spec:
credentials: {} (2)
gatewaySelector:
matchNames: (3)
- gateway01| 1 | Name of the actual device. |
| 2 | Empty credentials, as this device doesn’t need to allow a direct connection. |
| 3 | Names of the devices (gateways) which are allowed to act on behalf of this device. |
A device can act both as direct device and as gateway a the same time.
Protocol dialects
The MQTT endpoint supports different "dialects" or APIs.The following subsections describe these dialects.By default, the "Drogue V1" dialect is use. However, you can configure the dialect of a device through the application or device configuration: see MQTT dialects.
Drogue V1 dialect
The Drogue V1 dialect is the original one, which supports all the features that Drogue Cloud offers using the MQTT endpoint.
Publish data
To publish data as the connected device, publish to <channel>. The channel information will be encoded in
the subject header of the generated event.
To publish data on behalf of another device, publish to <channel>/<device>.
| If the connected device is not listed as the specified device. The message will be dropped (QoS 0) or rejected (QoS 1). |
Payload & Content type
The payload of the publish message will be the "data" of the generated event.
For MQTT v5, it is possible to set the "content type" property, which will be used as the content type for the generated event.
By default (for MQTT 3.1.1, or when the content type is not provided), the content-type will be evaluated. If
the payload can be successfully parsed as JSON, the content type will be application/json. Otherwise it will
be application/octet-stream.
Subscribe to commands
In general, the command topic structure is command/inbox/<device>/<command>. It is however not possible to subscribe
to specific commands only.
| Topic pattern | Example topic | Description |
|---|---|---|
|
|
Subscribe to commands for the actual device |
|
|
Subscribe to commands for the device |
|
|
Subscribe to commands for actual device and all devices it acts as a gateway for. |
The payload of the command, will be the payload of the received message.
Plain topic dialect
The "plain topic" dialect doesn’t impose any restrictions on the topic naming that devices publish to. So it is ideal for connecting existing clients via MQTT, without the need to change the publish topic structure.
The downside is, that additional information (like sending on behalft of another device) which could go in the topic structure, now cannot be assigned a special meaning.
Publish data
The topic the client publishes to will directly be used as the channel information.
If the "device prefix" option is enabled, then the first segment of the topic will always be used a device ID. The connected device will only act as a gateway. The same access rules apply as for all gateways and devices.
Connecting over Websockets
Drogue Cloud allows connecting to MQTT over websocket too.This works the same was a standard MQTT, but be sure to check out some more details in the section MQTT over Websockets.