Skip to main content

MQTT

Direction: MO and MT

Widely used in the IoT community - upon receipt, Messages are published to the Cloudloop MQTT Broker; clients can Subscribe to receive Messages via predefined Topic Namespaces. Additionally, Clients can also Publish Messages to the Broker to send MT Messages to Things. RockREMOTE users can make use of the advanced MQTT IoT bridge for seamless pub/sub between their device and Cloudloop.

Authentication​

  • The platform only supports Certificate-based authentication
  • Certificates can be generated via the [Generate Certificate] within the Destination
    • Or, programmatically using: Data/DoGenerateMqttCertificate
    • Both will provide a zip file containing all the Certificates and Keys required for Authentication
  • Client Setup:
    • Protocol - mqtt://
    • Hostname - mqtt.cloudloop.com
    • Port - 8883 (MQTT over TLS)
    • Username/Password - Can be left blank, we're using Certificate-based Authentication
    • MQTT Client Id - Can be left blank
    • CA Server Certificate - CloudloopMqtt.pem [in zip file]
    • Client Certificate - XXXXXXXX-certificate.pem.crt [in zip file]
    • Client Key (Private Key) - XXXXXXXX-private.pem.crt [in zip file]

Lingo Namespace​

The platform exposes a unified topic namespace structure for all Things within in an Account.

lingo / ACCOUNT ID / THING ID / (MO/MT)

For example:

lingo / yPQkYomwxvAZaJWqXrnDbdOXgezVKjGM / ejoGRxQrXpzkPJngbjBydwYZbqmDagNA / (MO/MT)

Example - SUBSCRIBE to all Things​

Using Eclipse Mosquito

mosquitto_sub -d
-L mqtt://mqtt.cloudloop.com:8883/lingo/YOUR-ACCOUNT-ID/+/MO
--cert XXXXXXXX-certificate.pem.crt
--key XXXXXXXX-private.pem.crt
--cafile CloudloopMQTT.pem

Example - SUBSCRIBE to a specific Thing​

Using Eclipse Mosquito

mosquitto_sub -d
-L mqtt://mqtt.cloudloop.com:8883/lingo/YOUR-ACCOUNT-ID/YOUR-THING-ID/MO
--cert XXXXXXXX-certificate.pem.crt
--key XXXXXXXX-private.pem.crt
--cafile CloudloopMQTT.pem

Example - LingoMO message received from Lingo namespace SUBSCRIPTION​

{
  "id": "c0eb3dd4-0ab5-41f2-8fbd-b71083161fba",
  "receivedAt": {
    "year": 2023,
    "month": 10,
    "day": 9,
    "hour": 9,
    "minute": 41,
    "second": 13
  },
  "identity": {
    "accountId": "yJGjpPobLlmOdanVkPWAKYzNMgwVZkrR",
    "subscriber": {
      "id": "XgwyNPpDmebJLWXmwgEoARqxMdZOVGva",
      "type": "SUBSCRIBER_TYPE_SBD",
      "description": ""
    },
    "hardware": {
      "id": "joGRxQrXpzkPJEglMOBydwYZbqmDagNA",
      "type": "HARDWARE_TYPE_LEOPARD3",
      "imei": "300234065366010",
      "serial": ""
    },
    "identifier": "300234065366010",
    "thingId": "DgXeoxwVPMyrdOBJeEGlqKRJLbajQkzZ"
  },
  "sbd": {
    "imei": "300234065366010",
    "cdrReference": "3152085395",
    "momsn": 5394,
    "mtmsn": 0,
    "sessionAt": {
      "year": 2023,
      "month": 10,
      "day": 9,
      "hour": 9,
      "minute": 41,
      "second": 12
    },
    "status": "SESSION_STATUS_OK",
    "location": {
      "latitude": 50.87023333333333,
      "longitude": -1.1934833333333335,
      "cep": 4.0
    }
  },
  "message": "JgBreyuiF+0IgswAAAQBR2QnBQ=="
}

Example - PUBLISH simple payload to Thing​

Example simple payload:

{
  "message": "BASE-64-ENCODED-PAYLOAD"
}

Using Eclipse Mosquito

mosquitto_pub -d
-L mqtt://mqtt.cloudloop.com:8883/lingo/YOUR-ACCOUNT-ID/YOUR-THING-ID/MT
-m '{"message": "BASE-64-ENCODED-PAYLOAD"}'
--cert XXXXXXXX-certificate.pem.crt
--key XXXXXXXX-private.pem.crt
--cafile CloudloopMQTT.pem

Example - PUBLISH P6 payload to supported Thing (RockSTAR, RockFLEET, RockAIR, Sense Switch)​

Example P6 message requesting system config:

{
  "p6": {
    "type": "MT_MESSAGE_CONFIG_GET",
    "getConfig": {
      "blocks": [
        "CONFIG_BLOCK_SYSTEM"
      ]
    }
  }
}

Using Eclipse Mosquito

