Capture Satellite Data Using AWS Ground Station
This example shows how to use Amazon® Web Services (AWS) Ground Station service from within MATLAB® to receive data from Earth observation satellite AQUA. AQUA (launched in 2002), is an Earth-orbiting National Aeronautics and Space Administration (NASA) scientific research satellite that studies precipitation, evaporation, and cycling of water. You can capture data from other satellites for which you have access permission by changing the satellite information. Using this example, you can capture satellite data as radio frequency (RF) in-phase quadrature (I/Q) samples and as demodulated and decoded data. You can further process and analyze this captured data using the Communications Toolbox™ and Image Processing Toolbox™.
AWS Ground Station is a service that enables you to manage satellite communications and process data without the need to build or maintain your own ground station infrastructure. You can get more information about AWS Ground Station service and its capabilities from the AWS Ground Station website.
AWS Ground Station currently supports low earth orbit (LEO) and medium earth orbit (MEO) satellites. These satellites are visible from the ground station for only few minutes during each pass due to their orbital cycles. Communication is possible when the satellites are within the line of sight of a ground station. AWS Ground Station establishes contact with the satellites, and then receives, demodulates, and decodes RF signals. Ground Station then pushes data to the receiver Elastic Compute Cloud (EC2) instance as a VITA 49 stream. This figure shows the end-to-end connection of the data received into Virtual Private Cloud (VPC) from the AWS Ground Station for the scheduled duration and then pushes the data to the AWS Simple Storage Service (S3) bucket.
AWS Services and Costs
This example uses these AWS services, some of which can incur costs on your AWS account. For cost estimates, see the respective pricing page websites for each of the AWS services that this example uses.
AWS lets you visualize, understand, and manage your AWS costs and usage over time. For more details, see the AWS Cost Explorer AWS website.
All the services created through this example can be released at any point of time. For more details, see Delete AWS Cloud Resources section.
Set Up Access to AWS
To capture data from satellites using the AWS Ground Station service, you must have an AWS account with permission to AWS services that this example uses. This section describes one-time setup steps to gain access to the AWS Ground Station service. If you have already completed this procedure, skip this section.
Create an IAM User
If you already have an Identity and Access Management (IAM) user, skip this section.
Step 1: Set user details
Follow the prompts to set user details. This figure shows an example of setting user details and AWS access type. Because this data capture example uses programmatic calls to AWS, so you must select Programmatic access and AWS Management Console access.
Step 2: Set permissions
Follow the prompts to set permissions. This figure shows an example of setting permissions for your IAM user. Because you must have administration permissions to access AWS services, select the
AdministratorAccess policy from the Attach existing policies directly policies.
Step 3: Add tags
Follow the prompts to add tags. This figure shows an example of adding tags to your IAM user.
Step 4: Review
Follow the prompts to review the details of your IAM user and Create user. This figure shows an example of IAM user details, permission summary, and attached policies for this example.
Step 5: Complete
This figure shows an example of viewing and downloading your IAM user security credentials. You can get your credentials using any of these options.
Click Download .csv, to download the credentials file, which includes your IAM username, access key ID, secret access key.
Click Send email, to receive an email with instructions about how to sign into the AWS Management Console.
Copy the access key ID, secret access key manually.
Request Access to Ground Station
To get access to ground station services on your account, email firstname.lastname@example.org with the NORAD ID, FCC license information (see the FCC licensing), and AWS account ID.
This figure shows a sample email to get access to AWS Ground Station service.
Create EC2 Key Pair
Create an EC2 key pair for the AWS region where you plan to receive data. The EC2 Key pair is used to connect to your EC2 instances for debugging and to get the status of the data capture.
Select Key pairs, and then click Create key pair. For more information on EC2 key pairs, see the Create a key pair using Amazon EC2 AWS website.
Specify a unique name for your EC2 key pair and select the file format as
.pemto save the private key. Click Create key pair to create an EC2 key pair.
The Key pair is created, and the private key file automatically downloads to your host PC. Save the file. This point in the process is the only point at which you have the option to save the private key file. If you lose this file or do not save it, you must repeat the process again to create new key pair.
Create S3 Bucket
Create an S3 bucket, which stores captured satellite data, by following these steps.
For more information, see the Create your first S3 bucket.
Configure AWS CLI
Download and install the latest AWS command line interface (CLI). For details, see the AWS Command Line Interface. You can control multiple AWS services using this AWS CLI.
Configure the AWS CLI using
.csv file that you downloaded in Create IAM user section. This file contains your IAM username, AWS access key ID, and AWS secret access key.
% Specify your IAM username, (for example, IAMUserName = 'yourusername') IAMUserName = "saml"; % Provide your credentials file location % (for example, C:\Work\new_user_credentials.csv) csvCredentialsFile = fullfile('C:','Work','new_user_credentials.csv'); HelperAWSConfig(IAMUserName,"csvFileName",csvCredentialsFile);
Alternatively, if you are using single sign on (SSO) or federated login, then the AWS credentials file is created in a default directory. In such cases, run this code instead.
Get Satellite List
To list the satellites accessible in the given AWS region (that is, the same region where you created the EC2 key pair in the Create EC2 Key Pair section), run this code.
% Provide the region name that you plan to use region = "us-west-2"; % List the satellites available in given region [satelliteID,groundStationName] = HelperAWSListSatellites(region);
Data Capture Setup
Create infrastructure to capture the data (such as leasing, computing resources), and load and run the software on to the leased machines.
Lease two EC2 instances (the t2.micro and m5.4xlarge instance type).
Copy the capture script and data transfer scripts to the EC2 instance.
Configure the Simple Notification Service (SNS) subscription email to get notifications at various stages of the data capture process.
Provide the EC2 key pair full file path, S3 bucket name, and notification email address to the
HelperAWSDataCaptureSetup helper function. The resources created during this process are tagged with a tag key value pair that can be used to track or control resources. To set up data capture, run this code.
% AQUA satellite ID 27424 noradID = satelliteID(1); % Provide the full path of your PEM SSH key pair name that you generated in % the 'Create EC2 Key Pair' section % (for example, ec2KeyPairFile = 'C:\Work\my-ssh-key-us-west-2.pem') ec2KeyPairFile = fullfile('C:','Work','your-ec2-key-pair-us-west-2.pem'); % Provide S3 bucket name to store the satellite data that was created in % the 'Create S3 Bucket' section, (for example, s3BucketName = 'your-s3-bucket-name') s3BucketName = "your-s3-bucket-for-us-west-2"; % Provide your email address to receive the notifications % (for example, email@example.com) notificationEmail = "firstname.lastname@example.org"; % Set up the data capture [tagKeyName,tagValueName] = HelperAWSDataCaptureSetup(noradID,ec2KeyPairFile, ... s3BucketName,notificationEmail,region);
During data capture setup, you receive two SNS topic subscription confirmation requests from the AWS Notification service. Confirm the subscription to receive further notifications.
This figure shows a sample email notification from the AWS Notification service. In the email notification, click the "Confirm subscription" link to receive SNS notifications.
After you complete the data capture set up, you receive a SNS notification. This figure shows an example of this notification.
Check the availability of the selected satellite in the given region and then schedule a contact. To get satellite available start time and available duration, run this code.
% Select a ground station (for example, groundStation = 'Ohio 1') groundStation = groundStationName(1); % Lists the available contacts in the given region and ground station [contactStartTime,contactDuration] = HelperAWSListContacts(noradID, ... groundStation,tagKeyName,tagValueName,region);
You can schedule a contact by using the
HelperAWSScheduleContact helper function with these input parameters.
Capture start time: Specify your start time of the contact.
Capture duration: Specify the duration (in seconds) to capture data.
% Provide a start time for the contact % (for example, captureStartTime ='26-Apr-2021 13:47:12') captureStartTime = contactStartTime(1); % Provide a contact duration (in seconds), making sure that the contact is available for % the given duration captureDuration = 60; % in seconds % Schedule contact. This function reserves the contact for the specified time % and captures satellite data for the specified duration. contactArn = HelperAWSScheduleContact(noradID,captureDuration, ... captureStartTime,groundStation,tagKeyName,tagValueName,region);
After scheduling a contact, you receive an AWS notification email regarding the status of your contact. This figure shows an example of successful reservation of the contact.
After Ground Station establishes contact with the satellite, you receive notifications for possible contact states like
PREPASS: Approximately 2 minutes prior to contact start, you receive an email notification indicating an upcoming pass. This figure shows an example of the ground station contact state changed to
PASS: The duration of the contact you scheduled, you receive an SNS event indicating that the capturing satellite data has started. This figure shows an example of the ground station contact state changed to
POSTPASS: After one minute of pass time, you receive an SNS event indicating the pass has finished. This figure shows an example of the ground station contact state changed to
COMPLETED: When satellite data captured successfully for the capture duration, you receive an SNS event indicating that contact has been completed successfully. This figure shows an example of the ground station contact state changed to
FAILED: If any failures occur during contact state change, then you receive an SNS event indicating that the contact has failed. In this case, contact MathWorks® technical support. For details, see contact support on the MathWorks website. This figure shows an example of the ground station contact state changed to
List Scheduled Contacts
List your scheduled contacts by running this code.
% List scheduled contacts [scheduledContactList] = HelperAWSListScheduledContacts(region);
You can cancel your scheduled contact before the scheduled time. Before doing so, review the terms and conditions for canceling a scheduled contact, as well as the associated charges and pricing. To cancel a scheduled contact, uncomment and run this code.
Get Captured Data from S3 Bucket
The raw data files (like
downlinkData___.bin) are pushed to the S3 bucket. To download the raw data from the S3 bucket, uncomment and run this code.
% % Specify the raw data file in S3 bucket % satelliteRawDataFileName = ...%_MWLCFILEREF_matlab/help/examples/satcom/win64/CaptureSatelliteDataUsingAWSGroundStationExample_26.png_MWLT__MWLCVALUE_"downlinkDemodDecode.bin"_MWLCVALUEEND_; % HelperAWSGetDataFromS3(s3BucketName,satelliteRawDataFileName);
Make another Data Capture
To schedule another data capture, repeat the steps from Data Capture Setup section.
Delete AWS Cloud Resources
After you have finished capturing data, deleting all resources is recommended to avoid incurring further cost. This action deletes all of resources that are tagged with the tag key value pair. To delete the resources, uncomment and run this code.
In case of further errors, you can delete the resources from the AWS Management Console. For example, to delete the AWS Cloud Formation Stack, follow these steps.
On the AWS Cloud Formation Console website, and select the stack to delete. The stacks created in this example are named with a prefix
DataCaptureSetupStack, and are tagged with a prefix of
Click Actions, and then click Delete from the menu that appears.
Close AWS Account
Only the AWS account root user can close an AWS account. For more information, see the Closing your AWS account AWS website.
During data capture at the scheduled time, you can connect to the EC2 instance by using this SSH command and observe the data transfer status, such as bandwidth or bytes transferred.
% Get the SSH command to connect to the EC2 instance sshCommand = HelperAWSGetSSHCmd(ec2KeyPairFile,tagKeyName,tagValueName,region);
Login to the EC2 instance using the
sshCommand to see the logs from your AWS CLI. You can track the installation and configuration of the software on the EC2 instance by checking the logs at the location
You can collect data from any of these satellites by changing the satellite NORAD ID in the data capture setup function.
NOAA 20 JPSS 1 (NORAD ID 43013): This satellite was launched in 2017 and orbits at an altitude of 825 km. It carries five sensors that are designed to study land and water.
SUOMI NPP (NORAD ID 37849): This satellite was launched in 2011 and orbits at an altitude of 883 km. It carries four sensors that are designed to provide climate measurements.
TERRA (NORAD ID 25994): This satellite was launched in 1999 and orbits at an altitude of 705 km. It carries five sensors that are designed to study the surface of the Earth.
The example uses these helper functions:
HelperAWSConfig.m: Sign to AWS CLI through MATLAB by providing IAM username
HelperAWSListSatellites.m: List available satellites in region and checks if the region has ground station
HelperAWSDataCaptureSetup.m: Set up Linux bastion and ground station stacks and then launches the EC2 instances respectively for the stacks
HelperAWSListContacts.m: List contacts present in specific region
HelperAWSScheduleContact.m: Schedule contact
HelperAWSListScheduledContacts.m: List scheduled contacts
HelperAWSCancelContact.m: Cancel scheduled contact
HelperAWSGetSSHCmd.m: Get secure shell (SSH) command to ssh into ground station Linux machine
HelperAWSCleanResources.m: Clean all stacks and unused resources in region