MQTT data specification

MQTT data payloads may contain the following fields.

Object format

The MQTT object sent to the portal should be a JSON object, either in a single layer (i.e. not nested) or two-layer (nested). The following formats are valid.

Single layer JSON

The following format is acceptable:

{
    "timestamp": 1469626599000,
    "deviceId": "abc123",
    "switch": 1,
    "uses": 650
}

The white space and newlines are shown above for clarity but can be omitted.

Two-layer JSON

You can use an object called "data", like this:

{
    "timestamp": 1469626599000,
    "deviceId": "abc123",
    data {
        "switch": 1,
        "uses": 650
    }
}

Again, white space and newlines can be omitted.

Identification fields

Device ID

Incoming data must contain a device ID. This must be the same as that given in the MQTT topic, and must correspond with a valid Asset in the user's portal.

Example:

{
    "deviceId": "1761827db26ec8a"
}

Timestamp

Incoming data can optionally contain a timestamp in Unix microtime format (number of milliseconds since 1 January 1970 00:00:00UTC). If specified, denotes the time of the data reading (from a sensor, for example).

Example:

{
    "timestamp": 1469626599000
}

This allows data to be batched up, and several readings send in one batch. If not specified, the portal will assume the data relates to the time at which it was received. 

Generic data types

Boolean

Can be 0 or 1, true or false.

Example:

{
    "switch": 1
}

Integer

Can be any integer number.

Example:

{
    "uses": 650
}

It is possible for data to be sent from an asset as an integer and then a factor applied (e.g. x0.001 to divide by 1,000). The factor can be determined on the Asset Type and the specific field in question.

Floating-point

Can be any floating-point number.

Example:

{
    "temperature": 21.2
}

Location

Can be a latitude and longitude.

Example:

{
    "lat": 51.491151,
    "lon": -1.087291
}

It is not necessary to use the names "lat" and "lon" as in the example, but the fields must correspond to the field name codes in the Asset Type.

String

Can be a string of up to 256 characters in length.

Example: 

{
    "message": "Here is the message."
}

Data recording

When data is sent to the portal, generic field data is only stored if the field name exists in the Asset Type of the Asset whose ID is specified. If the field in the JSON object does not correspond, the data will not be saved.