Iridium CloudConnect for SBD on the AWS Cloud • Apollo Satellite

Iridium CloudConnect is a satellite cloud-based adapter service that transfers SBD messages from Iridium-based devices to the AWS Cloud.

This Quick Start deploys Iridium CloudConnect into your existing AWS infrastructure. Using Amazon SQS, this deployment establishes the standard architecture to get SBD messages from devices on the Iridium network into queues stored on your AWS virtual private cloud (VPC).

Cost #

You are responsible for the cost of the AWS services used while running this Quick Start. There is no additional cost for using the Quick Start.

The AWS CloudFormation templates for Quick Starts include configuration parameters that you can customize. Some of the settings, such as the instance type, affect the cost of deployment. For cost estimates, see the pricing pages for each AWS service you use. Prices are subject to change.

Software Licenses #

No software licenses are necessary. 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.

Architecture #

Deploying this Quick Start with default parameters builds the following Iridium CloudConnect environment in the AWS Cloud.

Iridium CloudConnect

As shown in the figure just above, the Quick Start deploys the following in your existing AWS virtual private cloud (VPC):

Amazon SQS to provide a highly available queing 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.

Planning the deployment #

Specialized Knowledge #

This deployment requires a moderate level of familiarity with AWS services. If you’re new to AWS, visit Getting Started with AWS and Training and Certification. These sites provide materials for learning how to design, deploy, and operate your infrastructure and applications on the AWS Cloud.

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

AWS Account #

If you don’t already have an AWS account, create one at https://aws.amazon.com by following the on-screen instructions. Part of the sign-up process involves receiving a phone call and entering a PIN using the phone keypad.

Your AWS account is automatically signed up for all AWS services. You are charged only for the services you use.

Technical Requirements #

Before you launch the Quick Start, your account must be configured as specified in the following table. Otherwise, deployment might fail.

Resource Quotas #

If necessary, request service quota increases for the following resources. You might request quota increases to avoid exceeding the default limits for any resources that are shared across multiple deployments. The Service Quotas console displays your usage and quotas for some aspects of some services. For more information, see What is Service Quotas? and AWS service quotas.

Resource	This deployment uses
AWS Identity and Access Management (IAM) roles	1
Amazon SQS queues	4

Supported Regions #

This Quick Start is supported in all available Regions. Certain Regions are available on an opt-in basis. See Managing AWS Regions.

IAM Permissions #

Before launching the Quick Start, you must sign in to the AWS Management Console with IAM permissions for the resources that the templates deploy. The AdministratorAccess managed policy within IAM provides sufficient permissions, although your organization may choose to use a custom policy with more restrictions. For more information, see AWS managed policies for job functions.

Iridium Partner or Customer #

If you are not already an Iridium partner or customer, navigate to Apollo 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 Options #

This Quick Start provides a single deployment option:

Deploy Iridium CloudConnect into your AWS account. This option deploys Iridium CloudConnect into your existing AWS infrastructure.

Deployment Steps #

– Each deployment takes about 10 minutes to complete.

Sign in to your AWS account #

Sign in to your AWS account at https://aws.amazon.com with an IAM user role that has the necessary permissions. For details, see “Planning the Deployment” earlier in this guide.
Ensure that your AWS account is configured correctly, as discussed in the “Technical Requirements” section.

Launch the Quick Start #

You are responsible for the cost of the AWS services used while running this Quick Start reference deployment. There is no additional cost for using this Quick Start. For more information, see the pricing pages for each AWS service used by this Quick Start. Prices are subject to change.

Sign in to your AWS account.
Choose the link provided (Deploy Iridium CloudConnect into your AWS account) to launch the AWS CloudFormation template.

Deploy Iridium CloudConnect into your AWS account.

View template

The AWS Region that’s displayed in the upper-right corner of the navigation bar is where the network infrastructure for Iridium CloudConnect is built. The template is deployed in the us-east-1 Region by default. Change it if necessary.

On the Create stack page, keep the default setting for the template URL, and then choose Next.
On the Specify stack details page, change the stack name if needed. Review the template parameters and provide values for any parameters that require input. For more information, see the Parameter Reference section, later in this guide.

