Iridium CloudConnect for SBD on AWS

Partner Solution Deployment Guide


July 2023
Jaco Botes, Iridium Satellite LLC
Andrew Glenn, AWS Integration & Automation team

Refer to the GitHub repository to view source files, report bugs, submit feature ideas, and post feedback about this Partner Solution. To comment on the documentation, refer to Feedback.

This Partner Solution was created by Iridium Satellite LLC in collaboration with Amazon Web Services (AWS). Partner Solutions are automated reference deployments that help people deploy popular technologies on AWS according to AWS best practices. If you’re unfamiliar with AWS Partner Solutions, refer to the AWS Partner Solution General Information Guide.


This guide covers the information you need to deploy the Iridium CloudConnect for SBD Partner Solution in the AWS Cloud.

This Amazon Web Services (AWS) Partner Solution deploys Iridium CloudConnect for SBD in the AWS Cloud so that <purpose>. The Partner Solution is for Iridium users who want to receive their SBD device data in Amazon Simple Queue Service (Amazon SQS) queues in JavaScript Object Notation (JSON) format.

This Partner Solution deployment guide assumes that you have some familiarity with Iridium Short Burst Data (SBD) devices and communications.

Costs and licenses

There is no cost to use this Partner Solution, but you will be billed for any AWS services or resources that this Partner Solution deploys. For more information, refer to the AWS Partner Solution General Information Guide.

Iridium charges fees for messages, satellite network usage, and infrastructure setup, subject to applicable license agreements and terms and conditions with Iridium. Contact your Iridium representative, VAR, or service provider for details.


Deploying this Partner Solution with default parameters builds the following Iridium CloudConnect environment in the AWS Cloud.

Figure 1. Partner Solution architecture for Iridium CloudConnect on AWS

As shown in Figure 1, this Partner Solution sets up the following:

  • Amazon SQS to provide a highly available queueing service for Iridium SBD messages. This deployment configures the following queues:

    • Mobile-originated

    • Mobile-terminated

    • Mobile-terminated confirmation

    • Mobile-terminated error

  • An AWS Identity and Access Management (IAM) role and policy to set up Iridium CloudConnect cross-account authentication.

Deployment options

This Partner Solution provides a single deployment option:

Predeployment steps

Iridium partner or customer

If you are not already an Iridium partner or customer, navigate to Iridium to learn more. Existing Iridium customers that are not direct Iridium Value-Added Retailers (VARs) should inquire with their service provider if Iridium CloudConnect is available. Iridium maintains a list of approved Iridium CloudConnect service providers. For more information, see Who’s My Service Provider?

Deployment steps

  1. Sign in to your AWS account, and launch this Partner Solution, as described under Deployment options. The AWS CloudFormation console opens with a prepopulated template.

  2. Choose the correct AWS Region, and then choose Next.

  3. On the Create stack page, keep the default setting for the template URL, and then choose Next.

  4. On the Specify stack details page, change the stack name if needed. Review the parameters for the template. Provide values for the parameters that require input. For all other parameters, review the default settings and customize them as necessary. When you finish reviewing and customizing the parameters, choose Next.

    Unless you’re customizing the Partner Solution templates or are instructed otherwise in this guide’s Predeployment section, don’t change the default settings for the following parameters: QSS3BucketName, QSS3BucketRegion, and QSS3KeyPrefix. Changing the values of these parameters will modify code references that point to the Amazon Simple Storage Service (Amazon S3) bucket name and key prefix. For more information, refer to the AWS Partner Solutions Contributor’s Guide.
  5. On the Configure stack options page, you can specify tags (key-value pairs) for resources in your stack and set advanced options. When you finish, choose Next.

  6. On the Review page, review and confirm the template settings. Under Capabilities, select all of the check boxes to acknowledge that the template creates AWS Identity and Access Management (IAM) resources that might require the ability to automatically expand macros.

  7. Choose Create stack. The stack takes about 10 minutes to deploy.

  8. Monitor the stack’s status, and when the status is CREATE_COMPLETE, the Iridium CloudConnect for SBD deployment is ready.

  9. To view the created resources, choose the Outputs tab.

Figure 2. Iridium CloudConnect outputs after successful deployment

Postdeployment steps

Interacting with your Amazon SQS queues

AWS provides several ways to interact with Iridium CloudConnect SBD queues, including:

Receiving mobile-originated messages

