Data collection via MQTT

After connecting and authenticating your MQTT client to the MQTT broker, your client can send MQTT messages with data.

Topic

The MQTT topic is the following.

tenant/trial/ts/in/${device_identifier}

The {device_identifier} can either be the string representation of the device UUID, or the external ID of the device. If your devices or gateways cannot be configured in such a way that they would actually know their device UUID in graphicx.io, please use the external ID of your choice, which is an optional attribute of the device in graphicx.io. Make sure your external ID is designed in such a way that it is compatible with MQTT topic naming conventions.

Message Payload

For the MQTT message payload you can either, to start quickly, use the default JSON format without compression, or you can announce and use one of the advanced formats and optionally a compression.

Default Payload Format for starting quickly

To start quickly, simply create a JSON document of the following structure and include it as payload in the MQTT message, encoded using UTF-8.

{
  "data": {
    "1": [
      {
        "time": 1605813332501,
        "value": 1.11
      },
      {
        "time": 1605813333501,
        "value": 1.12
      }
    ],
    "2": [
      {
        "time": 1605813332501,
        "value": 1.21
      },
      {
        "time": 1605813333501,
        "value": 1.22
      }
    ],
    "3": [],
    "4": [
      {
        "time": 1605813332501,
        "value": 1.4
      }
    ]
  }
}

This JSON data format can be used to send time series to the Cloud.

  • The integer keys are the channel indices, each pointing to an array of one or more values.
  • The field time represents the point in time of a value on a time series. It requires a non-decimal JSON Number simply representing EpochMillis (not to be confused with EpochSeconds or other variants).
  • The field value represents the amplitude of a value on a time series. It requires a JSON Number, which must however at the same time adhere to the further restrictions of the Java float, since this number is interpreted by the Cloud as a Java float. The JSON Number may be positive, zero or negative. It must not be lesser or greater than the minimum or maximum float value supported by Java, respectively.
  • You may freely omit channels if there are currently no values to be sent for these. Alternatively, the arrays of values for these channels may be empty, as shown in the example for channel 3.

IoT Device Example for connecting to graphicx.io via MQTT

As mentioned also in the Introduction to this quickstart, an IoT Device Example based on a Raspberry Pi and python is available on GitHub. If you are new to graphicx.io we recommend to first read this quickstart here and to then head over to GitHub to study that simple example. By the way, the example uses the default payload format that we just described in the previous section.

Advanced Payload Formats and Compression

The above described payload format for starting quickly is auto-detected on the server-side. To use one of the advanced formats and optionally compression, the following contract applies.

Since MQTT 3.1.1 does not support headers, in order to identify the payload format and the optional compression algorithm, we interpret the first two bytes of the MQTT message payload in a custom way.

The first byte in the MQTT message payload announces the payload format. It has to be the format_byte_id of the format. The available payload formats are documented in all detail, including each format_byte_id, in the articles protobuf payload formats and JSON payload formats.

The second byte in the MQTT message payload announces the compression algorithm. Compression is optional, but this byte has to be present in every case. If you chose not to apply any compression, please use the compression_byte_id that stands for no compression. The available compression algorithms, including each compression_byte_id, are documented in the following table.

Compression Algorithmcompression_byte_id
no compression0x02 (Binary 00000010)
lzma0x03 (Binary 00000011)
lz40x04 (Binary 00000100)
snappy0x05 (Binary 00000101)
bzip20x06 (Binary 00000110)
gzip0x07 (Binary 00000111)
zip0x08 (Binary 00001000)

Finally, the formatted, serialized, and optionally compressed, payload data follows from the third byte onwards.

Next Step: Payload formats based on Google Protocol Buffers 3

Alternative: Payload formats based on JSON


Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.