Version: 1.5 Mar 27, 2024

Purpose

Skylo Connect APIs provides a interface for cloud applications to exchange data with UE onto Skylo Network.

Non-IP Data Delivery (NIDD) provides a path to exchange data between user equipment (UE) and Cloud Applications without the UE requiring to support an IP Stack. This document describes the communication mechanism between Customer Application Services and Skylo’s Data Mobility Platform (DMP) through Skylo Connect APIs, which are REST APIs (HTTP/JSON) to send and receive data over satellite securely

Overview

This document describes the communication mechanism between Customer Application Services and Skylo’s Data Mobility Platform(DMP) though Skylo Connect APIs, which are REST APIs (HTTP/JSON) to securely send and receive data over satellite. It covers the following procedures and apis:

• NIDD downstream data delivery over satellite and DL Data delivery status notifications
• NIDD Uplink Data Notification
• UE Network Connection status with Satellite Network

Cloud Applications can use these APIs to enhance their capabilities for satellite connectivity.

API Access

Each application will be provided a unique app-id and secret key to securely access the Skylo Connect APIs

These values shall be used in HTTP headers as shown below:

• APP-ID: <app-id string>
• APIKEY: <secret-key>

Register Notifications

This API’s purpose is to register Notification Destination Address on which application would like to receive notification events from Skylo Platform.

Application shall perform registration to receive the following notifications:

• NIDD Uplink Data Notification
• NIDD Downlink Data Delivery Status Notification
• UE Network Event Notification

Application receive and process HTTP messages for all notifications and content of such messages is encoded in JSON format. Application to ensure not to perform heavy processing in callbacks and shall return success response within 500ms

DMP will post notifications to the registered endpoint with the header APIKEY and value received in the  appSecretKey field.

Each of callback notification to registered endpoint will carry following HTTP header:

• APP-ID: <app-id string>
• APIKEY: <it contains the value  as passed by customer in registration notification api in field appSecretKey>

API

To register

Request: Sample Message

‍

Response: 201 Created

‍

Response: Failure case

Downlink Data Delivery

This section illustrate the procedure Application uses to send Non-IP Data to a given user as identified using the External Identifier

If Application has already activated the NIDD service for a given UE, and has downlink non-IP data to send to the UE, the Application sends an NIDD Submit Request containing the External Identifier and the non-IP data message to the Skylo Platform.

Procedure

DL Data Delivery (Submit Request)

This api is to send downstream data to UE over satellite.

• api will return unique dlMessageId if request is submitted successfully
• Skylo Platform will form SMP data(byte optimized data) based on information available in request body
• Skylo platform maintains association between app-id, dlMessgaeId and ueExternalIdentifier that will help DMP to route DL notification from Satellite Network to destination app-id
• Skylo platform send delivery status notifications with the same dlMessageId  for application to establish correlation with original DL messages
• Skylo platform imposing some limitation on DL traffic as per guideline mention in Appendix A: Inbound Policing for DL Messages. Api will be rejected when it exceed rate limit or/an UE is not reachable

API - SMP

Request: Sample Message:

Response: HTTP 202 Accepted

It return DL message id and transmitted size in bytes. size is SMP encoded data that is transmitted to the Satellite network.

Response: Failure case

Response: In case of request api validation failed, it send 400 bad request

API - Non SMP

Request: Sample Message

Response: HTTP 202 Accepted

It return DL message id and transmitted size in bytes, size is same as size of contentData in request message

DL Data Delivery Notification

The downlink data messages that are buffered by core network are either retransmitted or they expire sitting in the delivery queue. In either case, a Downlink Data Delivery Status notification is generated by Skylo Platform and sent to the Application on Notification Destination Address provided at the time of  register notification api for event: DL_DATA_DELIVERY_STATUS_NOTIFICATION. The status notification may contain one of these codes:

