Adding Extra TLE and OMM Orbital Data Sources (v0.8.9)

[sgoudelis]

This guide shows how to add extra orbital data feeds to Ground Station from the Orbital Data Sources page. You can select a guided CelesTrak group, load a TLE/3LE or OMM feed over HTTP, or build a self-curated Space-Track source from a list of NORAD IDs.

Ground Station uses these sources for satellite orbit data and combines the imported satellites with transmitter information from the SatNOGS API. Each source also gets a system-managed satellite group, which makes it easy to find the satellites imported from that feed.

Before adding a source

1. Use Ground Station v0.8.9 or newer.
2. Make sure the Ground Station backend can reach the source over the internet or your local network. A URL that works only in your desktop browser may not be reachable from a Docker container or remote server.
3. For a generic source, confirm which format the endpoint returns:
   • 3LE (TLE/3LE): repeating sets of a satellite name, TLE line 1, and TLE line 2.
   • OMM: OMM-XML, JSON, pretty-printed JSON, or CSV.
4. Prefer a focused feed containing the satellites you need. Sources with hundreds or thousands of satellites work, but they can make parts of the interface slower.

Orbital sources currently support Earth-orbiting objects. Adding an orbital source does not add transmitter frequencies supplied by that source; transmitter details are matched separately from SatNOGS when available.

1. Open the source editor

Open Satellites → Orbital Data Sources, select the Sources tab, and choose Add.

The Add Orbital Source dialog offers three provider types:

• CelesTrak (guided GP/CSV feeds): choose one of CelesTrak's supported groups and let Ground Station build the correct URL and format.
• Generic HTTP (Curated Lists): enter the URL of a 3LE or OMM feed.
• Space-Track (Self-Curated Lists): enter the NORAD IDs you want Ground Station to request from your Space-Track account.

2. Configure the source

Choose the section below that matches your provider.

Option A: add a CelesTrak group

Set:

• Provider: CelesTrak (guided GP/CSV feeds)
• Name: use the suggested name or enter a descriptive name such as CelesTrak - Amateur radio
• CelesTrak group: select the group you need, for example Amateur radio, CubeSats, Space stations, or Weather
• Priority: 100 is a suitable default
• Enabled: on

Ground Station constructs CelesTrak's canonical HTTPS GP/CSV URL and stores the records as OMM, so there is no URL or format to enter manually. Choose Submit when the form is complete.

CelesTrak requests are intentionally limited. After a successful response, another synchronization of that source is deferred until the two-hour interval has elapsed.

CelesTrak usage warning: Do not repeatedly synchronize, create overlapping sources, or otherwise try to work around the two-hour interval. Excessive requests can cause CelesTrak to throttle your connection and may eventually result in an access ban. An HTTP 5xx response usually means that CelesTrak's servers are overloaded or temporarily unavailable, so the error should be respected rather than treated as a prompt to retry immediately. Ground Station suspends and disables the source to prevent further requests. If fresh data is necessary, wait a few hours, check that the service has recovered, re-enable the source, and run one synchronization manually. If it returns another 5xx response, leave the source disabled and wait longer. Repeatedly re-enabling the source and requesting the same data is strongly discouraged.

Option B: add a generic TLE/3LE or OMM URL

Set:

• Provider: Generic HTTP (Curated Lists)
• Name: a short description of the feed, such as Local amateur satellites
• URL: the full http:// or https:// URL that returns the orbital records
• Format: select the format returned by the endpoint:
  • 3LE (TLE/3LE) for three-line name/TLE sets
  • OMM (OMM-XML, JSON, JSON-PP, CSV) for an OMM feed
• Priority: 100 is a suitable default
• Enabled: on

For example, a private 3LE feed might be configured as:

Name: Local amateur satellites
URL: https://example.org/orbits/amateur.txt
Format: 3LE (TLE/3LE)
Priority: 100
Enabled: on

Replace the example URL with a real endpoint that Ground Station can reach, then choose Submit.

The current generic HTTP adapter fetches unauthenticated URLs. Although the dialog displays Basic and Token fields under Advanced settings, those credentials are not sent by the generic HTTP fetcher in v0.8.9. Use an unauthenticated endpoint or the dedicated Space-Track provider.

Option C: add selected satellites from Space-Track

You need an active Space-Track account for this option. Set:

• Provider: Space-Track (Self-Curated Lists)
• Name: use the suggested name or enter a descriptive name
• NORAD IDs: enter one or more catalogue IDs separated by spaces, commas, or new lines, for example 25544, 43017, 57172
• Username: your Space-Track account identity
• Password / Token: your Space-Track account password
• Priority: 100 is a suitable default
• Enabled: on

Ground Station builds filtered Space-Track GP requests from the NORAD IDs and sends them in batches. The default format is OMM. You can select 3LE under Advanced settings if you specifically need it.

Choose Submit when the form is complete.

3. Set the priority when sources overlap

Every enabled source is processed in ascending priority order. A lower number runs first and is preferred when more than one source contains the same NORAD ID.

Keep the default 100 when the new feed does not overlap another source. If it should take precedence for duplicate satellites, give it a lower number than the competing source. Sources with the same priority are ordered by name.

4. Synchronize the orbital data

After saving the source, select the Sync Now tab and choose Synchronize. Ground Station fetches every enabled orbital source, updates the satellite catalogue and source groups, and refreshes matching transmitter information from SatNOGS.

Watch the progress and results for added, modified, and removed satellites or transmitters. A synchronization can complete with errors from one source while independent providers continue processing.

Ground Station also schedules orbital synchronization every 12 hours. Use the manual synchronization after adding or editing a source so you can verify it immediately.

5. Verify the imported satellites

After synchronization:

• Return to the Sources tab and confirm the source shows Healthy and a recent Last sync time.
• Open the satellite catalogue and search for one of the NORAD IDs or names from the new feed.
• Open Satellites → Groups and look for the system-managed group created for the source.
• Open an imported satellite and confirm that its orbit is current. Transmitters will appear when matching data is available from SatNOGS.

Select a source's sync-status chip to see its last attempt, last successful sync, HTTP status, or saved error details.

If the source does not synchronize:

• Confirm that the URL is reachable from the backend and returns 200 OK without an HTML login or error page.
• Confirm that Enabled is on.
• Check that the selected format matches the response. A 3LE feed must repeat exactly three lines per object: name, line 1, and line 2.
• For OMM, confirm that each record contains valid OMM orbit fields, including OBJECT_ID, NORAD_CAT_ID, EPOCH, inclination, node, eccentricity, argument of pericenter, mean anomaly, and mean motion.
• For Space-Track, verify the account credentials and NORAD IDs.
• If a CelesTrak source is already healthy, check whether its next request is being deferred by the two-hour interval.
• If a satellite appears with data from another source, compare the sources' Priority values; the lower number wins duplicate NORAD IDs.

Once the source reports Healthy, Ground Station will keep it in the regular orbital synchronization cycle.