Provide custom ephemeris data - AWS Ground Station
OverviewOEM ephemeris formatExample OEM ephemeris in KVN formatCreating a custom ephemerisExample: Create a two-line element (TLE) set ephemeris via APIExample: Uploading Ephemeris data from an S3 bucketExample: Using customer-provided ephemerides with AWS Ground Station

Provide custom ephemeris data

Important

The ephemeris API is currently in a Preview state

Access to the Ephemeris API is provided only on an as-needed basis. If you require the ability to upload custom ephemeris data, you should contact . AWS Ground Station treats ephemerides as Individualized Usage Data. If you use this optional feature, AWS will use your ephemeris data to provide troubleshooting support.

Overview

The Ephemeris API allows custom ephemerides to be uploaded to AWS Ground Station for use with a satellite. These ephemerides override the default ephemerides from Space-Track (see: Default ephemeris data). We support receiving ephemeris data in Orbit Ephemeris Message (OEM), and two-line element (TLE) formats.

Uploading custom ephemerides can improve the quality of tracking, handle early operations where no Space-Track ephemerides are available to AWS Ground Station, and account for maneuvers.

Note

When providing custom ephemeris before a satellite catalog number is assigned for your satellite, you can use 00000 for the satellite catalog number field of the TLE, and 000 for the launch number portion of the international designator field of the TLE or OEM metadata (e.g. 24000A for a vehicle launched in 2024).

For more information about the format of TLEs, see Two-line element set. For more information about the format of OEMs, see OEM ephemeris format.

OEM ephemeris format

AWS Ground Station processes OEM Customer Provided Ephemerides according to the CCSDS standard with some extra restrictions. OEM files should be in KVN format. The following table outlines the different fields in an OEM and how AWS Ground Station differs from the CCSDS standard.

Section Field CCSDS required AWS Ground Station required Notes
Header CCSDS_OEM_VERS Yes Yes Required value: 2.0
COMMENT No No
CLASSIFICATION No No
CREATION_DATE Yes Yes
ORIGINATOR Yes Yes
MESSAGE_ID No No
Metadata META_START Yes Yes
COMMENT No No
OBJECT_NAME Yes Yes
OBJECT_ID Yes Yes
CENTER_NAME Yes Yes Required value: Earth
REF_FRAME Yes Yes Accepted values: EME2000, ITRF2000
REF_FRAME_EPOCH No Not supported* Not needed because the accepted REF_FRAMEs have an implicit epoch
TIME_SYSTEM Yes Yes Required value: UTC
START_TIME Yes Yes
USEABLE_START_TIME No No
USEABLE_STOP_TIME No No
STOP_TIME Yes Yes
INTERPOLATION No Yes Required so AWS Ground Station can generate accurate pointing angles for contacts.
INTERPOLATION_DEGREES No Yes Required so AWS Ground Station can generate accurate pointing angles for contacts.
META_STOP Yes Yes
Data X Yes Yes Represented in km
Y Yes Yes Represented in km
Z Yes Yes Represented in km
X_DOT Yes Yes Represented in km/s
Y_DOT Yes Yes Represented in km/s
Z_DOT Yes Yes Represented in km/s
X_DDOT No No Represented in km/s^2
Y_DDOT No No Represented in km/s^2
Z_DDOT No No Represented in km/s^2
Covariance matrix COVARIANCE_START No No
EPOCH No No
COV_REF_FRAME No No
COVARIANCE_STOP No No

* If any rows that aren't supported by AWS Ground Station are included in the provided OEM, the OEM will fail validation.

The important deviations from the CCSDS standard for AWS Ground Station are:

  • CCSDS_OEM_VERS is required to be 2.0.

  • REF_FRAME is required to be either EME2000 or ITRF2000.

  • REF_FRAME_EPOCH is not supported by AWS Ground Station.

  • CENTER_NAME is required to be Earth.

  • TIME_SYSTEM is required to be UTC.

  • INTERPOLATION and INTERPOLATION_DEGREES are both required for AWS Ground Station CPE.

Example OEM ephemeris in KVN format

Following is a truncated example of an OEM ephemeris in KVN format for the JPSS-1 public broadcaster satellite. 


