Publish data through MQTT

In this article you will find how to publish data to Servitly by using the Servitly Thing Connector (STC) based on the MQTT protocol.

Authentication

The channel authentication is based on username and password credentials, that can be configured within the DPS, refer to the Direct MQTT Connector article for more details about the STC Configuration.

In the alternative, if you need cloud-to-cloud connection, you can configure a global MQTT connection, for more details you can refer to the Main IoT Connector article.

MQTT Endpoints

Depending on the Servitly instance in which the DPS is configured, your MQTT client must connect to the right endpoint to start publishing/subscribing data.

AWS

AZURE

SSL certificate

The MQTT connection is secured by an SSL certificate, which is subject to expiration and renewal.

For more information about how to deal with certificates, refer to the SSL Certificates article.

Topic structure

The MQTT protocol is a publish/subscribe protocol based on topics, so when you publish a message you need to use a specific topic in order to let Servitly recognize which is the correct target product (Thing) of the message.

MQTT topics must be structured in the following way, according to how the Servitly Thing Connector and the product have been configured within Servitly.

<USERNAME>/<THING_MAPPING_ASSET_ID>/<METRIC_PATH>

Where the various parts are:

• USERNAME: the username configured within the Connection Mapping tab of the product, or inherited by the parent location, customer o environment (Main IoT Connector). For security reasons, an MQTT client cannot publish or subscribe to a topic having the username part different from the username used to establish the MQTT connection.

• THING_MAPPING_ASSET_ID: this is the Asset Id configured within the Connection Mapping tab of the product.

• METRIC_PATH: this is the path configured within the metric mapping panel.

Optionally the Connection Mapping of a product allows defining a path that can be used if your firmware requires an extra level into the topic, for instance, a gateway is used for connecting multiple products.

Here is an example of a topic structure with this extra level:

<USERNAME>/<THING_MAPPING_ASSET_ID>/<THING_MAPPING_PATH>/<METRIC_PATH>

Payload format

The Servitly IoT Connector uses a predefined message payload format, which is a JSON document (UTF-8 encoded) and with the following structure:

{
 "ts": 1605179226000,
 "data": {
   "temperature": 23.5,
   "humidity": 45,
   "status": "OK",
   "active": true
 }
}

The JSON document must include the following predefined properties:

• ts: the timestamp in milliseconds relative to the data included in the data node, if missing, the server will consider the message reception time. The timestamp is expressed as the difference, measured in milliseconds, between the time of the data and midnight, January 1, 1970 UTC.

• data: the JSON node element containing all the metrics sent from the product.
  In the alternative, you can also use a simple "d" as node name. This saves your network traffic (3 bytes for every message).

Into the data node, you can use any string key you prefer, but it is important that these keys will match the name specified in the metric mapping panel.
In this way, Servitly can extract the n-th field value and store it under the right metric.

Data field values can be strings, numbers, or boolean encoded by using the standard JSON data encoding.
For more details about how to encode values into the JSON payload refer to the Encoding Values article.

Data publishing example

Considering the following configuration:

• Product Mapping

  • Username: FooBar

  • Asset Id: MC0001

• Metric Mapping

  • Path: measures

Product metrics:

To publish measures, the product should open an MQTT connection to the right MQTT endpoint (see the Product Connection Mapping tab).

URL: ssl://mqtt.servitly.com:8883
Username: FooBar
Password: ********

And publish the following message, serializing the JSON using a "UTF-8" encoding.

TOPIC: FooBar/MC0001/measures
MESSAGE: {"ts": 1605179226000, "data":{"temp": 22.5, "gps": "40.567,34.555"}}