The recommended approach for receiving mobile-originated (MO) messages is to long-poll the ICCMO.fifo queue. After messages are received, save your database to process the messages, and then delete the messages.

As a precaution in case of connectivity issues, Amazon SQS doesn’t automatically delete messages when they’re received. To delete a message, you must send a separate request after receiving it. For more information, see Receiving and deleting messages (console).
# Get the service resource
sqs = boto3.resource('sqs')

# Get the queue
queue = sqs.get_queue_by_name(QueueName='ICCMO.fifo')

# Process messages by printing out IMEI, location, and payload
for message in queue.receive_messages(WaitTimeSeconds=30):
  header = None
  location = None
  payload = None
  data = json.loads(message.body)

  for iei in data['data']:
    if data['iei_type'] == 'MO Header IEI':
      header = data
    elif data['iei_type'] == 'MO Location Information IEI':
      location = data
    elif data['iei_type'] == 'MO Payload IEI':
      payload = data

    # The message may contain location information
    if location is not None:
      print('IMEI {0} location is {1}'.format(
      location['latitude_longitude'] ))

    # The message may contain a payload
      if payload is not None:
      print('IMEI {0} payload of {1} bytes'.format(
        payload['mo_payload'] ))

# Let the queue know that the message is processed

Sending mobile-terminated messages

Mobile-terminated messages (MT) are sent asynchronously. Therefore, when establishing a management process for MT messages, it is recommended that you break the process down into three separate procedures: sending, polling the confirmation message queue, and polling the error message queue.


When sending IT messages, uniquely identify each message with an integer, and then send the message to the ICCMT.fifo queue. For example:

import boto3
import json
import uuid
# Get the service resource
sqs = boto3.resource('sqs')

# Get the queues
mt_queue = sqs.get_queue_by_name(QueueName = 'ICCMT.fifo')
message = "hello device".encode("utf-8").hex()

