APIs DMO API Work with satellite metrics

This tutorial will show you how to work with Satellite metrics using the DMO API. You’ll learn the basic CRUD (Create, Read, Update, Delete) operations and how to view your Satellite terminal and Satellite metrics.

Supported satellite metrics

The following metrics are supported for a specific terminal, given that the provider provides this data:

Resource Name (rn)Metric Unit (metUt)Metric TypeDescription
Network_StatusNumericoperationalStateThe operational state of the connection: 0 – unknown 1 – online 2 – offline 3 – offline and upgrading 4 – offline failed 5 – offline reason unknown 6 – online degraded
Throughput_UpBytesusAllocatedBwBytesUpstream bandwidth allocated, in bytes
Throughput_DownBytesdsAllocatedBwBytesDownstream bandwidth allocated, in bytes
Bandwidth_CIR_UplinkMbpsusCirCurrentUpstream Committed Information Rate (CIR) currently in effect
Bandwidth_CIR_DownlinkMbpsdsCirCurrentDownstream Committed Information Rate (CIR) currently in effect
Bandwidth_MIR_UplinkKbpsusMirDemandUpstream Maximum Information Rate (MIR) bandwidth requested by the subscriber, in Kbps
Bandwidth_MIR_DownlinkKbpsdsMirDemandDownstream Maximum Information Rate (MIR) bandwidth requested by the subscriber, in Kbps
LatencyMillisecondslatencyRound-trip time between the NMS and a terminal
Congestion_UpstreamPercentageusCirFulfillmentPercentage of upstream frames in which the allocation met the Committed Information Rate (CIR) demand
Congestion_DownstreamPercentagedsCirFulfillmentPercentage of downstream allocation periods (10/second) in which the allocation met the CIR demand
JitterMillisecondsjitterAmount of variation experienced in the latency measuremen
Packet_LossPercentagepacketlossPercent of echo requests sent to a terminal for which there was no response
Signal_StrengthdBcurrentSNRCurrent signal-to-noise ratio (SNR) as reported by the remote
LatitudeDecimallatitudeTerminal latitude
LongitudeDecimallongitudeTerminal longitude
AltitudeMetersaltitudeTerminal altitude

You will learn how to

  • Retrieve a satellite terminal
  • Retrieve a satellite terminal and its metrics
  • Retrieve a single satellite metric

Prerequisites

Before you begin, make sure you have completed the first tutorial, “Connecting your application to the T IoT Hub” and the connectivity groups tutorial, “Work with connectivity groups”.

Make sure that you:

  1. Register your application in Application Access Management
  2. Configure a request to fetch the API access token
  3. Register an Application Entity (AE) in your environment.
  4. Have an HTTP client available on your machine, such as cURL .
  5. Create a connectivity group.
NOTE
  • This tutorial assumes you are using cURL. If you are using a different HTTP client, the setup may be different.

Step 1. Retrieve a satellite object resource name assigned to your group

In order to get the resource name of a satellite assigned to your connectivity group you can refer to Step 5. Retrieve your connectivity group (Read) .

  • Copy & paste
  • Output
curl --location 'https://api.telekom.de/t-iot-hub/device-management-orchestrator/v3/$TENANT/connectivityGroups/<your_group_name>' \
  --header 'Content-Type: application/json' \
  --header 'X-M2M-Origin: <your_application_name>' \
  --header 'X-M2M-RI: 123' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

{
  "dtiot:conGp": {
    "cnd": "com.telekom.iot.orchestrator.connectivityGroup",
    "conPs": [
      {
        "coPID": "<your_product_id_number>",
        "coPTe": 1,
        "netID": "<your_network_id_number>"
      }
    ],
    "liCRr": "<your_router_serial_number>",
    "priRe": {
      "prPID": "<your_priority_product_id_number>",
      "faPID": "<your_fallback_product_id_number>",
      "priTd": 6
    },
    "updTe": 3,
    "errMe": "command is required.",
    "rn": "connectivityGroup_1",
    "ty": 28,
    "cr": "CPDemo",
    "st": 1,
    "ri": "64a816836e874776979410ba",
    "pi": "64a580864238880cfd551557",
    "ct": "20230707T134331,108000",
    "lt": "20230707T134332,308000"
  }
}
NOTE
  • Make sure that the coPTe attribute, Connectivity type, is 1, which stands for the satellite product type.

The value of the <your_network_id_number> field is the resource name for a satellite terminal to use in the next steps.

Step 2. Retrieve a satellite object assigned to your group

Now, with the terminal resource name retrieved you can retrieve the object itself.

  • Copy & paste
  • Output
