MQTT broker

We provide a MQTT broker which you can connect to for live data from your collection. To connect be able to connect you need the ID of the collection you want to stream live data from, and an API token with access to the collection. You can create an API token in the Span dashboard.

Connecting to the MQTT broker

The URL to use for the MQTT broker is tls://mqtt.lab5e.com:8883

To correctly connect you ,use the collectionId as the MQTT user, and use an API Token as the password. You should then connect and receive an automatic stream of data messages on the MQTT client.

{
  "device": {
    "deviceId": "<deviceId>",
    "collectionId": "<collectionId>",
    "imei": "111222333444",
    "imsi": "123456789",
    "tags": { "name": "My first device" }
  },
  "payload": "WXVwIHRoaXMgaXMgdGhlIHBheWxvYWQ=",
  "received": 1538163685141,
  "type": "data",
  "transport": "<transport used by the device to deliver the data>",
  "coapMetaData": {
    "method": "POST",
    "path": "<path used by device>"
  },
  "udpMetaData": {
    "localPort": "<the backend's local port>",
    "remotePort": "<the port used on the device>"
  }
}

Topic and payload templates

Templates are simple text strings where you add fields that should be expanded in double curly braces ({{ “{{ and }} " }}). The names of the fields follows the syntax and naming of the corresponding fields in the output data message.

By default the MQTT broker templates are {{ collection.collectionId }}/{{ device.deviceId }} for the topic and {{ message | json }} for the payload, ie for the collection 566ecm37cdcah5 and device 546ecm37cmcahh the payload will be published to the topic 566ecm37cdcah5/546ecm37cmcahh with a payload identical to the websocket output. You can customize the payload to either be a vanilla binary payload that will be just the payload from the device (and you’ll have to subscribe to a wildcard like /# to get all the different topics and use those to deduce which device sent the message).

Filtering on device metadata

It is possible to publish to topics based on the device metadata, ie if you create a template that looks like {{ collection.collectionId }}/{{device.tags["name"]}} the topics will be named after the tag name on each device. If you add a tag to mark the type of payload (f.e. version=v1 for one set of devices and version=v2 for another set of devices) you can use the tags to filter topics. If you set the topic to data/{{device.tags["version"]}} all devices marked v1 will publish their payloads to the topic data/v1 while devices marked with v2 will publish to the topic data/v1. If you ever change the payload format to a new version that isn’t backwards compatible you can set the tag version=v3 and clients that consume the data/v1 and data/v2 won’t have to handle the new payload format.

If you use the FOTA feature and the devices report firmware versions you can even publish based on the reported device version; for data/{{device.firmware.firmwareVersion }} you’ll get payloads split into separate topics based on the reported version of the firmware (like data/1.0.0, data/1.0.1 and so on). The usual wildcards for MQTT can be used so you can subscribe to all 1.0.0 payloads by subscribing to data/1.? or even data/1.0.?

Payload templates

Payloads can also be customized to your needs. If one of the upstream systems are quite particular on the format you can construct JSON structures via the payload template. A template like this:

{
    "name": "{{ collection.tags["name"] }}",
    "deviceId": "{{ device.deviceId }}",
    "firmwareVersion": "{{ device.firmware.firmwareVersion }}",
    "data": {
        "format": "{{ device.tags["format"] }}",
        "payload": "{{ message.payload }}",
        "received": "{{ message.received | asTime }}",
        "source": "{{ device.network.allocatedIp }}",
    }
}

…Would give you payloads that look like this:

{
    "name": "My collection name",
    "deviceId": "(device id))",
    "firmwareVersion": "1.0.1",
    "data": {
        "format": "v1",
        "payload": "(base 64 encoded payload)",
        "received": "2020-01-01T12:32:00.001Z",
        "source": "10.1.2.3"
    }
}