• FAILURE: When the retransmission attempt failed or the data lifetime expired
• SUCCESS: When the data message could successfully be delivered to the UE. The Skylo Platform includes the Downlink Data Delivery ID(dlMessageId ) of the data message in the notification for the Application to identify the same
• Cloud platform expect 200 OK for all callback urls

Request: Sample Message (success delivery)

Header will contains

• APP-ID: <app-id string>
• APIKEY: <it contains the value  as passed by customer in registration notification api in field appSecretKey>

Body

Request: Sample Message (failure delivery)

Guideline for handling Error code 1021 Application

Data Mobility Platform maintains DL transaction for each UE and restricts next DL transaction if existing transaction is still in process.

It is recommended that Cloud application shall restrict sending of DL transaction if an existing transaction is still in-progress. Connect API will return failure if Application submit another DL message while previous DL transaction is still in-progress.

API:  /connect-api/nidd/dl-data-delivery

API:  /connect-api/nidd/dl-data-delivery/smp

Failure Response while previous transaction is still in-progress

It is recommend that Cloud Application shall wait for 2 mins or more (configurable) for DL delivery status notification and avoid sending DL submit api by following the below workflow.

Uplink Data Notification

This illustrate procedure Skylo platform uses to send non-IP uplink data to Application

When Skylo Platform receives the non-IP data from core network, it sends the non-IP data to the Application using the Notification Destination Address provided by the Application at the time of register notification api for event: UL_DATA_NOTIFICATION.

• Skylo Platform parse SMP data(byte optimized data) received from core network and prepare json data that is passed in “nidd_data” field

Request: Sample Message

Header will conatins

• APP-ID: <app-id string>
• APIKEY: <it contains the value  as passed by customer in registration notification api in field appSecretKey>

Body

Note :

• Json Object “smpHeader" will be available when app-id is using SMP protocol. for non-SMP data, this field will not be present.
• "dataSizeInbytes":  It is the data size in bytes that is received from the satellite network

Sample for SMP Data

Sample for Non-SMP Data

Canceling of Existing Transaction

This api is to cancel existing downlink data transaction

API

Request: Body :

Response: HTTP 202 Accepted

UE Network Status Notification

Skylo platform will generate this notification whenever change in UE status is observed. Notification is sent to the Application using the Notification Destination Address provided by the Application at the time of register notification api for event: UE_NETWORK_STATUS_NOTIFICATION

Request: Sample Message

Header will contains

• APP-ID: <app-id string>
• APIKEY: <it contains the value  as passed by customer in registration notification api in field appSecretKey>

Body

Fetch UE Network Status

This API is to fetch UE network status

API

Request: Body : None

Response: HTTP 200 OK

UE Subscribe [Deprecated]

This api is to subscribe for UE notification(data and network status)

API

Request: Body :

Response: HTTP 200 OK

‍

UE De-Subscribe [Deprecated]

This api is to de-subscribe for UE notification(data and network status)

API

Request: Body :

Response: HTTP 200 OK

‍

API Error Reporting

Error Codes:

Skylo Platform generate error responses when HTTP Requests fails to get processed successfully. Platform insert error causes whenever possible for easy of debugging

Error Body

Various Objects for SMP Protocol

Content Types

ContentTextMessage

‍

ContentLocation

gpsFix: 0 or 1

ContentTextMessageAndLocation

• content: hexstring

ContentDeliveryReceipt

ContentReadReceipt

• readTimestamp: Read time stamp should be in epoch format. It represents the time when user read the message.

‍

ContentSendReceipt

• receiptType: If we need to send receipts over satellite, we can use this content type. For now, this receipt is limited to read status
  • value: 1 (Read)

ContentUndeliveredReceipt

readonCode: Reason code can be application specific. Sample reason codes given below.

• 01 - User blocked sender
• 02 - User not accepting any messages
• 03 - Timed out

ContentOpenSOS

sosReason: SOS reason code can be application specific. Set to 0x00, for generic SOS. This can be extended for different codes, which will be application specific. Sample reason codes given below.

• 01 - Fire Alert
• 02 - No fuel
• 03 - Safety
• 04 - Medical etc.

