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:
  authentication: {} (2)
  gatewaySelector:
    matchNames: (3)
      - gateway01
1 Name of the actual device.
2 Empty authentication, 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.

Connecting

  • Clean session must be true

Authenticating

X.509 Client certificates

You may use X.509 client certificates when establishing the TLS connection. The certificate must be signed with a trust anchor stored in the device registry on the application level.

TLS-PSK

You may use pre-shared keys when establishing the TLS connection. See Setting TLS-PSK credentials for how to configure the device.

Username/password

Use <device>@<application> and a configured password for the device.

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

  • command/inbox//#

  • command/inbox//set-temp

Subscribe to commands for the actual device

  • command/inbox/my-device/#

  • command/inbox/my-device/set-temp

Subscribe to commands for the device my-device.

  • command/inbox/#

  • command/inbox/+/#

  • command/inbox/my-device/set-temp

  • command/inbox//set-temp

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.