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

Integration Configuration

ParameterDescription
server

Address of the broker, the url must contain the port also. eg.: 192.168.0.5:1883, mqtt.example.com:1883.

topicTopic where to push uplinks.
clientIDAnything you like to identify the client on the broker (check mqtt docs for more information on this).
ca-certificateThe MQTT broker's CA authority's TLS certificate.
certificateThe client TLS certificate.
keyThe client TLS private key.
templateThis 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 keyNote: 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:

NameDescription
.Message.Device.IDThe device ID
.Message.Device.NameThe name of the device
.Message.Device.LabelsThe device's list of labels
.Message.ValuesThe updated state from the message
.Message.TimeThe 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.DeviceThe network server's ID of this device (commonly the DevEUI)
.Message.NetworkServer.ConnectionThe 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

Template

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

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