IMT and IoT Gateway

Effortlessly send/receive IoT MQTT messages anywhere via RockREMOTE.

note

Minimum version v0.12.0

Iridium Messaging Transport (IMT)

IMT is an Iridium Certus service that allows messages up to 100kb in length to be sent and recieved by terminals.

This is an alternative data transport to IP, and benefits from being cost-effective and data efficient.

IoT Gateway - Local Environment

This is where your field application resides - perhaps a remote sensor monitoring an oil and gas pipeline or a remote camera trap monitoring biodiversity in the jungle.

RockREMOTE has combined IMT with the MQTT protocol.

RockREMOTE exposes an MQTT broker for local devices attached to the LAN. Integrators can use any MQTT client or library to send/receive messages; libraries exist for all languages and platforms (including Raspberry Pi and Arduino). Once connected, integrators can publish messages to any topic in any message format; the service automatically packages and transmits these messages via IMT. The only restriction is the total size of the topic and payload, see the Limitations section below.

IoT Gateway automatically handles all connection lifecycle management, message queuing and transmission retries; facilitating simple fire-and-forget functionality.

There are several features to ensure the most efficient use of data:

• Multiple outbound MQTT messages can be queued up on the RockREMOTE until user-defined conditions are met (minimum time passed, minimum total size of messages)
• Multiple queued MQTT messages are packed into a single IMT message
• Data compression is sometimes applied to messages when this helps reduce size

This all happens automatically; published MQTT messages will appear identical to what was sent.

IoT Gateway supports multiple concurrent LAN devices, wired and wireless (if fitted).

Cloudloop MQTT - Cloud Environment

This is where all your messages land back down to Earth - from here they can be routed to different cloud-services so that you can ingest it into your own system.

Enabling integrators to benefit from a seamless MQTT experience using existing industry standard tools and libraries. Cloudloop MQTT is a secure, highly available MQTT service providing low-latency robust two-way message delivery.

Integrators connect over an encrypted session using certificate-based authentication; new certificates can be generated using the existing Cloudloop API.

Once connected, messages published in the Local Environment will be automatically syndicated on the same topics in the Cloud Environment.

Alternative delivery destinations can be configured, to allow messages to be additional sent to AWS S3 and AWS SQS destinations to integrate with existing cloud-services.

Configuration

RockREMOTE Local Environment

MQTT IoT IMT Settings

In the web UI, go to the IoT Gateway page using the main menu.

• MQTT Broker Settings
  • Must be Enabled to use IoT Gateway
  • Username and Password (optional) that devices on the LAN use to authenticate
  • Listening Port the MQTT server uses, this must be 1883 (TLS not currently supported)
• MQTT Transmission Settings
  • Must be Enabled to use IoT Gateway
  • MO (outbound) MQTT message queue settings:
    • Max Queue Size (bytes, default 50000): if not zero, message in the queue will be sent whenever the total of all payloads reaches this value
    • Max Queue Age (seconds, default 60): if not zero, then messages in the queue will be sent whenever the oldest message has been waiting for this amount of time
    • Send Messages Immediately (default off): sets both Max Queue Size and Max Queue Age fields to 0, so messages are sent as soon as they are received from LAN devices

If both Max Queue Size and Max Queue Age fields are set (non-zero), then the MO queue of MQTT messages will be sent if either of those conditions are met.

The minimum billable Message size for Iridium IMT messages is 500 Bytes; we recommend setting Max Queue Size = 500 Bytes where practical to do so - this will ensure that messages are transmitted as economically as possible.

Local devices must be configured to connect to the RockREMOTE MQTT broker:

• Protocol - mqtt://
• Hostname - whatever the LAN IP is, default 192.168.250.1
• Port - 1883 (no TLS)
• Username/Password - as configured, or left blank

Queue Settings

On the web UI, in IoT Gateway page there is some extra configuration parameters for the queue. This this would apply to all MQTT IoT MO messages and CDM MO messages, see the screenshot below.

• Queue Configuration

  • MO Time To Live (TTL) This parameter defines the lifespan of a message. Once the MO message age reaches the specified TTL, it will be discarded from the MO queue.
  • MO Retry Count The message retry count for an MO message determines how many times the system will attempt to send the message if delivery fails. If the retry count is set to 0, only the TTL will be considered. However, if the retry count is set to a value greater than 0, the system will make multiple delivery attempts up to the specified retry count before the TTL threshold is reached. If the retry count is exceeded before the TTL, the message will be dropped from the MO queue.

• MO Queue Status

  • State This gives the current state of a MO message which has been parsed to the Iridium modem for transmission.
  • MO Queue The number MO messages queued.
  • MO Bytes The sum of bytes of all the MO messages queued.
  • Clear Queue This button will clear all the MO messages waiting to be transmitted.

• Topic Statistics

  • Topic Name The topic name which the Iridium is provisioned for.
  • MO Count The number of MO messages which have been sent on this topic.
  • MT Count The number of MT messages which have been received on this topic.
  • MO Drop Count The number of MO messages which have been dropped on this topic.
  • MT Drop Count The number of MT messages which have been dropped on this topic.

Cloud Environment

1. Obtain Cloudloop API token
   • If you don't have API credentials - you'll need to request this from your Account Manager; it'll look something like this: 655f05ad-dc02-4b92-aca5-6867cd9af863
