This tutorial will show you step-by-step how to test the connection of your devices to Servitly using the MQTT standard protocol.

To publish data through the MQTT protocol you can download the Eclipse PAHO library, which is available in several programming languages, check out the download page for more details.

Account creation

Create a new account on https://lab.servitly-sandbox.com/ (when asked, choose "Personal" as Account Type) and login

Select the "My Home" location
Press the (+) button to create a new device:

Name: as desired, it’s the mnemonic name of the equipment.
Serial Number: as desired, it’s the equipment’s unique serial number.
Thing Definition: select Generic-Device, it’s the default equipment definition for testing that includes a predefined set of metrics, commands, configuration-parameters, and alerts definitions.
GPS Position: optional, by default it’s inherited from the location if specified.

MQTT Connector Configuration

Once saved, go to the equipment Connection tab to configure how the Equipment will connect to the cloud. Provide the following information:

Type: Servitly Thing Connector
MQTT Broker URL: mqtt.servitly-sandbox.com:8883
Username: as desired by you, it is the unique username identifying the MQTT connection. It’s the root part of the MQTT topics <USERNAME>/<ASSET_ID>/<METRIC_PATH>
Password: at least 8 characters long with at least one lower case letter, one upper case letter, and one number.
Payload Format: JSON
Asset Id: the equipment identifier, it will be used as the MQTT sub-topic (usually it is equivalent to the Serial Number or the MAC address of the gateway)
Path: the optional path which can be used to manage multiple devices mapped under the same gateway.

Now you are ready to open an MQTT connection and start sending data to Servitly.

MQTT Client

In order to publish data through the MQTT channel, the following information is needed:

MQTT Broker URL: the MQTT broker connection URL.
Username: the username used to open the MQTT connection.
Password: the username password authenticating the MQTT connection.
Asset Id: the device identifier used within the publishing topic.
Metric Path: the path mapping the metrics you want to publish.

For more details about how to configure the connection properties, enter the device dashboard page and click on the Edit button (top right), and then enter the Connection tab.

Please note that the publishing topic must have this structure <USERNAME>/<ASSET-ID>/<METRIC_PATH>, for this test you can use measures as the metric path.

The code below is a very basic sample that connects to the Servitly MQTT broker and publishes a message by using the PAHO MqttClient synchronous API. Remember to replace the variables (<***>) with your connection properties.

package com.servitly.testMQTT;

import org.eclipse.paho.client.mqttv3.MqttClient;
import org.eclipse.paho.client.mqttv3.MqttConnectOptions;
import org.eclipse.paho.client.mqttv3.MqttException;
import org.eclipse.paho.client.mqttv3.MqttMessage;
import org.eclipse.paho.client.mqttv3.persist.MemoryPersistence;
import org.apache.commons.lang.math.RandomUtils;
import com.fasterxml.jackson.databind.node.JsonNodeFactory;
import com.fasterxml.jackson.databind.node.ObjectNode;

public class TestMQTT {

    public static void main(String[] args) {
        int qos = 2;
        String broker = "ssl://mqtt.servitly-sandbox.com:8883";
        String clientId = "SN12345689_CLIENT";
        String username = "<USERNAME>";
        String password = "<PASSWORD>";
        String topic = "<USERNAME>/<ASSET_ID>/measures";
        MemoryPersistence persistence = new MemoryPersistence();
        try {
            ObjectNode payload = JsonNodeFactory.instance.objectNode();
            payload.put("ts", System.currentTimeMillis());
            ObjectNode data = JsonNodeFactory.instance.objectNode();
            data.put("measure1", 42 + RandomUtils.nextInt(10));
            data.put("measure2", 24 + RandomUtils.nextInt(10));
            payload.set("data", data);
            MqttClient sampleClient = new MqttClient(broker, clientId, persistence);
            MqttConnectOptions connOpts = new MqttConnectOptions();
            connOpts.setCleanSession(true);
            connOpts.setUserName(username);
            connOpts.setPassword(password.toCharArray());

            System.out.println("Connecting to broker: " + broker);
            sampleClient.connect(connOpts);
            System.out.println("Connected");
            System.out.println("Publishing message: " + payload.toString());

            MqttMessage message = new MqttMessage(payload.toString().getBytes());
            message.setQos(qos);
            sampleClient.publish(topic, message);
            System.out.println("Message published");
            sampleClient.disconnect();
            System.out.println("Disconnected");
            System.exit(0);
        } catch (MqttException me) {
            System.out.println("reason " + me.getReasonCode());
            System.out.println("msg " + me.getMessage());
            System.out.println("loc " + me.getLocalizedMessage());
            System.out.println("cause " + me.getCause());
            System.out.println("excep " + me);
            me.printStackTrace();
        }
    }
}

