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.

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)

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)
  • MT Messages can be published by the Client using the same namespace ending with MT; as defined by LingoMT Message structure, they must include an IotMessage.
  • The platform only performs the role of Broker; it doesn't presently support Bridge or Client modes of operation
  • Total maximum published Message size (including meta-data) is 128 Kb
  • 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.

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]

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.key
--cafile CloudloopMQTT.pem
{
  "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 Message to Thing​

Using Eclipse Mosquito

mosquitto_pub -d
-L mqtt://mqtt.cloudloop.com:8883/iot/ACCOUNT-ID/THING-ID
-m "Hello World"
--cert XXXXXXXX-certificate.pem.crt
--key XXXXXXXX-private.pem.key
--cafile CloudloopMQTT.pem

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.