2. Request your Cloudloop MQTT Certificate and Keys using the Cloudloop API
   • Using your browser, request the following URL (with your API token):
     • https://api.cloudloop.com/User/DoGenerateMqttCertificate?token=XXXX
   • This will return a zip archive containing your certificate and keys
     • CA Server Certificate - CloudloopMqtt.pem
     • Client Certificate - XXXXXXXX-certificate.pem.crt
     • Client Key (Private Key) - XXXXXXXX-private.pem.crt
     • Important Information - hello.txt
   • It’s very important that you retain these files securely - it's not possible to retrieve these again and they enable secure access to your data
   • If you make this request again and generate a new certificate; the previous one will automatically be invalidated and will immediately become unusable
3. Setup MT topic filters in Cloudloop data (this is explained in the Operation section below)
4. Connect to Cloudloop MQTT
   • Protocol - mqtt://
   • Hostname - mqtt.cloudloop.com
   • Port - 8883 (MQTT over TLS)
   • Username/Password - not required (we're using Certificate-based authentication)
   • Certificate:
     • CA Server Certificate - CloudloopMqtt.pem
     • Client Certificate - XXXXXXXX-certificate.pem.crt
     • Client Key (Private Key) - XXXXXXXX-private.pem.crt

Operation

Topic Mapping

You’re free to publish to any valid MQTT topic name you like - e.g. site1/sensor2/temperature

Topic names will be transmitted with every message, so to reduce the amount of data used keep topic names short.

• To enable Cloudloop MQTT to securely support multiple users - a prefix is automatically prepended to your topics names in the Cloud Environment
  • e.g. iot/ACCOUNT-ID/your/custom/topic/name
• The prefixing only applies in the Cloud Environment - the prefix will automatically be added/removed when receiving/sending messages from/to the Local Environment.
  • e.g. Local Environment Publish to: this/is/my/topic would be published to the Cloud Environment to: iot/ACCOUNT-ID/this/is/my/topic
  • e.g. Cloud Environment Publish to: iot/ACCOUNT-ID/this/is/other/topic would be published to the Local Environment to: this/is/my/other/topic
• You can find your Account Identifier inside the hello.txt file generated during setup
• In the Cloud Environment it's not possible to publish/subscribe outside of your account prefix - if you try and do this your request will be ignored; your messages are only accessible to you
• During development it may be useful to use the: iot/ACCOUNT-ID/# Topic Filter to subscribe to all messages published to your account.
• During production we recommend using more specific filters; using enables you to benefit from advanced functionality - including message retention and message replay.

Mobile Terminated Messages (MT)

• These are messages sent from the Cloud Environment to the Local Environment
• To provide the greatest amount of flexibility - there's no prescribed naming convention for topics. Therefore, integrators need to provide mapping details to enable Cloudloop to route messages published to specific topics to specific devices
• With this in mind, we recommend incorporating some kind of device identifier into your topic design (e.g. device1/sensor1) to segregate messages by device
• For each device, Integrators can specify one or more MT Topic Filter - if a message is published to a topic that matches this filter, it will be sent down to the device
• MT Topic Filters can be exact (e.g. device1/sensor1) or can be partial (e.g. device1/#)
• This approach enables both one-to-one message mapping to a single device; and fan-out to multiple devices; ensuring you're in control over what's sent to the Local Environment.

Topic Filters can be managed via Cloudloop data

Retain

The MQTT retain flag is respected and preseved on both MT and MO messages.

Examples (Mosquitto CLI)

Remember to replace ACCOUNT-ID

Local Environment - Publish Message "Hello World" to "this/is/my/topic"

mosquitto_pub -d
-L mqtt://192.168.250.1:1883/this/is/my/topic -m "Hello World"
-u username
-P password

Local Environment - Subscribe to all Messages

mosquitto_sub -d
-L mqtt://192.168.250.1:1883/#
-u username
-P password

Cloud Environment - Publish Message "Hello World" to "this/is/my/topic"

Refer to Cloudloop Knowledge.

Cloud Environment - Subscribe to all Messages

Refer to Cloudloop Knowledge.

Examples (Python 3 Paho)

Local Environment - Publish Message "Hello World" to "this/is/my/topic"

import paho.mqtt.client as mqtt

client = mqtt.Client()

client.username_pw_set("username", "password")
client.connect("192.168.250.1", 1883, 60)
client.publish("this/is/my/topic", "Hello World")

Local Environment - Subscribe to all Messages

import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, rc):
  client.subscribe("#")

def on_message(client, userdata, msg):
  print(msg.topic, str(msg.payload))

client = mqtt.Client()
client.username_pw_set("username", "password")
client.on_connect = on_connect
client.on_message = on_message

client.connect("192.168.250.1", 1883, 60)

client.loop_forever()

Alternative Delivery Destinations

Refer to Cloudloop Knowledge.

Limitations

Maximum MQTT topic string length: 100 bytes

Maximum MQTT payload size: 90,000 bytes

MQTT messages that exceed these limits may still be accepted by the MQTT broker (Local and Cloud), but will then be dropped.

The theoretical maximum throughput is 22kbps for MO messages and 88kbps for MT messages, however even in ideal conditions the practical limit will be lower due to contention and overhead.

If the internal MO queue of messages becomes too large, older message will be dropped.

MQTT properties are discarded in MO and MT messages.

Suggested MQTT libraries

• Eclipse Mosquito for command-line use
• MQTT Explorer for interactive use
• Eclipse Paho for programatic use