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

Environment Type	Region	URL	Port
Sandbox	Europe (Ireland)	mqtt.servitly-sandbox.com	8883
Production	Europe (Ireland)	mqtt.servitly.com	8883
Production	Asia/Pacific (Hong Kong)	mqtt-ap.servitly.com	8883

AZURE

Environment Type	Region	Certificate URL	Port
Develop	Europe (Frankfurt)	azmqtt.servitly-dev.com	8883
Staging	Europe (Frankfurt)	azmqtt.servitly-staging.com	8883
Production	Europe (Frankfurt)	azmqtt.servitly.com	8883

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 MQTT Connector uses the Standard Payload Format for exchanged messages.

Data publishing example

Considering the following configuration:

Product Mapping
- Username: FooBar
- Asset Id: MC0001
Metric Mapping
- Path: measures

Product metrics:

NAME	TYPE	MAPPING PATH	MAPPING NAME
Temp	FLOAT	measures	temp
GPS	STRING	measures	gps

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"}}

Documentation Index