LingoMO

Mobile Originated (MO) Messages coming from Devices into the platform.

The structured Message format comprises the following six top-level fields:

ID - Unique Identifier for each Message generated by the platform
Received At - Time the Message was first received from the Network (UTC)
Identity - Identifiers for this Thing in Cloudloop (e.g. Account, Subscriber, Device etc)
Header - Transport-specific meta-data about the Message transmission
- SBD - SBD specific meta-data (e.g. approximate location)
- Cellular - Cellular specific meta-data (e.g. msisdn)
- IMT - IMT specific meta-data (e.g. topic identifier)
Message - Raw Message payload sent from the Device in Bytes
Decoded - Interpreted Message payload (where possible)
- P6 - Messages originated from a Ground Control tracking Device (e.g. RockSTAR)
- IOT - "IoT Gateway" Message originating from RockREMOTE
- IOTFile - IoT file originating from RockREMOTE
- Ceefax - CDM Message originating from RockREMOTE
- IES - Message transmitted from an Iridium Edge Solar Device

Anatomy of a MO Message (SBD)

Below is an example SBD Message transmitted from a RockSTAR Devices; we'll break down each section and discuss in detail

{
  "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==",
  "p6": {
    "status": true,
    "error": [],
    "messages": [
      {
        "mo": {
          "encrypted": false,
          "alertStatus": false,
          "powerStatus": true,
          "watchStatus": false,
          "type": "MO_MESSAGE_AUTO_POSITION_REPORT",
          "position": {
            "standard": {
              "at": {
                "year": 2023,
                "month": 10,
                "day": 9,
                "hour": 9,
                "minute": 41,
                "second": 0
              },
              "timeDelta": 34860,
              "dayOfYear": 39,
              "latlng": {
                "latitude": 50.877669999999995,
                "longitude": -1.2520800000000065
              },
              "altitude": 20,
              "course": 0,
              "speed": 0.0,
              "navigationMode": "NAVIGATION_MODE_3D",
              "battery": 96,
              "pdop": 1.25,
              "temperature": 19
            }
          }
        }
      }
    ]
  }
}

1. Preamble

All Messages have the following two common fields

id - Unique Identifier for each Message generated by the platform
receivedAt - Time the Message was first received from the Network (UTC)

{
  "id": "c0eb3dd4-0ab5-41f2-8fbd-b71083161fba",
  "receivedAt": {
    "year": 2023,
    "month": 10,
    "day": 9,
    "hour": 9,
    "minute": 41,
    "second": 13
  }
}

2. Identity

During the data ingestion process, we "imbue" identity information onto the Message; providing hardware identifiers ( e.g. IMEI) as well as Cloudloop identifiers (e.g. Subscriber Id). This reduces the integration effort for Customers as they'll receive Messages with all the identifiers they'll need to identify the Message within their system; or for use with the Cloudloop API

identity
- accountId - Cloudloop Account Identifier (e.g. yJGjpPobLlmOdanVkPWAKYzNMgwVZkrR)
- subscriber - Object representing the Cloudloop Subscriber
  - id - Cloudloop Subscriber Identifier (e.g. XgwyNPpDmebJLWXmwgEoARqxMdZOVGva)
  - type - Type of Subscriber, either:
    - SUBSCRIBER_TYPE_UNKNOWN
    - SUBSCRIBER_TYPE_SBD
    - SUBSCRIBER_TYPE_TELEPHONY
    - SUBSCRIBER_TYPE_BGAN
    - SUBSCRIBER_TYPE_CERTUS
    - SUBSCRIBER_TYPE_CELLULAR
  - description - User-supplied value (pulled from Subscriber's Description field in Subscription Manager)
- sim - Object representing the Cloudloop SIM (where applicable)
  - id - Cloudloop SIM Identifier
  - type - Type of SIM
    - SIM_TYPE_UNKNOWN
    - SIM_TYPE_IRIDIUM_CERTUS
  - iccid - ICCID of SIM
  - imsi - IMSI of SIM
- hardware - Object representing the Cloudloop Hardware (where applicable)
  - id - Cloudloop Hardware Identifier (e.g. joGRxQrXpzkPJEglMOBydwYZbqmDagNA)
  - type - Type of Hardware
    - HARDWARE_TYPE_UNKNOWN - Default
    - HARDWARE_TYPE_TIGERSHARK - RockFLEET / YB3i
    - HARDWARE_TYPE_LEOPARD3 - RockSTAR / YB3
    - HARDWARE_TYPE_GRIFFIN - RockAIR
    - HARDWARE_TYPE_IRIDIUM_SBD - OEM SBD Module
  - imei - IMEI of Device transmitting
  - serial - Manufacturers serial number (where known) - e.g. RockSTAR 1234 >> 1234
- identifier - Primary Identifier used to determine the Message origin e.g. 300234065366010 [imei]
- thingId - Cloudloop Thing Identifier (e.g. DgXeoxwVPMyrdOBJeEGlqKRJLbajQkzZ)

{
  "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"
  }
}

