Space Track TLE Retriever Help

Introduction

As a service to the satellite user community, CelesTrak provides the Space Track TLE Retriever—a tool which allows users with an active Space Track account to easily download Space Track data sets and use them to generate standard CelesTrak data sets. The Space Track TLE Retriever is a standalone Windows-based application which can be run manually, as needed, or set up to automatically download and generate CelesTrak data sets. All downloaded data is automatically archived for the user.

Latest Version

The latest version of the Space Track TLE Retriever is Version 3.2.0.0 (2019 Jul 24). You will also need the Microsoft .NET Framework 4.7.1 Runtime, if you do not already have it installed. Information on bug fixes, known bugs, workarounds, and future enhancements can be found in the Update History.

Download Space Track TLE Retriever 3

Usage

The Space Track TLE Retriever consists of three major parts:

• A Processing section which allows the user to specify the processing configuration, download Space Track data sets, and convert Space Track data into CelesTrak data sets.
• A Space Track section which allows the user to specify their Space Track username and password, which data files to download, and which formats to use (two-line or three-line).
• A CelesTrak section which allows the user to specify which, if any, CelesTrak data sets to generate.

In its simplest form, once the user has selected which Space Track data sets to download, they need only click Download Data to check for and download all new user-specified files. To generate CelesTrak data sets, the user then simply clicks Process Data. All CelesTrak data sets are quality-checked and formatted to the community-standard TLE format, as has been the practice with all data published on CelesTrak for decades—using the latest Space Track data. These files should then be immediately ready for use in existing applications which currently rely on CelesTrak data sets.

Important Notes

• The user must have a current Space Track account to download Space Track data. The user may request an account by going to www.space-track.org. After receiving their Space Track account, the user must log in to their account manually via the Space Track web site to change their password, before using TLE Retriever for the first time.
• The user must provide a valid Space Track username and password on the Space Track tab before the Download Data button will be enabled.
• The user must download Space Track data before the Process Data button will be enabled. The user must either download the Full Catalog in the three-line format or the Full Catalog in the two-line format along with the Satellite Situation Report.

Specific detailed information on how to use the Space Track TLE Retriever is provided below.

Installation

To install the Space Track TLE Retriever, simply extract all of the files into any directory. Then double-click on TLERetriever3.exe to run.

Pull-Down Menus

• File
• Save Settings: Saves all current settings, including Space Track username and password (if "Retain username and password" is checked).
• Open My TLEs: All TLEs downloaded from Space Track are archived in the My TLEs directory under the user's (My) Documents directory. The program automatically determines where the (My) Documents directory is located and creates a My TLEs directory on startup, if one does not already exist. All Space Track data are archived under this directory by year and then by file type. This menu selection makes it easy to open the My TLEs directory for direct file access.
• Open User Data: Opens the directory that contains any user-defined data sets.
• Create Basic Job: Uses the schtasks.exe command-line interface—which is supposed to support Windows XP Pro/Windows 2003 Server and beyond—to create a basic Windows task, using the settings in the Auto Download section of the Processing tab. The user may wish to further edit these settings using Task Scheduler/Scheduled Tasks.
• Exit: Exits the program. Will prompt to save changes, if any have been made since last save.
• Web Sites
• CelesTrak: Opens the user's browser and goes to the CelesTrak main page.
• Space Track: Opens the user's browser and goes to the user's Space Track home page. The program will use the user's username and password, if available, to automatically log the user into their Space Track account. It is the user's responsibility to ensure this information is correct (the program has no way of verifying it).
• Help
• Online Help: Opens the user's browser and goes to this page.
• Check for Update: Checks CelesTrak to see whether there is a more current version of TLE Retriever available.
• About: Opens the About tab to provide basic information about the current version of TLE Retriever. Also includes an e-mail link to the author to provide user feedback.
• Send Debug Log: Opens the log file directory and the user's mail client with a pre-addressed message to send debugging information to help identify and resolve problems. Debug logs are automatically generated any time TLE Retriever is run with "Enable debug logging" checked. A new log is generated for each run, with a filename of the format yyyy-MM-dd-hhmm-debug.log.
• Open Debug Log Directory: Opens the directory where the TLE Retriever logs are stored.