ContentCloseSOS

This content type has no payload

ContentCheckIn

• userId: Optional field for recipient id. Set Default to 000000, to use pre-configured user id.
• content: hexstring

ContentPredefinedMessage

messageCode: An application specific short codes to convey the messages with less network costs.

• 01 - I am Okay
  02 - Call me back

ContentOther

If the application has a specific requirement of message type, which doesn’t fit into any of  predefined content types then Application owner can use this type to customize the message content according to their needs.

ContentNetworkAck

• messageType: Message type of the source message, which requested for confirmation.
• timestamp: Source message timestamp from source SMP header
• messagecounter: Source message counter from source SMP header

ContentHeartbeat

• timestamp: time that data was collected
• gpsFix: 0 or 1 (1 indicates gps data is valid)

ContentTextMessageAndOpenSOS

• content: hex string

ContentUpdateImsi

• userId: mobile number with country code
• imsi: New IMSI from the SIM card

SMP Header Object

Message Id Generation

Format: Sender ID - SMP-Timestamp - SMP Message Counter
Bytes    : 6 + 1 + 4 + 1 + 2
Sample Message ID: ABCDEABCDE-FFFFFFFF-AAAA

Example

• Sender User ID : 919999999999, Time stamp: 1657127077 (2022-Jul-6, 17:04:37 GMT), Message Counter : 120,
  • Sender ID: 919999999999 ==> 0x00D63445EFFF
  • Time stamp: 1657127077 ==> 0x62C5C0A5
  • Message Counter: 120 ==> 0x0078
  • Hiphen/Minus : 45 ==> 0x2D
  • Message ID: 0x00D63445EFFF 2D 62C5C0A5 2D 0078

Appendix A: Inbound Policing for DL Messages

Skylo Network imposes DL inbound policing to protect the network from unwanted traffic and reject the downlink submit request if it does not meet the inbound policing.

Network applies following inbound policing for UE

• All inbound traffic for each UE is rate limited to 20 messages per minute.
• DL submit request will be rejected if existing Downlink transaction is still in-progress
• DL submit request will be rejected when UE is not reachable
• DL submit request will be rejected when UE is not activated for an APN
• SOS traffic will follow a different rate limit than the normal messages. it has much higher rate limit than the normal text messages

Inbound policing is applied for following DL Submit Apis

API returns the following error response  for all DL submit request

A Few Recommendations for Applications handling failed DL messages

Appendix B : Connect Apis Regional Endpoints

Europe Region: Endpoints

Registration Notification Apis

https://api-connect.ntnyolks.space/connect-api/nidd/register-notifications

Fetch UE Network State Apis

https://api-connect.ntnyolks.space/connect-api/nidd/ue-network-state/{ueExternalIdentifier}

NON_SMP: DL Data Delivery Request Api

https://api-connect.ntnyolks.space/connect-api/nidd/dl-data-delivery

SMP: DL Data Delivery Request Api

https://api-connect.ntnyolks.space//connect-api/nidd/dl-data-delivery/smp

Cancel DL Data Delivery Request Api

https://api-connect.ntnyolks.space/connect-api/nidd/dl-data-delivery/cancel

‍

US Region: Endpoints

Registration Notification Apis

https://api-connect.us.ntnyolks.space/connect-api/us/nidd/register-notifications

Fetch UE Network State Apis

https://api-connect.us.ntnyolks.space/connect-api/us/nidd/ue-network-state/{ueExternalIdentifier}

NON_SMP: DL Data Delivery Request Api

https://api-connect.us.ntnyolks.space/connect-api/us/nidd/dl-data-delivery

SMP: DL Data Delivery Request Api

https://api-connect.us.ntnyolks.space/connect-api/us/nidd/dl-data-delivery/smp

Cancel DL Data Delivery Request Api

https://api-connect.us.ntnyolks.space/connect-api/us/nidd/dl-data-delivery/cancel

‍

Amendment History

END