3. Header

Transport-specific meta-data about the Message transmission.

sbd - Message has been transmitted via Iridium Short-Burst Data (SBD)
- imei - IMEI of Device that transmitted the Message (i.e. 300234065366010)
- cdrReference - Reference for the transmission in Iridium's billing system
- momsn - Mobile Originated (MO) Message Sequence Number for this transmission
- mtmsn - Mobile Terminated (MT) Message Sequence Number for this transmission
- sessionAt - Time of transmission (UTC)
- status - Status of the transmission (For info, as defined by Iridium)
  - SESSION_STATUS_OK
  - SESSION_STATUS_ERROR_MT_TOO_LARGE
  - SESSION_STATUS_ERROR_UNACCEPTABLE_QUALITY
  - SESSION_STATUS_ERROR_SESSION_TIMEOUT
  - SESSION_STATUS_ERROR_MO_TOO_LARGE
  - SESSION_STATUS_ERROR_RF_LINK_LOSS
  - SESSION_STATUS_ERROR_IMEI_ANOMALY
  - SESSION_STATUS_ERROR_IMEI_PROHIBITED
- location - (Very) Approximate Location of Device
  - latitude
  - longitude
  - cep - Circular Error Probable - in KM
cellular - Message has been transmitted via Cellular
- mcn - MCN of Cellular Network (if known)
- mcc - MCC of Cellular Network (if known)
- msisdn - MSISDN of SIM (if known)
- imei - IMEI of Device transmitting
imt - Message has been transmitted via Iridium Message Transport (IMT)
- cmid - Identifier for Device (derived from SIM) (e.g. 9771000172669)
- topicId - IMT Topic Identifier (e.g. 125)
- messageId - Unique identifier for message generated by Iridium
- crcError - If there was a Cyclic Redundancy Check error - true/false
- size - Size of Message transmission in Bytes

4. Message

The most important part - the raw bytes as transmitted from the Device!

{
  "message": "JgBreyuiF+0IgswAAAQBR2QnBQ=="
}

message - Base64 encoded Message payload (e.g. JgBreyuiF+0IgswAAAQBR2QnBQ==)

Drum and Base!

Base64 is ubiquitously used to represent "data" - it's a compact and effective method of communication across various transports. The 64 in Base64 denotes the number of "letters" in the "alphabet" used to convert the binary Message into something to show on the screen - the more letters available the shorter the representation.

Binary (aka 0's and 1's) it is also known as Base2 - has an alphabet of 2
Hexadecimal (aka Base16) has an alphabet of 16 (0-9; A-F)
Base64 has an alphabet of 64 (0-9; A-Z; a-z)

Example:

Message - Hello World [11 bytes]
**Binary (Base2) ** - 01001000 01100101 01101100 01101100 01101111 00100000 01010111 01101111 01110010 01101100 01100100
Hex (Base16) - 48 65 6c 6c 6f 20 57 6f 72 6c 64
Base64 - SGVsbG8gV29ybGQ=

Important! This is just the representation, the above examples are all 11 bytes; encoding it's not a magical form of data compression it does not change the message being sent on-the-wire; or indeed over-the-air!

5. Decoded

**Where Message comes from a Device that we're able to interpret (i.e. Decode) - one of the following will be populated. **

p6 - GC Tracking Devices (e.g. RockSTAR)
iot - IoT Gateway
iotFile - IoT File
ceefax - RockREMOTE CDM
ies - Iridium Edge Solar

The full details of these protocols are extensive; for example P6 encompasses all Messages the Device can send and receive (~100 Message types); therefore more comprehensive documentation for each protocol can be found using the links above.

{
  "p6": {
    "status": true,
    "error": [],
    "messages": [
      {
        "mo": {
          "encrypted": false,
          "alertStatus": false,
          "powerStatus": true,
          "watchStatus": false,
          "type": "MO_MESSAGE_AUTO_POSITION_REPORT",
          "position": {
            "standard": {
              "at": {
                "year": 2023,
                "month": 10,
                "day": 9,
                "hour": 9,
                "minute": 41,
                "second": 0
              },
              "timeDelta": 34860,
              "dayOfYear": 39,
              "latlng": {
                "latitude": 50.877669999999995,
                "longitude": -1.2520800000000065
              },
              "altitude": 20,
              "course": 0,
              "speed": 0.0,
              "navigationMode": "NAVIGATION_MODE_3D",
              "battery": 96,
              "pdop": 1.25,
              "temperature": 19
            }
          }
        }
      }
    ]
  }
}

Example showing a "Routine" position report from the Device; key information such as latitude and longitude is clearly visible.

xyz

LingoMO

Anatomy of a MO Message (SBD)​

1. Preamble​

2. Identity​

3. Header​

4. Message​

5. Decoded​