Processing Tab

• Auto Download: If this box is not checked, the user must manually download and/or process the data. If this box is checked, the program will be configured to automatically download and/or process the selected data sets, by creating a shortcut in the user's Startup directory and setting up TLE Retriever to run from the System Tray.
• Initial Delay: If Auto Download is checked, this is the delay in minutes before the program begins automatically downloading and processing data. The time is measured from when the application is first run. This value can only be changed if Auto Download is checked and when it is changed, the countdown timer will be reset to the current value, for use on the next startup.
• Auto Download Frequency (per day): If Auto Download is checked, the program will automatically check for new data and/or process it one, two, three, or four times a day. Remember, the Space Track data files are currently only updated twice each day.
• Enable debug logging: To support finding the cause of program difficulties, the user may check this box to enable debug logging. The program must be restarted before logging can begin. Each time the program is restarted, the log will be reinitialized. If you experience difficulties, please follow this procedure and send me the resulting yyyy-MM-dd-hhmm-debug.log file for problem resolution.
• Stop on errors: Uncheck this box to turn off the warning messages produced when TLE Retriever runs automatically. This choice will prevent the program from stopping (e.g., if the Internet connection is temporarily unavailable) when an automatic process is running unattended (the program will simply reset and attempt to run again at the next scheduled time). Please note that if this box is unchecked, it is the user's responsibility to ensure the program is running properly, since no error messages will be produced. Otherwise, it is possible for the program to run indefinitely without ever doing anything.
• Download Data: Clicking this button will automatically log the user in to their Space Track account and begin downloading the selected data files (as indicated on the Space Track tab). If the Space Track username and password fields are blank, the user will receive a warning and be taken to the Space Track tab to enter their credentials. All files are archived in the My TLEs directory under (My) Documents, organized by year and file type. The user can access the My TLEs directory from the File menu.
• Process Data: Clicking this button will use the latest Full Catalog and SSR (if the Full Catalog is in two-line format) to build standard CelesTrak data sets (as defined on the CelesTrak tab). If these files have not yet been downloaded or are over 30 days old, the user will receive a warning and be taken to the Space Track tab to select the appropriate files for downloading. For each data set, the program checks for the appropriate data set definition file on CelesTrak to ensure the most up-to-date definition. These files consist only of the Catalog Number and CelesTrak Common Name (which can be different than that used by Space Track, to meet a specific user group's preferences). A sample for the International Space Station data set might look like:

  25544ISS (ZARYA)
  36086POISK
  37820TIANGONG 1
  38852RAIKO
  38853FITSAT-1 (NIWAKA)
  38854TECHEDSAT
  38855F-1
  38856WE-WISH
  38871SOYUZ-TMA 06M
  38975PROGRESS-M 17M
  39082PROGRESS-M 18M

  The CelesTrak Common Name may be left blank to allow for using the Space Track Common Name. All CelesTrak data sets are stored in the CelesTrak directory under My TLEs. Query files are stored locally each time CelesTrak is accessed. If these files are available locally, it is possible to generate CelesTrak data sets without Internet connectivity (assuming Space Track data was previously downloaded).

Space Track Tab

• Space Track User Information
• Username: Space Track–provided username.
• Password: Space Track–provided password.
• Retain username and password: Check this box to save your Space Track account information for future use.
• Space Track Data Sets
• TLE Data Format: Allows the user to specify whether they want to download two-line or three-line bulk data files from Space Track.
• Current Catalog Files: Allows the user to specify which, if any, of the Space Track bulk catalog files to download. NOTE: The Full Catalog data file must be downloaded (two-line or three line format) to generate CelesTrak data sets.
• Complete Daily Data: Space Track provides complete daily data files (in two-line format only) for each of the past seven days (which a slight lag). Select Yes to check for, download, and archive these files.
• Satellite Situation Report (SSR): Select Yes to download Satellite Situation Report data. This file contains information, such as satellite common name, international designator, source, launch/decay dates, and basic orbital information. NOTE: This file must be downloaded to generate CelesTrak data sets if the Full Catalog is downloaded in two-line format.

CelesTrak Tab

• CelesTrak Data Sets: All of the standard CelesTrak data sets available in the Current Data section of CelesTrak can be selected in this section. When the Process Data button is clicked, the data sets are generated from the latest Space Track data and stored in the CelesTrak directory under My TLEs. The data set definition files will be maintained current via CelesTrak. In addition to the standard choices, there is also a choice to generate a CelesTrak standard data set for the entire on-orbit catalog (Complete Catalog) using Space Track common names.
• CelesTrak File Extension: Users can choose to generate CelesTrak data sets with either .txt or .tle file extensions.

About Tab

The About tab contains basic information on the current version of TLE Retriever, the specific version of the Windows operating system being used, and the CPU being used. This information, along with screen resolution, is included in the debug logs for diagnostic purposes. There is also a link to launch the user's mail client to send feedback.

Status Bar

Status for the program will be shown in the status bar at the bottom of the application. Status includes showing when the program is accessing Space Track or downloading or processing files. It also includes warning messages which indicate when data files necessary for processing are not available. These status messages should also indicate the status of the program should an unexpected error occur and are included in the debug log when "Enable debug logging" is checked on the Processing tab.

User-Defined Data Sets

Users may create as many data sets as desired by creating files of the form [fname].query and placing them in the My TLEs\User folder. Each .query file should contain a line for each object which consists of the NORAD Catalog Number followed immediately by the common name (please be sure that each line ends with a carriage return and that there are no blank lines at the end of the file). If only the NORAD Catalog Number is provided, the program will use the Space Track Common Name. Any objects which are not found in the current catalog will be omitted. Each [fname].query file will produce an [fname].txt or .tle file in the My TLEs\User folder.

Command-Line Option

Users may run TLE Retriever on an as-needed basis by running the program with the -auto command-line option. That is:

TLERetriever3 -auto

VBScript Post Processing

Several users have expressed a need to be able to perform additional processing in support of existing software applications which may expect data in specific locations or require some other form of post processing. TLE Retriever checks for the existence of the file post.vbs in the same directory as the program, whenever it completes Process Data. The program also writes a file named newdata.log, which contains the full path name of any Space Track data downloaded the last time Download Data is run. Users may create their own post.vbs file to handle additional post-processing needs (a sample is included with the program for illustration purposes, just to show that it is running). CelesTrak will provide links to scripts developed by software developers to help them tailor their applications for their users.

Combined with the command-line option described above, these features will allow users to easily configure TLE Retriever to run on a scheduled basis (e.g., using Windows Task Scheduler/Scheduled Tasks to automatically download Space Track data sets, generate CelesTrak data sets, send e-mail notifications, and/or then prepare those files for use with their existing satellite tracking applications.

Program Shutdown

The program automatically saves the position of the form and information on the latest Full Catalog and SSR on shutdown. It will also query the user to save other settings if the form has been changed since the last time these settings were saved.

Frequently Asked Questions (FAQs)

• Can I specify a data directory other than My TLEs?
• The choice of the My TLEs folder was made for three reasons:
1. It was hoped that by defining a standard data location, directory structure, and file formats that this would make it easier for software developers to know where to check for and find TLE data on any user's system. This choice is particularly important due to the restrictions placed on redistribution of Space Track data which will prevent future applications from providing their own data.
2. With the data in a location under (My) Documents, it would be easy for the user—and many other existing Windows applications—to locate it quickly.
3. Because of the restrictions on redistribution of Space Track data, I felt the data needed to be saved in a location that was user-specific. In a secure configuration, data in the My TLEs folder would not be visible to other users of the same machine. As a result, there could be no suggestion that TLE Retriever was designed to circumvent current US public law in any way. Allowing the user to specify the location would permit the selection of locations which could easily be shared with other users. I chose this limitation to ensure the availability of TLE Retriever to CelesTrak users would not be jeopardized.
• Why do I get the error message Unable to create directory C:\My Documents\My TLEs\ 200\\?
• This problem results from the Space Track requirement that you change your password on the first login to their site. When you first receive your Space Track username and password, you must first log in to Space Track and change your password. You may then use your Space Track username and new password to run TLE Retriever.