# Create a message
body = {
  "client_message_id": 123456789,
  "message": message,
  "imei": "432143214321432"

deduplication_id = str(uuid.uuid4())
group_id = str(uuid.uuid4())
  MessageBody = json.dumps(body),
  MessageGroupId = group_id,
  MessageDeduplicationId = deduplication_id

Polling the confirmation message queue

When polling the ICCMTConfirmation.fifo queue for confirmation messages, process each confirmation message and then delete it. For example:

# Get the service resource
sqs = boto3.resource('sqs') # Get the queues

mt_confirmation_queue = sqs.get_queue_by_name(QueueName='ICCMTConfirmation.fifo')

# Check the confirmation queue and, if no message found, check the error queue

for message in mt_confirmation_queue.receive_messages(WaitTimeSeconds=30):
  data = json.loads(message.body)

  # Status greater than zero indicates success
  if data['mt_message_status'] > 0:
    print("Message {0} is queued for delivery to IMEI {1} in position{2}".format(
    print("Message {0} was not sent to IMEI {0}".format(

# Let the queue know that the message is processed

Polling the error message queue

When polling the MTErrors.fifo queue for error messages, process each error message and then delete it. For example:

# Get the service resource
sqs = boto3.resource('sqs')

# Get the queues
mt_errors_queue = sqs.get_queue_by_name(QueueName='ICCMTErrors.fifo')

# Check the confirmation queue and, if no message found, check the errorqueue

for message in mt_errors_queue.receive_messages(WaitTimeSeconds=30):

# Let the queue know that the message is processed


Devices must be provisioned using Iridium SPNet or Iridium Web Services (IWS). The provisioning address format is address:port, which corresponds to the customer origin and destination.

Data format

When Iridium CloudConnect processes data from your device, it puts it in a JSON object that is exchanged between Amazon SQS and the Iridium gateway through Iridium CloudConnect. The JSON object contains information about the device, message payload, and header, in the following format:

    "api_version": 1,
    "data": {
        "mo_header": {
            "cdr_reference": 1179650258,
            "session_status_int": 0,
            "session_status": "No error.",
            "momsn": 58939,
            "mtmsn": 0,
            "imei": "300334010407160",
            "time_of_session": "2019-12-16 15:04:09"
        "location_information": {
            "cep_radius": 10,
            "latitude": "38.52137",
            "longitude": "-77.12970"
        "payload": "746573746d756963"
For more information about message specifications, see the Iridium Short Burst Data Service Developers Guide.

Mobile-originated message formatting

Mobile-originated messages will be translated into the following JSON format:

    "data": {
        "location_information": {
            "cep_radius": 2,
            "latitude": "33.20574",
            "longitude": "-111.50958"
        "mo_header": {
            "cdr_reference": 1519223194,
            "imei": "3000010XXXXXXXX",
            "mtmsn": 0,
            "momsn": 64588,
            "session_status": "sbd_session_successful",
            "time_of_session": "2019-01-25 22:11:07"
        "payload": "54657374696e67204d4f2054657874207769746820494343"
    "api_version": 1
For field details, see the following tables.
Top-level MO keys
Field Description


Contains the latitude, longitude, and certainty radius.


Contains metadata about the message including status and device ID.


Contains the message payload.


Notes the SBD API version. The SBD API version should always be 1.

Location information
Field Description Type


Contains the latitude of the device down to thousandths of a minute.

Floating point (thousandths of a minute)


Contains the longitude of the device down to thousandths of a minute.

Floating point (thousandths of a minute)


Provides an estimate of the Iridium Subscriber Unit’s (ISU’s) location accuracy.


MO header
Field Description Type


Call detail record, also known as auto ID. It’s a unique identifier for a given message in the Iridium gateway database.

10-digit number


International Mobile Equipment Identity (IMEI), a unique equipment identifier also known as device ID.

15-digit number


Mobile-terminated message sequence number (MTMSN) associated with the SBD session. This value is set by the Iridium gateway at the time that an MT message is queued for delivery. It is unique to each IMEI. It is then sent to the IMEI as part of the MT payload transfer.

If an MT payload transfer is attempted, the MTMSN is included in the header regardless session’s success. If the session fails, the payload still queues for delivery. If no MT delivery attempt is made in the session, this value is zero.

5- digit number


Mobile-originated message sequence number (MOMSN) associated with the SBD session. This value is set by the IMEI and transmitted to the Iridium gateway as part of every SBD session. It is incremented by the IMEI after every successful session.

5-digit number


An indication of success of the SBD session between the IMEI and the Iridium gateway associated with the over-the-air payload delivery.

String. (See the MO session status values table below.)


Provides a UTC timestamp of the IMEI session between the IMEI and the Iridium Gateway.


MO session status values
Status Description String


SBD session completed successfully.



MO message transfer, if any, was successful. The MT message queued at the Iridium gateway is too large to be transferred within a single SBD session.



MO message transfer, if any, was successful. The reported location is an unacceptable quality. This value is only applicable to IMEIs using SBD protocol revision 1.



SBD session timed out before session completed.



MO message transferred by the IMEI is too large to be transferred within a single SBD session.



RF link loss occurred during the SBD session.



IMEI protocol anomaly occurred during SBD session.



IMEI is prohibited from accessing the Iridium gateway.


Mobile-terminated message formatting

Use the following formatting to build mobile-terminated messages:

  • Mobile-terminated message JSON

  "client_message_id" : "TEST",
  "message" : "5465737420484558206d657373616765",
  "imei" : "300125010001100",
  "flush_mt_queue" : false,
  "send_ring_alert_no_payload" : false,
  "high_priority_message" : false,
  "assign_mtmsn" : false
  • Bare minimum

  "client_message_id" : 1234,
  "message" : "68656c6c6f20776f726c64",
  "imei" : "300234087352917"
  • With priority specified

  "client_message_id" : 9977331,
  "message" : "68656c6c6f20776f726c64",
  "imei" : "300234087352917",
  "priority" : 2
  • All possible options

  "client_message_id" : 789012,
  "message" : "68656c6c6f20776f726c64",
  "imei" : "300234087352917",
  "flush_mt_queue" : false,
  "send_ring_alert_no_payload" : false,
  "message_priority" : 3,
  "assign_mtmsn" : false
For more information about allowed combinations, see the Iridium Short Burst Data Service Developers Guide. For field details, see the following Top-level MT keys table.
Top-level MT keys
Field Description Type


Unique identifier for client messages.

Number or 4-character string


Payload of the MT message.



Unique equipment identifier of the device that receives an MT message.

15-digit number


When this flag is set to true, all payloads in the MT queue for the given IMEI are deleted. This provides an integrated method to administer MT queues.

When an MT message includes a payload, it is queued after the currently queued payloads, if any, are deleted. This enables the vendor application to maintain a queue depth of one, overwriting any previously queued payloads.

Boolean (true, false)


When this flag is set to true, the Iridium gateway sends an SBD ring alert to the specified IMEI, even though no new MT payload is queued.

Boolean (true, false)


Places the associated MT payload in the queue according to priority level.

Boolean (true, false)


When this flag is set to true, the Generic Security Standard (GSS) API uses the value in the Unique ID field in the message header as the MTMSN for the associated MT message payload.

Boolean (true, false)

MT confirmation message formatting

MT confirmation messages are presented in the following format:

  "mt_message_id": 1234512345,
  "unique_client_message_id": 1234,
  "imei": 123451234512345,
  "auto_id_reference": 5432154321,
  "mt_message_status": -2
For field details, see the following Keys and MT confirmation status values tables.
Field Description


Identifier of the message in the Iridium CloudConnect database.


Customer-supplied identifier for the message.


Unique equipment identifier of the device that will receive an MT message.


Unique identifier in the Iridium gateway database.


Number. (See MT confirmation status values table.)

MT confirmation status values
Status Description


Order in the MT message queue of the successfully received payload.


Message with a zero-byte payload received successfully (i.e., a mailbox check).


IMEI has too few characters, non-numeric characters.


Unknown IMEI – is not provisioned on the Iridium gateway.


Payload size exceeds the maximum allowed.


No payload received.


MT message queue is full (maximum of 50).


MT resources are unavailable.


Violation of MT DirectIP protocol error.


Ring alerts to the given IMEI are disabled.


IMEI is not attached (i.e., not set to receive ring alerts).


Source IP address was rejected by MT filter.


MTMSN value is out of range (valid range is 1–65,535).

For transceiver message sizes and other specifications, see the Iridium Short Burst Data Service Developers Guide.


For troubleshooting common Partner Solution issues, refer to the AWS Partner Solution General Information Guide and Troubleshooting CloudFormation.


Q. I already use DirectIP service to send and receive Iridium messages. How do I get access to Iridium CloudConnect?

A. Partners can explore Iridium CloudConnect regardless of their existing connection method to Iridium SBD. Contact your Iridium channel manager for a technical brief tailored to your specific configuration.

Q. How do I get started with an Iridium CloudConnect development environment?

A. Most Iridium customers set up two Iridium CloudConnect instances, one for their development environments and another for their production system. This aligns with the way Iridium customers traditionally set up DirectIP deployments. Also, you can route messages using your traditional method and through Iridium CloudConnect, and use comparative testing to verify Iridium CloudConnect operations and utility.

Q. What is the pricing for Iridium CloudConnect? Who pays for the AWS compute resources?

A. Iridium does not assess a charge for sending messages through Iridium CloudConnect instead of another method such as DirectIP. Iridium, however, prefers that customers use Iridium CloudConnect for development and production environments. As such, Iridium may direct customers away from using SMTP (e-mail) for message exchange to the SBD gateway for production environment activity.

Q. How do you ensure message ordering? Do you use Amazon SQS FIFO (First-In-First-Out)?.

A. Iridium processes messages from the SBD gateway in order of receipt but does not specifically use an AWS Lambda instance to do this. During the setup of Iridium CloudConnect, customers can choose FIFO or non-FIFO configurations. FIFO queues keep messages in order.

Customer responsibility

After you deploy a Partner Solution, confirm that your resources and services are updated and configured—including any required patches—to meet your security and other needs. For more information, refer to the Shared Responsibility Model.


To submit feature ideas and report bugs, use the Issues section of the GitHub repository for this Partner Solution. To submit code, refer to the Partner Solution Contributor’s Guide. To submit feedback on this deployment guide, use the following GitHub links:


This document is provided for informational purposes only. It represents current AWS product offerings and practices as of the date of issue of this document, which are subject to change without notice. Customers are responsible for making their own independent assessment of the information in this document and any use of AWS products or services, each of which is provided "as is" without warranty of any kind, whether expressed or implied. This document does not create any warranties, representations, contractual commitments, conditions, or assurances from AWS, its affiliates, suppliers, or licensors. The responsibilities and liabilities of AWS to its customers are controlled by AWS agreements, and this document is not part of, nor does it modify, any agreement between AWS and its customers.

The software included with this paper is licensed under the Apache License, version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at or in the accompanying "license" file. This code is distributed on an "as is" basis, without warranties or conditions of any kind, either expressed or implied. Refer to the License for specific language governing permissions and limitations.