curl --location 'https://api.telekom.de/t-iot-hub/device-management-orchestrator/v3/$TENANT/satelliteTerminal/<your_network_id_number>' \
  --header 'Content-Type: application/json' \
  --header 'X-M2M-Origin: <your_application_name>' \
  --header 'X-M2M-RI: 123' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

{
  "rn": "<your_network_id_number>",
  "cnd": "com.telekom.iot.orchestrator.satelliteTerminal",
  "serNr": "<your_network_id_number>",
  "netNt": "<network_name>",
  "satNe": "<satellite_name>",
  "satBm": "<satellite_beam>",
  "satOr": "<satellite_originator>",
  "terTe": "<terminal_type>",
  "terMl": "<terminal_model>",
  "liCGp": "<connectivity_group_resource_id>",
  "ty": 28,
  "cr": "CConnGroupAE",
  "st": 2,
  "ri": "64b10160423888a508554bc8",
  "pi": "<your_tenant>",
  "ct": "20230714T080344,322000",
  "lt": "20230714T080412,029000",
}

Step 3. Retrieve a satellite object with satellite metrics (Read)

Satellite metrics are objects created under the parent satellite object. Metrics objects are created for each supported metric, and each of these objects contains the most recently received value. Please note that the value processing is asynchronous and is initiated by the satellite operator, so when new data is available, it is processed by the IT Hub. This means that the data update rate depends on the external system of the satellite operator.

NOTE
  • This request is almost exactly the same as in the previous step with one important addition - the rcn query parameter that defines the output. rcn=4 returns attributes and child resources found, and rcn=8 returns child resources found. The following example uses the rcn=4 parameter.
  • Copy & paste
  • Output
curl --location 'https://api.telekom.de/t-iot-hub/device-management-orchestrator/v3/$TENANT/satelliteTerminal/<your_network_id_number>?rcn=4' \
  --header 'Content-Type: application/json' \
  --header 'X-M2M-Origin: <your_application_name>' \
  --header 'X-M2M-RI: 123' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

{
  "rn": "<your_network_id_number>",
  "cnd": "com.telekom.iot.orchestrator.satelliteTerminal",
  "serNr": "<your_network_id_number>",
  "netNt": "<network_name>",
  "satNe": "<satellite_name>",
  "satBm": "<satellite_beam>",
  "satOr": "<satellite_originator>",
  "terTe": "<terminal_type>",
  "terMl": "<terminal_model>",
  "liCGp": "<connectivity_group_resource_id>",
  "ty": 28,
  "cr": "CConnGroupAE",
  "st": 2,
  "ri": "64b10160423888a508554bc8",
  "pi": "<your_tenant>",
  "ct": "20230714T080344,322000",
  "lt": "20230714T080412,029000",
  "dtiot:sitRe": [
    {
        "cnd": "com.telekom.iot.orchestrator.satelliteMetrics",
        "rn": "<metric_resource_name>",
        "metTe": "<metric_type>",
        "metUt": "<metric_unit>",
        "metVe": "<metric_value_stringified>",
        "dgt": "20230713T131037,000868",
        "ty": 28,
        "cr": "CINTELSAT_IPE",
        "st": 1,
        "ri": "<metric_resource_id>",
        "pi": "<your_network_id_number>",
        "ct": "20230714T080359,556000",
        "lt": "20230714T080403,408000"
    }
  ]
}
NOTE
  • The dgt parameter represents the latests update for a metric.

Step 4. Retrieve a satellite metric (Read)

To retrieve a specific metric you can use the following cURL command with your values for <your_network_id_number> and <metric_resource_name> fields.

  • Copy & paste
  • Output
curl --location 'https://api.telekom.de/t-iot-hub/device-management-orchestrator/v3/$TENANT/satelliteTerminal/<your_network_id_number>/`<metric_resource_name>`' \
  --header 'Content-Type: application/json' \
  --header 'X-M2M-Origin: <your_application_name>' \
  --header 'X-M2M-RI: 123' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $ACCESS_TOKEN'

{
    "cnd": "com.telekom.iot.orchestrator.satelliteMetrics",
    "rn": "<metric_resource_name>",
    "metTe": "<metric_type>",
    "metUt": "<metric_unit>",
    "metVe": "<metric_value_stringified>",
    "dgt": "20230713T131037,000868",
    "ty": 28,
    "cr": "CINTELSAT_IPE",
    "st": 1,
    "ri": "<metric_resource_id>",
    "pi": "<your_network_id_number>",
    "ct": "20230714T080359,556000",
    "lt": "20230714T080403,408000"
}