Let’s see how it works.

MQTT connection setup

int qos = 2;
String topic = "<USERNAME>/<ASSET-ID>/measures";
String broker = "ssl://mqtt.servitly-sandbox.com:8883";
String clientId = "<USERNAME>_CLIENT";
String username = "<USERNAME>";
String password = "<PASSWORD>";

Here, we are defining the parameters needed for the connection, all of them have been configured during the product registration within Servitly.

MQTT connection certificate

All the Servitly connection certificates are secured over SSL, for more details about certificates refer to the Security article.

Create the MQTT message payload

ObjectNode payload = JsonNodeFactory.instance.objectNode();
payload.put("ts", System.currentTimeMillis());
ObjectNode data = JsonNodeFactory.instance.objectNode();
data.put("measure1", 42 + RandomUtils.nextInt(10));
data.put("measure2", 24 + RandomUtils.nextInt(10));
payload.set("data", data);

Here, we are preparing the MQTT payload that contains the measures being sent to Servitly. A generic payload has the following format:

{"ts": 1605179226000,
 "data":{
    "measure1": 42,
    "measure2": 24
 }
}

Publish the MQTT message

Here, we are creating the MQTT client that will connect to Servitly, and send the message that we have previously created.

MqttClient sampleClient = new MqttClient(broker, clientId, persistence);

MqttConnectOptions connOpts = new MqttConnectOptions();
connOpts.setCleanSession(true);
connOpts.setUserName(username);
connOpts.setPassword(password.toCharArray());

System.out.println("Connecting to broker: " + broker);
sampleClient.connect(connOpts);
System.out.println("Connected");

System.out.println("Publishing message: " + payload.toString());
MqttMessage message = new MqttMessage(payload.toString().getBytes());
message.setQos(qos);
sampleClient.publish(topic, message);
System.out.println("Message published");

If everything works correctly, the result will be the Connection Status changed to ONLINE, and then a new measure is received.

Dealing with configuration parameters

The Generic-Device thing-definition exposes two metrics and a configuration-parameter:

METRIC

MAPPING PATH

MAPPING NAME

Measure 1

measures

measure1

Measure 2

measures

measure2

Parameter 1

measures

parameter1

Parameter1 can be updated directly within the dashboard, using the corresponding configuration-parameter in the Overview tab.

To receive data from Servitly for the Parameter 1 parameter, the MQTT client has to subscribe to the following topic:

<USERNAME>/<ASSET-ID>/command

Technical restrictions

The communication between the gateway and Servitly is TCP/IP based and encrypted with TLS 1.2.
The MQTT broker is exposed on the 8883 port, to open the connection this information is mandatory:
- username and password: credentials defined within the Connection tab of the equipment registered within Servitly.
- asset-id: the ID of the asset opening the connection, usually the serial number, or the MAC address can be used.
The MQTT topics must always start with the <USERNAME>/<ASSET_ID>/ path.
The MQTT topics must always end with the metric mapping path.
The Servitly Lab tenant allows 200 measures per hour per equipment, the measures exceeding such a limit will be discarded until the end of the hour.
The certificates of Servitly are periodically updated (see the Security article).

Get started with MQTT

Account creation

MQTT Connector Configuration

MQTT Client

MQTT connection setup

MQTT connection certificate

Publish the MQTT message

Dealing with configuration parameters

Technical restrictions

Comments

Account creation

MQTT Connector Configuration

MQTT Client

MQTT connection setup

MQTT connection certificate

Publish the MQTT message

Dealing with configuration parameters

Technical restrictions

Related articles