mosquitto_pub -d
-L mqtt://mqtt.cloudloop.com:8883/lingo/YOUR-ACCOUNT-ID/YOUR-THING-ID/MT
-m '{
  "p6": {
    "type": "MT_MESSAGE_CONFIG_GET",
    "getConfig": {
      "blocks": [
        "CONFIG_BLOCK_SYSTEM"
      ]
    }
  }
}'
--cert XXXXXXXX-certificate.pem.crt
--key XXXXXXXX-private.pem.crt
--cafile CloudloopMQTT.pem

Example - PUBLISH to a specific topic on device broker (RockREMOTE Classic/Rugged - IoT Gateway Messages only)​

Example with required IotMessage:

{
  "iot": {
    "topic": "my/custom/topic",
    "message": "BASE-64-ENCODED-PAYLOAD",
    "retain": true
  }
}

Using Eclipse Mosquito

mosquitto_pub -d
-L mqtt://mqtt.cloudloop.com:8883/lingo/YOUR-ACCOUNT-ID/YOUR-THING-ID/MT
-m '{
  "iot": {
    "topic": "my/custom/topic",
    "message": "BASE-64-ENCODED-PAYLOAD",
    "retain": true
  }
}'
--cert XXXXXXXX-certificate.pem.crt
--key XXXXXXXX-private.pem.crt
--cafile CloudloopMQTT.pem

Group Namespace​

There is also a topic namespace for all Things within a Thing Group

group / ACCOUNT ID / GROUP ID / (MO/MT)

For example:

group / yPQkYomwxvAZaJWqXrnDbdOXgezVKjGM / ejoGRxQrXpzkPJngbjBydwYZbqmDagNA / (MO/MT)

MT Messages will be sent to all Things within the group.

Example - SUBSCRIBE to a Thing Group​

Using Eclipse Mosquito

mosquitto_sub -d
-L mqtt://mqtt.cloudloop.com:8883/group/YOUR-ACCOUNT-ID/YOUR-THING-GROUP-ID/MO
--cert XXXXXXXX-certificate.pem.crt
--key XXXXXXXX-private.pem.crt
--cafile CloudloopMQTT.pem

Example - PUBLISH to a Thing Group​

Example simple payload:

{
  "message": "BASE-64-ENCODED-PAYLOAD"
}

Using Eclipse Mosquito

mosquitto_pub -d
-L mqtt://mqtt.cloudloop.com:8883/group/YOUR-ACCOUNT-ID/YOUR-THING-GROUP-ID/MT
-m '{"message": "BASE-64-ENCODED-PAYLOAD"}'
--cert XXXXXXXX-certificate.pem.crt
--key XXXXXXXX-private.pem.crt
--cafile CloudloopMQTT.pem

Notes​

  • MO Messages are published to this Namespace ending with MO - payload will be as prescribed by the LingoMO Message structure
  • Clients can SUBSCRIBE to specific Things (lingo / ACCOUNT ID / THING ID / MO), or all Things - (lingo / ACCOUNT ID / + / MO)
  • Clients can SUBSCRIBE to a specific Thing Group (lingo / ACCOUNT ID / THING GROUP ID / MO)
  • MT Messages can be published by the Client using the same namespace ending with MT; as defined by LingoMT.
  • RockREMOTE devices will publish messages locally on the topic provided in the IotMessage format.
  • P6 and IotMessage payloads can be sent to a group MT but all devices in the group must support these formats.
  • Attempting to subscriber to topics outside the prescribed namespace will automatically terminate the connection
  • Message payloads cannot be larger than ~97 KB due to MQTT upload limits.
  • The retain option allows the preserving of the previous message sent to a topic, this can be toggled when managing the destination (defaults on)

Advanced Use

IoT Gateway namespace (RockREMOTE Classic/Rugged - IoT Gateway Messages only)​

Additionally, where Message originate from IoT Gateway on RockREMOTE; they're additionally published to the iot Namespace in accordance to the Topic it was originally published to in the Local Environment.

Local Environment: your / custom / topic / goes / here

Cloudloop: iot / ACCOUNT ID / your / custom / topic / goes / here

site123 / sensor12 / temperature >> iot / yPQkYomwxvAZaJWqXrnDbdOXgezVKjGM / site123 / sensor12 / temperature


Topic Filters (MT)​

To ensure Messages are sent to the correct Thing, an MT Filter must be specified - which maps Topics to Things.

Topic Filters can be concrete - this / specific / topic or include wildcards - this / specific / #

Typically, Topic Filters are set up 1:1 per Thing - for example:

  • projectX / site01 >> Thing 1234
  • projectX / site02 >> Thing 5678
  • projectY / site03 >> Thing 7531

To facilitate Message "fan-out", multiple Things can use the same Topic Filter:

  • projectX / alarm >> Thing 1234
  • projectX / alarm >> Thing 5678

When using topic filters, only the payload needs to be sent, the LingoMt format is not required.