CCSDS_OEM_VERS = 2.0

COMMENT Orbit data are consistent with planetary ephemeris DE-430

CREATION_DATE  = 2024-07-22T05:20:59
ORIGINATOR     = Raytheon-JPSS/CGS

META_START
OBJECT_NAME          = J1
OBJECT_ID            = 2017-073A
CENTER_NAME          = Earth
REF_FRAME            = EME2000
TIME_SYSTEM          = UTC
START_TIME           = 2024-07-22T00:00:00.000000
STOP_TIME            = 2024-07-22T00:06:00.000000 
INTERPOLATION        = Lagrange
INTERPOLATION_DEGREE = 5
META_STOP

2024-07-22T00:00:00.000000   5.905147360000000e+02  -1.860082793999999e+03  -6.944807075000000e+03  -5.784245796000000e+00   4.347501391999999e+00  -1.657256863000000e+00
2024-07-22T00:01:00.000000   2.425572045154201e+02  -1.595860765983339e+03  -7.030938457373539e+03  -5.810660250794190e+00   4.457103652219009e+00  -1.212889340333023e+00
2024-07-22T00:02:00.000000  -1.063224256538050e+02  -1.325569732497146e+03  -7.090262617183503e+03  -5.814973972202444e+00   4.549739160042560e+00  -7.639633689161465e-01
2024-07-22T00:03:00.000000  -4.547973959231161e+02  -1.050238305712201e+03  -7.122556683227951e+03  -5.797176562437553e+00   4.625064829516728e+00  -3.121687831090774e-01
2024-07-22T00:04:00.000000  -8.015427368657785e+02  -7.709137891269565e+02  -7.127699477194810e+03  -5.757338007808417e+00   4.682800822515077e+00   1.407953645161997e-01
2024-07-22T00:05:00.000000  -1.145240083085062e+03  -4.886583601179489e+02  -7.105671911254255e+03  -5.695608435738609e+00   4.722731329786999e+00   5.932259682105052e-01
2024-07-22T00:06:00.000000  -1.484582479061495e+03  -2.045451985605701e+02  -7.056557069672793e+03  -5.612218005854990e+00   4.744705579872771e+00   1.043421397392599e+00

Creating a custom ephemeris

A custom ephemeris can be created using the CreateEphemeris action in the AWS Ground Station API. This action will upload an ephemeris using data either in the request body or from a specified S3 bucket.

It is important to note that uploading an ephemeris sets the ephemeris to VALIDATING and starts an asynchronous workflow that will validate and generate potential contacts from your ephemeris. Only once an ephemeris has passed this workflow and become ENABLED will it be used for contacts. You should poll DescribeEphemeris for the ephemeris status or use CloudWatch events to track the ephemeris' status changes.

To troubleshoot an invalid ephemeris see: Troubleshoot invalid ephemerides

Example: Create a two-line element (TLE) set ephemeris via API

The AWS SDKs, and CLI can be used to upload a two line element (TLE) set ephemeris to AWS Ground Station via the CreateEphemeris call. This ephemeris will be used in place of the default ephemeris data for a satellite (see Default Ephemeris Data). This example shows how to do this using the AWS SDK for Python (Boto3).

A TLE set is a JSON formatted object that strings one or more TLEs together to construct a continuous trajectory. The TLEs in the TLE set must form a continuous set that we can use to construct a trajectory (i.e. no gaps in time between TLEs in a TLE set). An example TLE set is shown below: 

# example_tle_set.json
[
    {
        "tleLine1": "1 25994U 99068A   20318.54719794  .00000075  00000-0  26688-4 0  9997",
        "tleLine2": "2 25994  98.2007  30.6589 0001234  89.2782  18.9934 14.57114995111906",
        "validTimeRange": {
            "startTime": 12345,
            "endTime": 12346
        }
    },
    {
        "tleLine1": "1 25994U 99068A   20318.54719794  .00000075  00000-0  26688-4 0  9997",
        "tleLine2": "2 25994  98.2007  30.6589 0001234  89.2782  18.9934 14.57114995111906",
        "validTimeRange": {
            "startTime": 12346,
            "endTime": 12347
        }
    }
]
Note