On the Configure stack options page, you can specify tags (key-value pairs) for resources in your stack and set advanced options. When you’re finished, choose Next.
On the Review page, review and confirm the template settings. Under Capabilities, select the two check boxes to acknowledge that the template creates IAM resources and might require the ability to automatically expand macros.
Choose Create stack to deploy the stack.
Monitor the status of the stack. When the status is CREATE_COMPLETE, the Iridium CloudConnect deployment is ready.
Use the values displayed in the Outputs tab for the stack, as shown in the image just below to view the created resources.

Iridium CloudConnect

Interacting With Your Amazon SQS Queues #

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

Via the command line, using the AWS Command Line Interface (AWS CLI).
Manually, by navigating to Amazon SQS queues in the AWS Management Console.
Programmatically, with many libraries available, such as:

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(
        header['imei'],
      location['latitude_longitude'] ))

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

# Let the queue know that the message is processed
message.delete()

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.

Sending #

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())
mt_queue.send_message(
  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(
      data['unique_client_message_id'],
      data['imei'],
      data['mt_message_status']))
  else:
    print("Message {0} was not sent to IMEI {0}".format(
      data['unique_client_message_id'],
      data['imei']))

# Let the queue know that the message is processed
message.delete()

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):
  print(message.body)

# Let the queue know that the message is processed
message.delete()

Provisioning #

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
location_information	Contains the latitude, longitude, and certainty radius.
mo_header	Contains metadata about the message including status and device ID.
payload	Contains the message payload.
api_version	Notes the SBD API version. The SBD API version should always be 1.

Location information #

Field	Description	Type
latitude	Contains the latitude of the device down to thousandths of a minute.	Floating point (thousandths of a minute)
longitude	Contains the longitude of the device down to thousandths of a minute.	Floating point (thousandths of a minute)
cep_radius	Provides an estimate of the Iridium Subscriber Unit’s (ISU’s) location accuracy.	Integer

MO header #

Field	Description	Type
cdr_reference	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
imei	International Mobile Equipment Identity (IMEI), a unique equipment identifier also known as device ID.	15-digit number
mtmsn	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.	Integer
momsn	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
session_status	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.)
time_of_session	Provides a UTC timestamp of the IMEI session between the IMEI and the Iridium Gateway.	Timestamp

MO session status values #

Status	Description	String
0	SBD session completed successfully.	sbd_session_successful
1	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.	mt_message_too_large
2	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.	unacceptable_quality
10	SBD session timed out before session completed.	session_timeout
12	MO message transferred by the IMEI is too large to be transferred within a single SBD session.	mo_message_too_large
13	RF link loss occurred during the SBD session.	rf_link_loss
14	IMEI protocol anomaly occurred during SBD session.	imei_anomaly
15	IMEI is prohibited from accessing the Iridium gateway.	imei_prohibited

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
}

Top-level MT keys #

Field	Description	Type
client_message_id	Unique identifier for client messages.	Number or 4-character string
message	Payload of the MT message.	String
imei	Unique equipment identifier of the device that receives an MT message.	15-digit number
flush_mt_queue	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)
send_ring_alert_no_payload	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)
high_priority_message	Places the associated MT payload in the queue according to priority level.	Boolean (true, false)
assign_mtmsn	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.

Keys #

Field	Description
mt_message_id	Identifier of the message in the Iridium CloudConnect database.
unique_client_message_id	Customer-supplied identifier for the message.
imei	Unique equipment identifier of the device that will receive an MT message.
auto_id_reference	Unique identifier in the Iridium gateway database.
mt_message_status	Number. (See MT confirmation status values table.)

MT confirmation status values #

Status	Description
1–50	Order in the MT message queue of the successfully received payload.
0	Message with a zero-byte payload received successfully (i.e., a mailbox check).
-1	IMEI has too few characters, non-numeric characters.
-2	Unknown IMEI – is not provisioned on the Iridium gateway.
-3	Payload size exceeds the maximum allowed.
-4	No payload received.
-5	MT message queue is full (maximum of 50).
-6	MT resources are unavailable.
-7	Violation of MT DirectIP protocol error.
-8	Ring alerts to the given IMEI are disabled.
-9	IMEI is not attached (i.e., not set to receive ring alerts).
-10	Source IP address was rejected by MT filter.
-11	MTMSN value is out of range (valid range is 1–65,535).

Account