Using the MQTT Client integration, it is possible to send data to an external MQTT broker in a adaptable format.

Integration Configuration

Parameter	Description
server	Address of the broker, the url must contain the port also. eg.: 192.168.0.5:1883, mqtt.example.com:1883.
topic	Topic where to push uplinks.
clientID	Anything you like to identify the client on the broker (check mqtt docs for more information on this).
ca-certificate	The MQTT broker's CA authority's TLS certificate.
certificate	The client TLS certificate.
key	The client TLS private key.
template	This optional parameter is used to customize the message that is sent. See below

Example

{
  "type": "MQTTClient",
  "name": "MQTT Client integration",
  "params": {
    "server": "mqtt.example.com:1883",
    "topic": "lora-devices",
    "clientID": "thingshub"
  },
  "selector": {
    "$or": [
      "all"
    ]
  }
}

JS

If using the ssl all the ssl related keys are required: certificate, ca-certificate and key. Note: the cerficates and the key must be concatenated in one line string escaped for json.

How to Set this Integration up

The endpoint for creating an integration is the same for all types: POST /api/v3/integrations.

Below are two examples with parameters to send with the POST request to create different types of mqtt client integrations:

Simple example without SSL

Simple example no SSL

{
  "type": "MQTTClient",
  "name": "Company-wide MQTT Broker Connection",
  "params": {
    "server": "mqtt.example.com:1883",
    "topic": "lora-devices",
    "clientID": "thingshub"
  }
}

JS

Example Using an SSL Certificate

Example using an SSL certificate

{   
    "type": "MQTTClient",
    "server": "mqtt.example.com:1883",
    "topic": "lora-devices",
    "clientID": "thingshub",

    "certificate": "-----BEGIN CERTIFICATE-----\nDUMMYDATA\n-----END CERTIFICATE-----\n",
    "ca-certificate": "-----BEGIN CERTIFICATE-----\nDUMMYDATA\n-----END CERTIFICATE-----\n",
    "key": "-----BEGIN RSA PRIVATE KEY-----\nDUMMYDATA\n-----END RSA PRIVATE KEY-----\n",
}

JS

The certificate information has to be in a single line, so please replace all line breaks with "\n".

Templating

The MQTT client integration allows adapting the data format to custom needs. Syntax follows Golang's template package. This means double curly braces are used to indicate template fields. The following fields can be used:

Name	Description
`.Message.Device.ID`	The device ID
`.Message.Device.Name`	The name of the device
`.Message.Device.Labels`	The device's list of labels
`.Message.Values`	The updated state from the message
`.Message.Time`	The update's timestamp (not necessarily the time stamp of the uplink). The meaning of this is is device driver dependent, but most commonly this is the time of measurement.
`.Message.NetworkServer.Device`	The network server's ID of this device (commonly the DevEUI)
`.Message.NetworkServer.Connection`	The network connection ID.

A message can be in any text format (though JSON easily is the most common). Given a device with the DevEUI 0102030405060708 with the template shown below, an uplink as shown below will be transformed to the following message:

Template

{
  "deveui": "{{ .Message.NetworkServer.Device }}",
  "value": "{{ .Message.Values.temperature }}"
}

JS

Uplink

Original Uplink

{
  "temperature": 26.5,
  "humdity": 60
}

JS

MQTT Message

Resulting MQTT Message

{
  "deveui": "0102030405060708",
  "value": "26.5"
}

JS

To put it all together now, activate a device of the Elsys ERS family on the thingsHub, assigned the right device driver and the label roomsensor, then do the following REST call to POST <tenant>.thingshub.smartmakers.de/api/v3/integrations:

{
  "type": "MQTTClient",
  "name":
  "params": {
    "server": "mqtt.example.com:1883",
    "topic": "roomsensors",
    "clientID": "thingshub",
    "template": "{ \"deveui\": \"{{ .Message.NetworkServer.Device }}\", \"value\": \"{{ .Message.Values.temperature }}\"}"
  },
  "selector": {
    "$or": [
      "roomsensor"
    ]
  }
}

CODE

With the next uplink, you should receive this uplink in the desired output format on the topic "roomsensors".

Sending Data to the Azure IoTHub

The thingsHub's MQTT integration can also be used to send data to the Azure IoTHub. With this approach, the thingsHub will act as a single device on the IoTHub, repsenting all of the attached (and labelled) IoT devices.

The following configuration

Option	Value
server	Hostname and port, e.g. "example.azure-devices.net:8883"
clientID	The client ID must be set to the name of the device.
topic	The topic must be set to "devices/<device-name>/messages/events/", e.g. "devices/test-device/messages/events/".
ca-certificate	The CA certificate should be left empty. The MQTT broker of the Azure IoTHub uses a public certificate which the thingsHub trusts already.
certificate	The client certificate in the PEM format including the "-----BEGIN CERTIFICATE------" and "------END CERTIFICATE------". "A client certificate for testing can be generated according to Azure's guide for self-signed certificates: https://github.com/Azure/azure-iot-sdk-c/blob/master/tools/CACertificates/CACertificateOverview.md
key	The private key which matches the client certificate in the PEM format.
username	Th username must be filled with "<full-hostname>/<device-name>/?api-version=2018-06-30", e.g. "example.azure-devices.net/test-device/?api-version=2018-06-30".
password	The password field should stay empty. Authentication is done with the TLS client certificate.