Authentication
Use username and password defined in the Servitly Thing Connector configuration.
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 data.
ENVIRONMENT |
URL |
PORT |
AWS SANDBOX |
mqtt.servitly-sandbox.com |
8883 |
AWS Ireland |
mqtt.servitly.com |
8883 |
AWS Hong Kong |
mqtt-ap.servitly.com |
8883 |
Azure 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 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 tenant. For security reasons, an MQTT client cannot publish or subscribe to a topic having a 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.
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" and 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 mapping name specified in the metrics. In this way, Servitly can extract the n-th property value and store it under the right product metric.
Data property values can be strings, numbers, or boolean encoded by using the standard JSON data encoding.
Data publish example
Considering the following configuration:
-
Product Mapping - Username: FooBar
-
Product Mapping - 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"}}
Comments
0 comments
Please sign in to leave a comment.