# Understand how AWS Ground Station uses ephemerides
An [ephemeris](https://en.wikipedia.org/wiki/Ephemeris), plural ephemerides, is a file or data structure providing the trajectory of astronomical objects. Historically, this file only referred to tabular data but, gradually, it has come to direct to a wide variety of data files indicating a spacecraft trajectory.
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](https://www.space-track.org/) (see: [Default ephemeris data](default-ephemeris-data.md)). We support receiving ephemeris data in Orbit Ephemeris Message (OEM), two-line element (TLE), and azimuth elevation formats.
AWS Ground Station uses ephemeris data to determine when contacts become available based on the provided ephemeris and correctly command antennas in the AWS Ground Station network. By default, no action is required to provide AWS Ground Station with ephemerides if your satellite has an assigned [NORAD ID](https://en.wikipedia.org/wiki/Satellite_Catalog_Number).
Uploading custom ephemerides can improve the quality of tracking, handle early operations where no [Space-Track](https://www.space-track.org/) ephemerides are available to AWS Ground Station, and account for maneuvers.
Alternatively, AWS Ground Station supports an azimuth elevation format, which allow you to directly specify antenna pointing directions without providing satellite orbital information. This is useful for scenarios where precise antenna pointing is required because satellite trajectory information is imprecise or unknown.
**Topics**
+ [Default ephemeris data](default-ephemeris-data.md)
+ [Provide custom ephemeris data](providing-custom-ephemeris-data.md)
+ [Reserve contacts with custom ephemeris](reserving-contacts-with-custom-ephemeris.md)
+ [Understand which ephemeris is used](which-ephemeris-is-used.md)
+ [Get the current ephemeris for a satellite](getting-current-ephemeris.md)
+ [Revert to default ephemeris data](reverting-to-default-ephemeris-data.md)
# Default ephemeris data
By default, AWS Ground Station uses publicly available data from [Space-Track](https://www.space-track.org/), and no action is required to supply AWS Ground Station with these default ephemerides. These ephemerides are [two-line element sets (TLEs)](https://en.wikipedia.org/wiki/Two-line_element_set) associated with your satellite's [NORAD ID](https://en.wikipedia.org/wiki/Satellite_Catalog_Number). All default ephemerides have a priority of `0`. As a result, they will be overridden, always, by any non-expired, custom ephemerides uploaded via the ephemeris API, which must always have a priority of `1`, or greater.
Satellites without a NORAD ID must upload custom ephemeris data to AWS Ground Station. For example, satellites that have just launched or that are intentionally omitted from the [Space-Track](https://www.space-track.org/) catalog would have no NORAD ID and would need to have custom ephemerides uploaded. For more information on providing custom ephemeris data, see: [Providing Custom Ephemeris Data](providing-custom-ephemeris-data.md).
# 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, please open an AWS Support ticket through the [AWS Support Center Console](https://console.aws.amazon.com/support). Our team will work with you to enable this capability for your specific requirements.
## 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](https://www.space-track.org/) (see: [Default ephemeris data](default-ephemeris-data.md)). We support receiving ephemeris data in Orbit Ephemeris Message (OEM), two-line element (TLE), and azimuth elevation formats.
AWS Ground Station treats ephemerides as [Individualized Usage Data](https://aws.amazon.com/service-terms). If you use this optional feature, AWS will use your ephemeris data to provide troubleshooting support.
Uploading custom ephemerides can improve the quality of tracking, handle operations where no [Space-Track](https://www.space-track.org/) ephemerides are available to AWS Ground Station, and account for maneuvers.
To troubleshoot an invalid ephemeris see: [Troubleshoot invalid ephemerides](troubleshooting-invalid-ephemerides.md)
## 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](https://aws.amazon.com/blogs/publicsector/using-customer-provided-ephemerides-with-aws-ground-station/) and it's associated GitHub repository [aws-samples/aws-groundstation-cpe](https://github.com/aws-samples/aws-groundstation-cpe).
# Provide TLE 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, please open an AWS Support ticket through the [AWS Support Center Console](https://console.aws.amazon.com/support). Our team will work with you to enable this capability for your specific requirements.
## Overview
Two-line element (TLE) sets are a standardized format for describing satellite orbits. The Ephemeris API allows TLE ephemerides to be uploaded to AWS Ground Station for use with a satellite. These ephemerides override the default ephemerides from [Space-Track](https://www.space-track.org/) (see: [Default ephemeris data](default-ephemeris-data.md)).
AWS Ground Station treats ephemerides as [Individualized Usage Data](https://aws.amazon.com/service-terms). If you use this optional feature, AWS will use your ephemeris data to provide troubleshooting support.
Uploading custom TLE ephemerides can improve the quality of tracking, handle early operations where no [Space-Track](https://www.space-track.org/) 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 (e.g. `24000A` for a vehicle launched in 2024).
For more information about the format of TLEs, see [Two-line element set](https://en.wikipedia.org/wiki/Two-line_element_set).
## Creating a TLE ephemeris
A TLE ephemeris can be created using the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 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](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) for the ephemeris status or use CloudWatch events to track the ephemeris' status changes.
To troubleshoot an invalid ephemeris see: [Troubleshoot invalid ephemerides](troubleshooting-invalid-ephemerides.md)
## 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](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) call. This ephemeris will be used in place of the default ephemeris data for a satellite (see [Default ephemeris data](default-ephemeris-data.md)). This example shows how to do this using the [AWS SDK for Python (Boto3)](https://docs.aws.amazon.com/pythonsdk).
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:
```
[
{
"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:
```
import boto3
from datetime import datetime, timedelta, timezone
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Create TLE ephemeris
tle_ephemeris = ground_station_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),
},
}
]
}
},
)
print(f"Created TLE ephemeris with ID: {tle_ephemeris['ephemerisId']}")
```
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:
```
import boto3
from datetime import datetime, timedelta, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# First, create a TLE ephemeris
print("Creating TLE ephemeris...")
tle_ephemeris = ground_station_client.create_ephemeris(
name="Example TLE Ephemeris for Description",
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),
},
}
]
}
},
)
ephemeris_id = tle_ephemeris["ephemerisId"]
print(f"Created TLE ephemeris with ID: {ephemeris_id}")
# Describe the ephemeris immediately to check initial status
print("Describing ephemeris...")
response = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)
print(f"Ephemeris ID: {response['ephemerisId']}")
print(f"Name: {response['name']}")
print(f"Status: {response['status']}")
```
An example response from the [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 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](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 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](https://www.space-track.org/) database.
## Example: Uploading TLE ephemeris data from an S3 bucket
It is also possible to upload a TLE 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](security.encryption-at-rest.md).
Below is an example of uploading a TLE ephemeris file from an S3 bucket
```
import boto3
from datetime import datetime, timedelta, timezone
import json
# Create AWS clients
s3_client = boto3.client("s3")
ground_station_client = boto3.client("groundstation")
# Define S3 bucket and key
bucket_name = "ephemeris-bucket"
object_key = "test_data.tle"
# Create sample TLE set data
# Note: For actual satellites, use real TLE data from sources like Space-Track
tle_set_data = [
{
"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=3),
},
},
{
"tleLine1": "1 25994U 99068A 20321.54719794 .00000075 00000-0 26688-4 0 9998",
"tleLine2": "2 25994 98.2007 33.6589 0001234 89.2782 18.9934 14.57114995112342",
"validTimeRange": {
"startTime": datetime.now(timezone.utc) + timedelta(days=3),
"endTime": datetime.now(timezone.utc) + timedelta(days=7),
},
},
]
# Convert to JSON string for upload
tle_json = json.dumps(tle_set_data, indent=2)
# Upload sample TLE data to S3
print(f"Uploading TLE set data to s3://{bucket_name}/{object_key}")
s3_client.put_object(
Bucket=bucket_name, Key=object_key, Body=tle_json, ContentType="application/json"
)
print("TLE set data uploaded successfully to S3")
print(f"Uploaded {len(tle_set_data)} TLE entries covering 7 days")
# Create TLE ephemeris from S3
print("Creating TLE ephemeris from S3...")
s3_tle_ephemeris = ground_station_client.create_ephemeris(
name="2022-11-05 S3 TLE Upload",
satelliteId="fde41049-14f7-413e-bd7b-EXAMPLE01",
enabled=True,
expirationTime=datetime.now(timezone.utc) + timedelta(days=5),
priority=2,
ephemeris={"tle": {"s3Object": {"bucket": bucket_name, "key": object_key}}},
)
print(f"Created TLE ephemeris with ID: {s3_tle_ephemeris['ephemerisId']}")
```
# Provide OEM 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, please open an AWS Support ticket through the [AWS Support Center Console](https://console.aws.amazon.com/support). Our team will work with you to enable this capability for your specific requirements.
## Overview
Orbit Ephemeris Message (OEM) is a standardized format for representing spacecraft trajectory data. The Ephemeris API allows OEM ephemerides to be uploaded to AWS Ground Station for use with a satellite. These ephemerides override the default ephemerides from [Space-Track](https://www.space-track.org/) (see: [Default ephemeris data](default-ephemeris-data.md)).
AWS Ground Station treats ephemerides as [Individualized Usage Data](https://aws.amazon.com/service-terms). If you use this optional feature, AWS will use your ephemeris data to provide troubleshooting support.
Uploading custom OEM ephemerides can improve the quality of tracking, handle early operations where no [Space-Track](https://www.space-track.org/) 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 `satelliteId` for the `OBJECT_ID` portion of the OEM.
For more information about the format of OEMs, see [OEM ephemeris format](#oem-ephemeris-format).
## OEM ephemeris format
AWS Ground Station processes OEM Customer Provided Ephemerides according to the [CCSDS standard](https://ccsds.org/Pubs/502x0b3e1.pdf) 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.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ground-station/latest/ug/providing-oem-ephemeris-data.html)
\$1 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_DEGREE` are both required for AWS Ground Station customer provided ephemeris.
+ AWS Ground Station deviates from CCSDS 5.2.4.7 by allowing OEM data blocks that do not contain enough ephemeris data records to perform interpolation at the specified `INTERPOLATION_DEGREE`. In this case, AWS Ground Station will use the highest interpolation degree possible that is less than or equal to the specified `INTERPOLATION_DEGREE`.
## 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 an OEM ephemeris
An OEM ephemeris can be created using the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 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](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) for the ephemeris status or use CloudWatch events to track the ephemeris' status changes.
To troubleshoot an invalid ephemeris see: [Troubleshoot invalid ephemerides](troubleshooting-invalid-ephemerides.md)
## Example: Uploading OEM ephemeris data from an S3 bucket
It is also possible to upload an OEM 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](security.encryption-at-rest.md).
Below is an example of uploading an OEM ephemeris file from an S3 bucket
```
import boto3
from datetime import datetime, timedelta, timezone
# Create AWS clients
s3_client = boto3.client("s3")
ground_station_client = boto3.client("groundstation")
# Define S3 bucket and key
bucket_name = "ephemeris-bucket"
object_key = "test_data.oem"
# Create sample OEM data in KVN format
oem_data = """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
"""
# Upload sample OEM data to S3
print(f"Uploading OEM data to s3://{bucket_name}/{object_key}")
s3_client.put_object(
Bucket=bucket_name, Key=object_key, Body=oem_data, ContentType="text/plain"
)
print("OEM data uploaded successfully to S3")
# Create OEM ephemeris from S3
print("Creating OEM ephemeris from S3...")
s3_oem_ephemeris = ground_station_client.create_ephemeris(
name="2024-07-22 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": bucket_name, "key": object_key}}},
)
print(f"Created OEM ephemeris with ID: {s3_oem_ephemeris['ephemerisId']}")
```
Below is an example returned data from the [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 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"
}
}
}
}
```
# Provide azimuth elevation ephemeris data
**Important**
The azimuth elevation ephemeris feature is currently in a Preview state and requires explicit onboarding.
Azimuth elevation ephemeris functionality is under strict access control for a limited number of pre-determined, specialized use cases. Access is significantly more restrictive than for standard customer-provided ephemeris capabilities. For more information about approved use cases and the access request process, please open an AWS Support ticket through the [AWS Support Center Console](https://console.aws.amazon.com/support). Our team will guide you through the approval process for specialized use cases.
## Overview
Azimuth elevation ephemeris provides a way to directly specify antenna pointing directions without providing satellite orbital information. Instead of uploading ephemeris data that describes a satellite's orbit, you provide time-tagged azimuth and elevation angles that tell the antenna exactly where to point throughout a contact.
AWS Ground Station treats ephemerides as [Individualized Usage Data](https://aws.amazon.com/service-terms). If you use this optional feature, AWS will use your ephemeris data to provide troubleshooting support.
This approach is particularly useful for the following scenarios:
+ *Early operations support:* During Launch and Early Orbit Phase (LEOP) when precise orbital data is unavailable, or orbital parameters are rapidly changing.
+ *Custom pointing patterns:* Implementing specific pointing sequences for antenna testing or non-standard operations.
**Note**
When using azimuth elevation ephemeris, the satellite ARN may be omitted from the contact reservation request. If the satellite ARN is not omitted, it will still be included as part of the contact data, but the azimuth elevation ephemeris will be used for antenna pointing rather than performing ephemeris priority resolution. The azimuth elevation ephemeris is associated with a specific ground station and defines the antenna pointing directions for that location.
## Azimuth elevation ephemeris data format
Azimuth elevation ephemeris data consists of time-tagged azimuth and elevation values organized into segments. Each segment contains a series of azimuth and elevation angles that cover a specific time range.
The key components of azimuth elevation ephemeris data are:
+ *Ground Station:* The specific ground station where this azimuth elevation ephemeris will be used.
+ *Angle Unit:* The unit of measurement for angles (`DEGREE_ANGLE` or `RADIAN`).
+ *Segments:* One or more time-bounded collections of azimuth and elevation angles.
+ *Time-tagged angles:* Individual azimuth and elevation values with associated timestamps.
Each segment requires:
+ A reference epoch (the base time for the segment)
+ A valid time range (start and end times for the segment)
+ At least 5 time-tagged azimuth/elevation pairs
Azimuth elevation constraints:
+ Azimuth in degrees: -180° to 360°
+ Azimuth in radians: -π to 2π
+ Elevation in degrees: -90° to 90°
+ Elevation in radians: -π/2 to π/2
+ Time values must be in ascending order within each segment
+ Segments must not overlap in time
For more information, see the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) API documentation and the [TimeAzEl](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_TimeAzEl.html) data type.
## Creating azimuth elevation ephemeris
Azimuth elevation ephemeris is created using the same [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) API action, but with the `azEl` ephemeris type. The key differences from TLE and OEM ephemeris are:
+ You must specify a `groundStation` parameter
+ The `satelliteId` parameter must be omitted from the request
+ Priority settings do not apply (each azimuth elevation ephemeris is specific to a ground station)
+ Each segment must contain at least 5 azimuth/elevation points to support 4th order Lagrange interpolation
+ Additional limits and requirements are detailed in the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) API documentation
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. An ephemeris will only be used for contacts after it has passed this workflow and its status becomes `ENABLED`. You should poll [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) for the ephemeris status or use CloudWatch events to track the ephemeris' status changes.
To troubleshoot an invalid ephemeris see: [Troubleshoot invalid ephemerides](troubleshooting-invalid-ephemerides.md)
## Example: Create azimuth elevation ephemeris via API
The following example shows how to create an azimuth elevation ephemeris using the AWS SDK for Python (Boto3):
```
import boto3
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Create azimuth elevation ephemeris
azimuth_elevation_ephemeris = ground_station_client.create_ephemeris(
name="Azimuth Elevation for Ohio Ground Station",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
print(f"Created ephemeris with ID: {azimuth_elevation_ephemeris['ephemerisId']}")
```
In this example:
+ The azimuth elevation data is associated with the "Ohio 1" ground station
+ Angles are specified in degrees
+ The segment covers a 15-minute period
+ The `dt` values are atomic seconds offset from the reference epoch
+ Six azimuth/elevation pairs are provided (minimum is 5)
## Example: Upload azimuth elevation data from S3
For larger datasets, you can upload azimuth elevation data from an S3 bucket:
```
import boto3
import json
# Create AWS clients
s3_client = boto3.client("s3")
ground_station_client = boto3.client("groundstation")
# Define S3 bucket and key
bucket_name = "azimuth-elevation-bucket"
object_key = "singapore-azimuth-elevation.json"
# Create sample azimuth elevation data
azimuth_elevation_data = {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
},
{
"referenceEpoch": "2024-03-15T10:15:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:15:00Z",
"endTime": "2024-03-15T10:30:00Z",
},
"azElList": [
{"dt": 0.0, "az": 70.0, "el": 35.0},
{"dt": 180.0, "az": 75.0, "el": 40.0},
{"dt": 360.0, "az": 80.0, "el": 45.0},
{"dt": 540.0, "az": 85.0, "el": 50.0},
{"dt": 720.0, "az": 90.0, "el": 55.0},
{"dt": 900.0, "az": 95.0, "el": 50.0},
],
},
],
}
# Upload sample data to S3
print(f"Uploading azimuth elevation data to s3://{bucket_name}/{object_key}")
s3_client.put_object(
Bucket=bucket_name,
Key=object_key,
Body=json.dumps(azimuth_elevation_data, indent=2),
ContentType="application/json",
)
print("Sample data uploaded successfully to S3")
# Create azimuth elevation ephemeris from S3
print("Creating azimuth elevation ephemeris from S3...")
s3_azimuth_elevation_ephemeris = ground_station_client.create_ephemeris(
name="Large Azimuth Elevation Dataset",
ephemeris={
"azEl": {
"groundStation": "Singapore 1",
"data": {"s3Object": {"bucket": bucket_name, "key": object_key}},
}
},
)
print(f"Created ephemeris with ID: {s3_azimuth_elevation_ephemeris['ephemerisId']}")
```
The S3 object should contain a JSON structure with the azimuth elevation data in the same format as shown in the direct upload example.
## Reserving contacts with azimuth elevation ephemeris
When using an azimuth elevation ephemeris to reserve a contact, the process differs from TLE and OEM ephemeris:
1. Create the azimuth elevation ephemeris using [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html)
1. Wait for the ephemeris to reach `ENABLED` status
1. Reserve the contact using [ReserveContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ReserveContact.html) with tracking overrides
Example of reserving a contact with azimuth elevation ephemeris:
```
import boto3
from datetime import datetime
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# First, create an azimuth elevation ephemeris
print("Creating azimuth elevation ephemeris...")
create_ephemeris_response = ground_station_client.create_ephemeris(
name="Azimuth Elevation for Contact Reservation",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
ephemeris_id = create_ephemeris_response["ephemerisId"]
print(f"Created ephemeris with ID: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
print("Waiting for ephemeris to become ENABLED...")
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# Reserve contact with azimuth elevation ephemeris
print("Reserving contact...")
contact = ground_station_client.reserve_contact(
# Note: satelliteArn is omitted when using azimuth elevation ephemeris
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-mission-profile",
groundStation="Ohio 1",
startTime=datetime(2024, 3, 15, 10, 0, 0),
endTime=datetime(2024, 3, 15, 10, 15, 0),
trackingOverrides={"programTrackSettings": {"azEl": {"ephemerisId": ephemeris_id}}},
)
print(f"Reserved contact with ID: {contact['contactId']}")
```
**Note**
The `satelliteArn` parameter may be omitted when reserving a contact with azimuth elevation ephemeris. The antenna will follow the specified azimuth and elevation angles during the contact.
## Listing available contacts
When using azimuth elevation ephemeris, the [ListContacts](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContacts.html) API requires specific parameters:
+ The `satelliteArn` parameter may be omitted from the request
+ You must provide an `ephemeris` parameter with the azimuth elevation ephemeris ID to specify which ephemeris to use
+ Available contact windows show when the provided azimuth and elevation angles are above the [site mask](https://docs.aws.amazon.com/ground-station/latest/ug/locations.site-masks.html) of the requested ground station
+ You must still provide `groundStation` and `missionProfileArn`
Example of creating an azimuth elevation ephemeris and listing available contacts with it:
```
import boto3
from datetime import datetime, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Step 1: Create azimuth elevation ephemeris
print("Creating azimuth elevation ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="Stockholm AzEl Ephemeris",
ephemeris={
"azEl": {
"groundStation": "Stockholm 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-04-01T12:00:00Z",
"validTimeRange": {
"startTime": "2024-04-01T12:00:00Z",
"endTime": "2024-04-01T12:30:00Z",
},
"azElList": [
{"dt": 0.0, "az": 30.0, "el": 15.0},
{"dt": 360.0, "az": 45.0, "el": 30.0},
{"dt": 720.0, "az": 60.0, "el": 45.0},
{"dt": 1080.0, "az": 75.0, "el": 35.0},
{"dt": 1440.0, "az": 90.0, "el": 20.0},
{"dt": 1800.0, "az": 105.0, "el": 10.0},
],
}
],
}
},
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Step 2: Wait for ephemeris to become ENABLED
print("Waiting for ephemeris to become ENABLED...")
while True:
describe_response = ground_station_client.describe_ephemeris(
ephemerisId=ephemeris_id
)
status = describe_response["status"]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
# Check for validation errors
if "invalidReason" in describe_response:
print(f"Ephemeris validation failed: {describe_response['invalidReason']}")
raise RuntimeError(f"Ephemeris failed with status: {status}")
print(f"Current status: {status}, waiting...")
time.sleep(5)
# Step 3: List available contacts using the azimuth elevation ephemeris
print("Listing available contacts with azimuth elevation ephemeris...")
# Convert epoch timestamps to datetime objects
start_time = datetime.fromtimestamp(1760710513, tz=timezone.utc)
end_time = datetime.fromtimestamp(1760883313, tz=timezone.utc)
contacts_response = ground_station_client.list_contacts(
startTime=start_time,
endTime=end_time,
groundStation="Stockholm 1",
statusList=["AVAILABLE"],
ephemeris={"azEl": {"id": ephemeris_id}},
# satelliteArn is optional
satelliteArn="arn:aws:groundstation::111122223333:satellite/a88611b0-f755-404e-b60d-57d8aEXAMPLE",
missionProfileArn="arn:aws:groundstation:eu-north-1:111122223333:mission-profile/966b72f6-6d82-4e7e-b072-f8240EXAMPLE",
)
# Process the results
if contacts_response["contactList"]:
print(f"Found {len(contacts_response['contactList'])} available contacts:")
for contact in contacts_response["contactList"]:
print(f" - Contact from {contact['startTime']} to {contact['endTime']}")
print(
f" Max elevation: {contact.get('maximumElevation', {}).get('value', 'N/A')}°"
)
else:
print("No available contacts found for the specified azimuth elevation ephemeris")
```
**Note**
The `ephemeris` parameter with the azimuth elevation ID must be provided when listing contacts to specify which azimuth elevation ephemeris should be used for determining contact windows. If the `satelliteArn` is included, it will be associated with the contact data, but the azimuth elevation ephemeris will be used for antenna pointing rather than performing ephemeris priority resolution.
# Reserve contacts with custom ephemeris
## Overview
When using custom ephemeris (TLE, OEM, or azimuth elevation), you can reserve contacts using the [ReserveContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ReserveContact.html) API. This section describes two common workflows for reserving contacts and important considerations for ensuring successful contact scheduling.
AWS Ground Station antennas are shared resources among multiple customers. This means that even if a contact window appears available when you list contacts, another customer might reserve it before you do. Therefore, it's crucial to verify that your contact reaches the `SCHEDULED` state after reservation and to implement proper monitoring for contact state changes.
**Important**
For azimuth elevation ephemeris, the `satelliteArn` parameter may be omitted from the `ReserveContact` request, and you must provide `trackingOverrides` with the ephemeris ID. For TLE and OEM ephemeris, you still need to provide the `satelliteArn`.
## Contact reservation workflows
There are two primary workflows for reserving contacts with custom ephemeris:
1. *List-then-reserve workflow:* First list available contact windows using [ListContacts](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContacts.html), then select and reserve a specific window. This approach is useful when you want to see all available opportunities before making a selection.
1. *Direct reservation workflow:* Directly reserve a contact for a specific time window without first listing available contacts. This approach is useful when you already know your desired contact time or are working with predetermined schedules.
Both workflows are valid and the choice depends on your operational requirements. The following sections provide examples of each approach.
## Workflow 1: List available contacts then reserve
This workflow first queries for available contact windows, then reserves a specific window. This is useful when you want to see all available opportunities before making a selection.
### Example: List and reserve with azimuth elevation ephemeris
```
import boto3
from datetime import datetime, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Create azimuth elevation ephemeris
print("Creating azimuth elevation ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="AzEl Ephemeris for Contact",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# List available contacts
print("Listing available contacts...")
contacts = ground_station_client.list_contacts(
# Note: satelliteArn is omitted for azimuth elevation ephemeris
groundStation="Ohio 1",
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-profile",
startTime=datetime(2024, 3, 15, 10, 0, 0, tzinfo=timezone.utc),
endTime=datetime(2024, 3, 15, 10, 15, 0, tzinfo=timezone.utc),
statusList=["AVAILABLE"],
ephemeris={"azEl": {"id": ephemeris_id}},
)
if contacts["contactList"]:
# Reserve the first available contact
contact = contacts["contactList"][0]
print(f"Reserving contact from {contact['startTime']} to {contact['endTime']}...")
reservation = ground_station_client.reserve_contact(
# Note: satelliteArn is omitted when using azimuth elevation ephemeris
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-profile",
groundStation="Ohio 1",
startTime=contact["startTime"],
endTime=contact["endTime"],
trackingOverrides={
"programTrackSettings": {"azEl": {"ephemerisId": ephemeris_id}}
},
)
print(f"Reserved contact: {reservation['contactId']}")
else:
print("No available contacts found")
```
### Example: List and reserve with TLE ephemeris
```
import boto3
from datetime import datetime, timedelta, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
satellite_id = "12345678-1234-1234-1234-123456789012"
satellite_arn = f"arn:aws:groundstation::111122223333:satellite/{satellite_id}"
# Create TLE ephemeris
print("Creating TLE ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="TLE Ephemeris for Contact",
satelliteId=satellite_id,
enabled=True,
expirationTime=datetime.now(timezone.utc) + timedelta(days=7),
priority=1, # Higher priority than default ephemeris
ephemeris={
"tle": {
"tleData": [
{
"tleLine1": "1 25994U 99068A 24075.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),
},
}
]
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# List available contacts
print("Listing available contacts...")
start_time = datetime.now(timezone.utc) + timedelta(hours=1)
end_time = start_time + timedelta(days=1)
contacts = ground_station_client.list_contacts(
satelliteArn=satellite_arn, # Required for TLE/OEM ephemeris
groundStation="Hawaii 1",
missionProfileArn="arn:aws:groundstation:us-west-2:111122223333:mission-profile/example-profile",
startTime=start_time,
endTime=end_time,
statusList=["AVAILABLE"],
)
if contacts["contactList"]:
# Reserve the first available contact
contact = contacts["contactList"][0]
print(f"Reserving contact from {contact['startTime']} to {contact['endTime']}...")
reservation = ground_station_client.reserve_contact(
satelliteArn=satellite_arn, # Required for TLE/OEM ephemeris
missionProfileArn="arn:aws:groundstation:us-west-2:111122223333:mission-profile/example-profile",
groundStation="Hawaii 1",
startTime=contact["startTime"],
endTime=contact["endTime"],
# Note: trackingOverrides is optional for TLE/OEM
# The system will use the highest priority ephemeris automatically
)
print(f"Reserved contact: {reservation['contactId']}")
else:
print("No available contacts found")
```
## Workflow 2: Direct contact reservation
This workflow directly reserves a contact without first listing available windows. This approach is useful when you already know your desired contact time or are implementing automated scheduling.
### Example: Direct reservation with azimuth elevation ephemeris
```
import boto3
from datetime import datetime, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Define contact window
contact_start = datetime(2024, 3, 20, 14, 0, 0, tzinfo=timezone.utc)
contact_end = datetime(2024, 3, 20, 14, 15, 0, tzinfo=timezone.utc)
# Create azimuth elevation ephemeris for the specific contact time
print("Creating azimuth elevation ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="Direct Contact AzEl Ephemeris",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": contact_start.isoformat(),
"validTimeRange": {
"startTime": contact_start.isoformat(),
"endTime": contact_end.isoformat(),
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# Directly reserve the contact
print(f"Reserving contact from {contact_start} to {contact_end}...")
reservation = ground_station_client.reserve_contact(
# Note: satelliteArn is omitted for azimuth elevation
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-profile",
groundStation="Ohio 1",
startTime=contact_start,
endTime=contact_end,
trackingOverrides={"programTrackSettings": {"azEl": {"ephemerisId": ephemeris_id}}},
)
print(f"Reserved contact: {reservation['contactId']}")
```
### Example: Direct reservation with TLE ephemeris
```
import boto3
from datetime import datetime, timedelta, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
satellite_id = "12345678-1234-1234-1234-123456789012"
satellite_arn = f"arn:aws:groundstation::111122223333:satellite/{satellite_id}"
# Define contact window (based on predicted pass)
contact_start = datetime(2024, 3, 21, 10, 30, 0, tzinfo=timezone.utc)
contact_end = datetime(2024, 3, 21, 10, 42, 0, tzinfo=timezone.utc)
# Create TLE ephemeris
print("Creating TLE ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="Direct Contact TLE Ephemeris",
satelliteId=satellite_id,
enabled=True,
expirationTime=contact_end + timedelta(days=1),
priority=1,
ephemeris={
"tle": {
"tleData": [
{
"tleLine1": "1 25994U 99068A 24080.50000000 .00000075 00000-0 26688-4 0 9999",
"tleLine2": "2 25994 98.2007 35.6589 0001234 89.2782 18.9934 14.57114995112000",
"validTimeRange": {
"startTime": (contact_start - timedelta(hours=1)).isoformat(),
"endTime": (contact_end + timedelta(hours=1)).isoformat(),
},
}
]
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# Directly reserve the contact
print(f"Reserving contact from {contact_start} to {contact_end}...")
reservation = ground_station_client.reserve_contact(
satelliteArn=satellite_arn, # Required for TLE ephemeris
missionProfileArn="arn:aws:groundstation:us-west-2:111122223333:mission-profile/example-profile",
groundStation="Hawaii 1",
startTime=contact_start,
endTime=contact_end,
# Note: trackingOverrides is optional for TLE
# The system will use the highest priority ephemeris automatically
)
print(f"Reserved contact: {reservation['contactId']}")
```
## Monitoring contact state changes
After reserving a contact, it's important to monitor its state to ensure it successfully transitions to `SCHEDULED` and to be notified of any issues. AWS Ground Station emits events to Amazon EventBridge for all contact state changes.
Contact states follow this lifecycle:
+ `SCHEDULING` - The contact is being processed for scheduling
+ `SCHEDULED` - The contact was successfully scheduled and will execute
+ `FAILED_TO_SCHEDULE` - The contact could not be scheduled (terminal state)
For more information on contact states and lifecycle, see [Understand contact lifecycle](contacts.lifecycle.md).
### Implementing contact state monitoring with EventBridge
To monitor contact state changes in real-time, you can set up an Amazon EventBridge rule that triggers a Lambda function whenever a Ground Station contact changes state. This approach is more efficient and scalable than polling the contact status.
#### Implementation steps
1. Create a Lambda function to process contact state change events
1. Create an EventBridge rule that matches Ground Station contact state change events
1. Add the Lambda function as a target for the rule
#### Example Lambda function handler
For a complete example of a Lambda function that processes contact state change events, see the `GroundStationCloudWatchEventHandlerLambda` resource in the `AquaSnppJpssTerraDigIF.yml` CloudFormation template. This template is available in the AWS Ground Station customer onboarding Amazon S3 bucket. For instructions on accessing this template, see the [Putting it together](examples.pbs-data-dataflow-endpoint.md#examples.pbs-dataflow-endpoint.putting-it-together) section of the dataflow endpoint example.
#### EventBridge rule configuration
The EventBridge rule should use the following event pattern to match all Ground Station contact state changes:
```
{
"source": ["aws.groundstation"],
"detail-type": ["Ground Station Contact State Change"]
}
```
To filter for specific states only (e.g., failures), you can add a detail filter:
```
{
"source": ["aws.groundstation"],
"detail-type": ["Ground Station Contact State Change"],
"detail": {
"contactStatus": [
"FAILED_TO_SCHEDULE",
"FAILED",
"AWS_FAILED",
"AWS_CANCELLED"
]
}
}
```
For detailed instructions on creating EventBridge rules with Lambda targets, see [Creating rules that react to events](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule.html) in the Amazon EventBridge User Guide.
### Setting up EventBridge rules for automation
You can create EventBridge rules to automatically respond to contact state changes. For example:
+ Send notifications when a contact fails to schedule
+ Trigger Lambda functions to prepare resources when a contact enters `PREPASS`
+ Log contact completions for auditing purposes
For detailed information on setting up EventBridge rules for AWS Ground Station events, see [Automate AWS Ground Station with Events](monitoring.automating-events.md).
## Best practices and considerations
### Handling scheduling conflicts
Since AWS Ground Station antennas are shared resources, a contact window that appears available in `ListContacts` might be reserved by another customer before you can reserve it. To handle this:
1. Always check the contact status after reservation
1. Implement retry logic with alternative time windows
1. Consider reserving contacts well in advance when possible
1. Use EventBridge events to monitor for `FAILED_TO_SCHEDULE` states
### Ephemeris validation timing
Remember that ephemeris must be in `ENABLED` state before you can use it to reserve contacts. The validation process typically takes a few seconds to a few minutes depending on the ephemeris type and size. Always verify the ephemeris status before attempting to reserve contacts.
### Contact timing considerations
When using custom ephemeris:
+ Ensure your ephemeris covers the entire contact duration
+ For azimuth elevation ephemeris, verify that the angles keep the antenna above the [site mask](https://docs.aws.amazon.com/ground-station/latest/ug/locations.site-masks.html) throughout the contact
+ Consider ephemeris expiration times when scheduling future contacts
### API differences by ephemeris type
The `ReserveContact` API behaves differently depending on the ephemeris type:
| Ephemeris Type | satelliteArn Required | trackingOverrides Required |
| --- | --- | --- |
| TLE | Yes | No (optional) |
| OEM | Yes | No (optional) |
| Azimuth Elevation | No (optional) | Yes |
# Understand which ephemeris is used
Ephemerides have a *priority*, *expiration time*, and *enabled* flag. Together, these determine which ephemeris is used for tracking during a contact.
## TLE and OEM ephemerides
For OEM and TLE ephemerides, only one ephemeris can be active for each satellite. The ephemeris that will be used is the highest-priority enabled ephemeris whose expiration time is in the future. A larger priority value indicates a higher priority. The available contact times returned by [ListContacts](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContacts.html) are based on this ephemeris. If multiple `ENABLED` ephemerides have the same priority, the most recently created or updated ephemeris will be used.
**Note**
AWS Ground Station has a service quota on the number of `ENABLED` customer-provided ephemerides per satellite (see: [Service Quotas](https://docs.aws.amazon.com/general/latest/gr/gs.html)). To upload ephemeris data after reaching this quota, delete (using [DeleteEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DeleteEphemeris.html)) or disable (using [UpdateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_UpdateEphemeris.html)) the lowest-priority/earliest created customer-provided ephemerides.
If no ephemeris has been created, or if no ephemerides have `ENABLED` status, AWS Ground Station will use a default ephemeris for the satellite (from [Space-Track](https://www.space-track.org/)), if available. This default ephemeris has priority 0.
## Azimuth elevation ephemerides
Azimuth elevation ephemerides work differently from OEM and TLE ephemerides. Each azimuth elevation ephemeris is associated with a specific ground station and does not have a priority. When you reserve a contact with azimuth elevation ephemeris, you explicitly specify which azimuth elevation ephemeris to use through the `trackingOverrides` parameter.
Key differences for azimuth elevation ephemerides:
+ No priority system - you explicitly select the ephemeris for each contact
+ Ground station specific - each ephemeris is associated with a particular ground station
+ No automatic fallback - if the specified ephemeris is unavailable, the contact will fail
**Note**
Azimuth elevation ephemerides do not compete with OEM and TLE ephemerides. They are selected explicitly when reserving a contact and are only used when tracking overrides are specified.
## Effect of new ephemerides on previously scheduled contacts
Use the [DescribeContact API](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContact.html) to view the effects of new ephemerides on previously scheduled contacts by returning the active visibility times.
For OEM and TLE ephemerides, contacts scheduled prior to uploading a new ephemeris will retain the originally scheduled contact time, while the antenna tracking will use the active ephemeris. If the spacecraft's position, based on the active ephemeris, differs greatly from the prior ephemeris, this may result in reduced satellite contact time with the antenna due to the spacecraft operating outside the transmit/receive site mask. Therefore, we recommend that you cancel and reschedule your future contacts after you upload a new ephemeris that differs greatly from the previous ephemeris.
With the [DescribeContact API](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContact.html), you can determine the portion of your future contact that is unusable due to the spacecraft operating outside the transmit/receive site mask by comparing your scheduled contact `startTime` and `endTime` with the returned `visibilityStartTime` and `visibilityEndTime`. If you choose to cancel and reschedule your future contact(s), the contact time range must not be outside the visibility time range by more than 30 seconds. Cancelled contacts may incur costs when cancelled too close to the time of contact. For more information on cancelled contacts see: [Ground Station FAQs](https://aws.amazon.com/ground-station/faqs/).
For azimuth elevation ephemerides, scheduled contacts will use the specific ephemeris that was selected when the contact was reserved. If you need to update the azimuth elevation data for a scheduled contact, you can cancel and reschedule the contact with a new ephemeris.
# Get the current ephemeris for a satellite
The current ephemeris in use by AWS Ground Station for a specific satellite can be retrieved by calling the [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) or [ListSatellites](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListSatellites.html) actions. Both of these methods will return metadata for the ephemeris currently in use. This ephemeris metadata is different for custom ephemerides uploaded to AWS Ground Station and for default ephemerides.
**Note**
Azimuth elevation ephemerides are not associated with satellites and therefore are not returned by [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) or [ListSatellites](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListSatellites.html). To retrieve information about azimuth elevation ephemerides, use the [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) API with the specific ephemeris ID, or use [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html) to see all available ephemerides for your account.
Default Ephemerides will only include `source` and `epoch` fields. The `epoch` is the [epoch](https://en.wikipedia.org/wiki/Epoch_(astronomy)) of the [two-line element set](https://en.wikipedia.org/wiki/Two-line_element_set) that was pulled from [Space-Track](https://www.space-track.org/), and it is currently being used for computing the trajectory of the satellite.
A custom ephemeris will have a `source` value of `CUSTOMER_PROVIDED` and will include a unique identifier in the `ephemerisId` field. This unique identifier can be used to query for the ephemeris via the [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) action. An optional `name` field will be returned if the ephemeris was assigned a name during upload to AWS Ground Station via the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) action.
It is important to note that ephemerides are updated dynamically by AWS Ground Station so the returned data is only a snapshot of the ephemeris being used at the time of the call to the API.
## Example [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) return for a satellite using a default ephemeris
```
{
"satelliteId": "e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"satelliteArn": "arn:aws:groundstation::111122223333:satellite/e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"noradSatelliteID": 25994,
"groundStations": [
"Ohio 1",
"Oregon 1"
],
"currentEphemeris": {
"source": "SPACE_TRACK",
"epoch": 1528245583.619
}
}
```
## Example [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) for a satellite using a custom ephemeris
```
{
"satelliteId": "e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"satelliteArn": "arn:aws:groundstation::111122223333:satellite/e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"noradSatelliteID": 25994,
"groundStations": [
"Ohio 1",
"Oregon 1"
],
"currentEphemeris": {
"source": "CUSTOMER_PROVIDED",
"ephemerisId": "e1cfe0c7-67f9-4d98-bad2-EXAMPLE",
"name": "My Ephemeris"
}
}
```
## Listing azimuth elevation ephemerides
Since azimuth elevation ephemerides are not associated with satellites, you need to use different APIs to discover and retrieve information about them:
1. Use [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html) to list all ephemerides in your account, including azimuth elevation ephemerides. You can filter by status and ephemeris type.
1. Use [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) with a specific ephemeris ID to get detailed information about an azimuth elevation ephemeris.
1. Use [DescribeContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeContact.html) with a specific contact ID to get detailed information about an ephemeris used for the contact.
Example [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html) response including an azimuth elevation ephemeris:
```
{
"ephemerides": [
{
"ephemerisId": "abc12345-6789-def0-1234-5678EXAMPLE",
"ephemerisType": "AZ_EL",
"name": "Azimuth Elevation for Ohio Ground Station",
"status": "ENABLED",
"creationTime": 1620254718.765
},
{
"ephemerisId": "def45678-9012-abc3-4567-8901EXAMPLE",
"ephemerisType": "TLE",
"name": "TLE for Satellite 12345",
"status": "ENABLED",
"creationTime": 1620254700.123
}
]
}
```
**Note**
In the [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html) response, azimuth elevation ephemerides will have a `groundStation` field instead of a `satelliteId` field, making them easy to identify.
# Revert to default ephemeris data
When you upload custom ephemeris data it will override the default ephemerides AWS Ground Station uses for that particular satellite. AWS Ground Station does not use the default ephemeris again until there are no currently enabled, unexpired customer-provided ephemerides available for use. AWS Ground Station also does not list contacts past the expiration time of the current customer-provided ephemeris, even if there is a default ephemeris available past that expiration time.
**Note**
Azimuth elevation ephemerides do not have default values and do not override satellite ephemerides. They are explicitly selected when reserving a contact using the `trackingOverrides` parameter. If you no longer wish to use azimuth elevation ephemeris, simply reserve contacts without specifying tracking overrides, and the system will use the active satellite ephemeris instead.
## Reverting TLE and OEM ephemerides
To revert back to the default [Space-Track](https://www.space-track.org/) ephemerides for a satellite, you will need to do one of the following:
+ Delete (using [DeleteEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DeleteEphemeris.html)) or disable (using [UpdateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_UpdateEphemeris.html)) all enabled customer-provided ephemerides. You can list the customer-provided ephemerides for a satellite using [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html).
+ Wait for all existing customer-provided ephemerides to expire.
You can confirm that the default ephemeris is being used by calling [GetSatellite](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_GetSatellite.html) and verifying that the `source` of the current ephemeris for the satellite is `SPACE_TRACK`. See [Default ephemeris data](default-ephemeris-data.md) for more information on default ephemerides.
## Managing azimuth elevation ephemerides
Since azimuth elevation ephemerides are explicitly selected for each contact and are not associated with satellites, there is no concept of "reverting" to a default. Instead, you can manage azimuth elevation ephemerides as follows:
+ *To stop using azimuth elevation ephemeris:* Simply reserve new contacts without specifying `trackingOverrides` and specifying a `satelliteArn`. The contact will use the active ephemeris for the specified satellite instead.
+ *To remove unused azimuth elevation ephemerides:* Use [DeleteEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DeleteEphemeris.html) to delete azimuth elevation ephemerides that are no longer needed. Note that you cannot delete an ephemeris that is currently being used by a scheduled contact.
To list all azimuth elevation ephemerides in your account, use [ListEphemerides](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListEphemerides.html). Azimuth elevation ephemerides can be identified by the `ephemerisType` field, or by the presence of a `groundStation` field instead of a `satelliteId` field in the response.