CREATING AN MQTT CONNECTION

The MQTT connector requires access to a MQTT broker.

Note

To use the MQTT connector, refer to the guide here.
Alternatively, if you want to connect directly to an Actility MQTT broker, follow the instructions here.

Creating a Connection from the UI

You must have deployed a MQTT server prior to configuring a MQTT Connector instance. The MQTT server must be accessible from your ThingPark Enterprise server, and you need to know the path of MQTT topics you want to publish to (uplinks) or subscribe (downlinks).

You also need to know the parameters that are required to perform this task. To learn more, click Parameters required for connecting to a MQTT application below in this topic.

1. Click Applications -> Create -> View More Applications Type.

Then, a new page will open. Select the connection type: MQTT

Note

The application creation form is the same for a JSON enriched document as for a JSON legacy document.

2. Fill in the form as in the example below.

Note

Parameters marked with * are mandatory.

The Certificate and the Private Key are required for both SSL and WSS protocols. This does not apply to TCP.

3. Click Create.

• A notification appears on the upper right side of your screen to confirm that the application has been created.

4. After creating the application, you will be redirected to the application details.

Parameters required for connecting to a MQTT application

The parameters are the following:

UI Field	Description
Application Name	Name of the application that you want to register (Editable).
Uplink Topic Pattern	Defines a pattern of topic for the Uplink.
Downlink Topic Pattern	Defines a pattern of topic for the Downlink.
Host Name	The hostname/IP and port of your MQTT server. For example, "myhostname.com:8883".
Protocol	Protocol to be used for your connection with your MQTT server. Choose among SSL, WSS and TCP.
Username	The username to access your MQTT server.
Password	The password to access your MQTT server.
Certificate	The client certificate file (X.509 with .crt format only) used to connect to your MQTT server. Only required when you are using double factor authentication (login/password and client interface). This parameter does not apply to TCP protocol.
Private Key	The client Private Key file (PKCS#8 format only) used to connect to your MQTT server. Only required when you are using double factor authentication (login/password and client interface). This parameter does not apply to TCP protocol.
Description	Any useful information related to the application.
QoS	Quality of Service (QoS) is an agreement between the message sender and receiver that defines the level of delivery guarantee for a specific message.

Creating a Connection With API

MQTT over TLS v1.2 connection is the recommended protocol to use with MQTT Brokers. You need to create a MQTT Connector instance (Connection) before you can associate it to device(s). For more information, see Creating a Connection instance. The creation of a Connection establishes a link from ThingPark IoT Flow to the MQTT Broker. The link can be used to publish Uplink and related metadata information for any device associated to this instance of MQTT Connector, but will also publish messages that may have been redirected from other Connectors.

To do this, you need to use the following endpoints:

• POST/connections for creation
• PUT/connections for modification
• DELETE/connections for deletion

Note

When you want to update a configuration property on a Connection, you must provide all configuration properties again.

Example of the creation of a Connection.

POST /connections

    {
      "connectorId": "actility-mqtt-iot",
      "name": "Actility MQTT (SSL) Connection",
      "configuration": {
        "description": "MQTT (SSL) connection example",
        "uplinkTopicPattern": "mqtt/things/{DevEUI}/uplink",
        "downlinkTopicPattern": "mqtt/things/{DevEUI}/downlink",
        "hostName": "91.134.250.109:8883",
        "protocol": "SSL",
        "username": "mycompany",
        "password": "bar",
        "certificate": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
        "privateKey": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
        "qos": 1
      }
    }

The following table lists the expected results of the properties when applied.

Property	Expected results
connectorId	Must be set to actility-mqtt-iot for AWS IoT cloud platform.
configuration/uplinkTopicPattern	Defines a pattern of topic for the Uplink. Could contain JSONPath expression, check common parameters section for examples.
configuration/downlinkTopicPattern	Defines a pattern of topic for the Downlink. Could contain JSONPath expression, check common parameters section for examples.
configuration/hostName	Hostname/IP and port of your MQTT Broker.
configuration/protocol	Protocol to be used for the connection with your MQTT server, possible values are 'SSL' (MQTT over SSL), 'WSS' (MQTT over secure Web Sockets) or 'TCP' (MQTT over TCP without encryption).
configuration/username	Login to access your MQTT Broker.
configuration/trustedCaCertficate	Contents of the client CA certificate file (X.509 with .crt format only) used to connect to your MQTT server. Only required when your+ client certificate is not self-sign).
configuration/certificate	Contents of the client certificate file (X.509 with .crt format only) used to connect to your MQTT server. Only required when you are using double factor authentication (login/password + client certificate).
configuration/privateKey	Contents of the client private key file (PKCS#8 format only) used to connect to your MQTT server. Only required when you are using double factor authentication (login/password + client certificate).
configuration/connectionTimeout	Max time needed for establishing a connection. (Default=5000ms, max=30000ms)
configuration/actionTimeout	Max time available for each action like publishing a message or subscribe to a topic. (Default=1000ms, max = 10000ms)

Important note

All properties are not present in this example. You can check the rest of these properties in the common parameters section.

Creating an Access to MQTT Broker

To interact with the location API, you first need to obtain a bearer token. Follow these steps to acquire the required credentials and connect to your MQTT broker.

---

1. Obtain a Bearer Token

1. Click on the following link: ThingPark Swagger UI.
2. Click on "Try it out", enter your ThingPark login credentials and execute the request.
3. In the response body, locate and copy the value of the access_token attribute.

---

2. Retrieve Your API Token for the MQTT Broker

Available Platforms:

• Community: Swagger UI
• PROD EU: Swagger UI
• PROD AU: Swagger UI
• PROD US: Swagger UI

Note: The platform link you select depends on the environment where you obtained your initial token. For example, if you retrieved a token using PROD EU credentials, you should select the PROD EU link.

Steps to Follow:

1. Open the appropriate Swagger UI link based on your platform.
2. Click the Authorize button to open the authorization window.

3. Paste your bearer token into the value input field and click Authorize.
4. If the login is successful, you will see a confirmation message similar to the image below:

5. Navigate to the API Key section, specifically the POST /apiKeys request.

6. Click Try it Out and execute the request to generate an API Key.
7. The response will contain your apiKey, which you can use to authenticate with your MQTT broker. Make sure to note which platform you used (e.g., PROD US) since the broker access will depend on it.

---

3. Connect to Your MQTT Broker

Below are the broker URLs and ports for each platform:

Environment	Broker URL	Port
BROKER ECO	mqtt-eco.thingpark.com	8883
BROKER PROD EU	mqtt-eu.thingpark.com	8883
BROKER PROD AU	mqtt-au.thingpark.com	8883
BROKER PROD US	mqtt-us.thingpark.com	8883

Authentication Details:

• Username: You can use any value, but the convention is to use unused_username.
• Password: Use your apiKey generated in the previous step.

With these details, you should be able to successfully connect to the MQTT broker for your respective platform.

Limitations

There are currently no known limitations to the MQTT connector.

How to test the MQTT Connection

1. Download and install a MQTT client, for example MQTT Explorer or MQTT.fx.

2. Create a new connection and connect to the MQTT Broker using your configuration:

3. Select the Subscribe tab, fill the uplink topic you want to monitor (that is, mqtt/things/+/uplink) and click Subscribe.

You should see incoming uplinks (published by your IoT Flow MQTT connector) in the right part of the screen.

In order to test the processing of subscribed topic messages by the MQTT connector, you need to properly format the message. LoRaWAN Commands targeted to a given DevEUI look like this:

mosquitto_pub \
 -h $BROKER_PUBLIC \
 -p $TLS_PUBLIC_LISTENER \
 -u $SUPER_USERNAME \
 -P $SUPER_PASSWORD \
 -t "mqtt/things/A81758FFFE04F27E/downlink" \
 -m '{
         "DevEUI_downlink": {
             "Time": "2022-06-08T15:50:00.882+02:00",
             "DevEUI": "A81758FFFE04F27E",
             "FPort": "8",
             "payload_hex": "9e1c4852512000220020e3831071",
             "Confirmed": "1",
             "FlushDownlinkQueue": "1"
         }
     }'

Any other JSON message will be accepted and processed by the forwarding rules configured in the MQTT connector (forwarding rules do not apply to Commands). Messages not properly JSON-formatted will be ignored.

Troubleshooting

MQTT Broker timeouts

If your MQTT Broker is really far from the Actility platform, the network latency can cause the MQTT connection to timeout. These two parameters may need to be tuned accordingly :

Parameter	Description	Default
configuration/connectionTimeout	Max time allowed for establishing a connection.	Default=5s, max=10s
configuration/actionTimeout	Max time available for each action, e.g. publishing a message or subscribe to a topic.	Default=1s, max = 10s