The time ranges of the TLEs in a TLE set must match up exactly to be a valid, continuous trajectory.

A TLE set can be uploaded via the AWS Ground Station boto3 client as follows: 

tle_ephemeris_id = ground_station_boto3_client.create_ephemeris( name="Example Ephemeris", satelliteId="2e925701-9485-4644-b031-EXAMPLE01", enabled=True, expirationTime=datetime.now(timezone.utc) + timedelta(days=3), priority=2,
    ephemeris = {
      "tle": {
        "tleData": [
            {
                "tleLine1": "1 25994U 99068A   20318.54719794  .00000075  00000-0  26688-4 0  9997",
                "tleLine2": "2 25994  98.2007  30.6589 0001234  89.2782  18.9934 14.57114995111906",
                "validTimeRange": {
                    "startTime": datetime.now(timezone.utc),
                    "endTime": datetime.now(timezone.utc) + timedelta(days=7)
                }
            }
        ]
      }
    })

This call will return an ephemerisId that can be used to reference the ephemeris in the future. For example, we can use the provided ephemerisId from the call above to poll for the status of the ephemeris: 

client.describe_ephemeris(ephemerisId=tle_ephemeris_id['ephemerisId'])

An example response from the DescribeEphemeris action is provided below 

{
  "creationTime": 1620254718.765,
  "enabled": true,
  "name": "Example Ephemeris",
  "ephemerisId": "fde41049-14f7-413e-bd7b-EXAMPLE01",
  "priority": 2,
  "status": "VALIDATING",
  "suppliedData": {
    "tle": {
      "ephemerisData": "[{\"tleLine1\": \"1 25994U 99068A   20318.54719794  .00000075  00000-0  26688-4 0  9997\",\"tleLine2": \"2 25994  98.2007  30.6589 0001234  89.2782  18.9934 14.57114995111906\",\"validTimeRange\": {\"startTime\": 1620254712000,\"endTime\": 1620859512000}}]"
    }
  }
}

It is recommended to poll the DescribeEphemeris route or use CloudWatch events to track the status of the uploaded ephemeris as it must go through an asynchronous validation workflow before it is set to ENABLED and becomes usable for scheduling and executing contacts.

Note that the NORAD ID in all TLEs in the TLE set, 25994 in the examples above, must match the NORAD ID your satellite has been assigned in the Space-Track database.

Example: Uploading Ephemeris data from an S3 bucket

It is also possible to upload an ephemeris file directly from an S3 bucket by pointing to the bucket and object key. AWS Ground Station will retrieve the object on your behalf. Information about the encryption of data at rest in AWS Ground Station is detailed in: Data Encryption At Rest For AWS Ground Station

Below is an example of uploading an OEM ephemeris file from an S3 bucket 

s3_oem_ephemeris_id = ground_station_client.create_ephemeris( name="2022-10-26 S3 OEM Upload", satelliteId="fde41049-14f7-413e-bd7b-EXAMPLE01", enabled=True, expirationTime=datetime.now(timezone.utc) + timedelta(days=5), priority=2,
    ephemeris = {
        "oem": {
            "s3Object": {
                "bucket": "ephemeris-bucket-for-testing",
                "key": "test_data.oem",
            }
        }
    })

Below is an example returned data from the DescribeEphemeris action being called for the OEM ephemeris uploaded in the previous block of example code. 

{
  "creationTime": 1620254718.765,
  "enabled": true,
  "name": "Example Ephemeris",
  "ephemerisId": "fde41049-14f7-413e-bd7b-EXAMPLE02",
  "priority": 2,
  "status": "VALIDATING",
  "suppliedData": {
    "oem": {
      "sourceS3Object": {
          "bucket": "ephemeris-bucket-for-testing",
          "key": "test_data.oem"
      }
    }
  }
}

Example: Using customer-provided ephemerides with AWS Ground Station

For more detailed instructions for using customer-provided ephemerides with AWS Ground Station, see Using customer-provided ephemerides with AWS Ground Station (and it's associated GitHub repository aws-samples/aws-groundstation-cpe)