Celestial Transit Tracker – Technical User Guide

1. Open the App

In your browser, navigate to:

https://transit-tracker.vercel.app

You should see a page titled 🌙 Moon Transit Tracker (or ☀️ Sun Transit Tracker depending on the last selection). At the top, a status banner will read “Checking flights near the Moon…” (or “…near the Sun…”).

2. Choose a Data Source (API)

The app supports four flight data sources. By default, it uses ADS-B One, but you can also use OpenSky, ADS-B Exchange, or RadarBox.

OpenSky

1. Click the OpenSky tab.
2. In the “OpenSky Login” panel:
   • Enter your Username and Password.
   • Click 🔐 Save Credentials.
   • If you don’t have an account, sign up at opensky-network.org.

ADS-B One (default)

1. Click the ADS-B One tab.
2. No login or API key required — this provider uses public data.
3. Click ✈️ Use ADS-B One to activate it.

ADS-B Exchange

1. Click the ADS-B Exchange tab.
2. Enter your API Key and Host (from RapidAPI or another provider).
3. Click 🔐 Save Settings.
4. Once saved, the app will use ADS-B Exchange for flight data.

RadarBox

1. Click the RadarBox tab.
2. This feature is coming soon.

3. Set Your Location

Below the API section, locate the Location Mode controls:

1. Location Mode dropdown:
   • Auto (GPS) – Uses your device’s geolocation. Grant permission when prompted to allow accurate latitude/longitude detection.
   • Manual – Enables three fields for manual entry:
     • Latitude (e.g., −33.8688).
     • Longitude (e.g., 151.2093).
     • Elevation (m) (default: 10).
   • 📍 Select from Map – Click on the small map preview to choose a location by tapping or dragging. This auto-fills your coordinates based on the clicked point.
2. After setting your location, click 🔄 Refresh to apply changes and fetch celestial position data (used in Moon/Sun modes).

4. Configure Tracking Parameters

In the controls panel, adjust the following settings:

1. Celestial Body dropdown:
   • Moon – Track aircraft transits across the Moon.
   • Sun – Track aircraft transits across the Sun.
2. Search Radius dropdown (in kilometers):
   • Options: 10 km, 20 km, 30 km (default), 40 km, 50 km.
   • Defines how far from the Sun/Moon’s exact azimuth/altitude to look for aircraft. Larger radius = more coverage, but more potential false positives; smaller = more precise.
3. Prediction Mode dropdown:
   • Off – Only checks current positions.
   • 5 sec, 10 sec (default), 15 sec, 20 sec, 30 sec – Project each aircraft’s path that many seconds into the future. Useful for anticipating imminent transits.
4. Auto Refresh dropdown:
   • On (default) – Automatically re-checks flights at the chosen interval.
   • Off – Only fetch data when you click 🔄 Refresh.
5. Below these controls, a live countdown appears:

   Next check in: Xs (where X is seconds until the next automatic refresh). Only active if Auto Refresh is On.

5. Adjust Detection Margin

Use the Detection Margin slider (in degrees °):

• Adjust between 1° and 50° in 0.5° steps. Default is 2.5°.
• Smaller margins catch only precise alignments (ideal for astrophotography).
• Larger margins increase coverage but allow looser "near-miss" matches.
• As you move the slider, a text label will describe the setting (e.g., “🌟 Very strict” or “😊 Moderate”).
• 🟢 Enhanced Prediction ON (default for Sun & Moon transits) enables these intelligent adjustments:
  • Zenith logic: If the Sun/Moon is high in the sky (>80°), the detection margin is auto-shrunk to reduce false positives.
  • 3D heading analysis: Uses flight direction and vertical angle to predict trajectory more precisely.
  • Offset compensation: Adjusts alignment check based on angular separation and speed, improving timing accuracy.

6. Watch Real-Time Status

• The “transitStatus” banner (below the header) displays:
  • “Checking flights near the Moon…” or “Checking flights near the Sun…” on each new check.
  • After a check: “No planes near transit” or “🚀 1 flight approaching transit!” etc.
• Below the Detection Margin, live Azimuth and Altitude of the selected body (Moon/Sun) are shown. They refresh on each 🔄 Refresh or automatically if Auto Refresh is On.
• When an aircraft’s projected path falls within the Detection Margin:
  • A visual alert appears in the status banner (e.g., “✈️ Plane ABC123 transiting the Moon!”).
  • An audible alert (beep/chime) sounds unless muted (see Step 7).
  • The event is logged in the Transit Log for review.

7. Advanced Settings & Logs

Expand the ⚙️ Advanced Settings section at the bottom to access these controls:

1. 🕒 View Transit Log
   Opens a modal/panel listing all recorded transits in the current session:
   • Timestamp
   • Flight Callsign
   • Airline
   • Altitude (AGL)
   • Offset (degrees) from Moon/Sun center
2. 🗑️ Clear Log
   Deletes all entries from the Transit Log. Does not affect previously downloaded files.
3. 📥 Download Log
   Downloads the log file in the chosen format:
   • Log Format dropdown:
     • Plain Text (.txt) – One human-readable line per event.
     • JSON (.json) – Array of objects, each representing a transit event.
   • Select desired format before clicking 📥 Download Log.
4. 🔇 Mute Alert Sound checkbox:
   • Check to disable audible alerts; visual notifications remain active.
   • Uncheck to re-enable sound.
5. 🔁 Auto Refresh Interval (sec) field:
   • Specify how often (in seconds) the app should refetch flight data—only if Auto Refresh is On.
   • Minimum: 3 sec. Default: 5 sec. Higher values lighten browser load.

8. Manual Refresh

To override the countdown and perform an immediate flight-data check (e.g., after changing location or margin), click the 🔄 Refresh button next to “Location Mode.” This forces a real-time update.

9. Interpreting Transit Alerts

• When a flight aligns within the Detection Margin, the status banner will display:

  “✈️ [Callsign] ([Airline or Reg]) is transiting the Moon in X seconds!”

• If unmuted, an audible chime plays at that moment.
• The event is instantly logged in the Transit Log. For simultaneous transits, multiple alerts appear, and each flight is listed separately in the log.

10. Downloading & Using Logs

1. Open the Transit Log via 🕒 View Transit Log to review recorded events.
2. To save a copy:
   1. Select Log Format (.txt or .json) in Advanced Settings.
   2. Click 📥 Download Log.
   3. The file (e.g., transit-log.txt or transit-log.json) saves to your Downloads folder.
3. You can import the JSON into spreadsheets or scripts, or reference the text file directly.

11. Clearing the Log

Click 🗑️ Clear Log to delete all entries from the current session’s Transit Log. Downloaded files remain unaffected.

12. Tips & Troubleshooting

• Location Permission: If using Auto (GPS) fails, confirm that your browser is permitted to access location data for transit-tracker.vercel.app.
• Manual Coordinates: If GPS is inaccurate (e.g., indoors), switch to Manual and enter precise latitude/longitude (obtainable via Google Maps or a GPS tool).
• Detection Margin: For photography, keep < 3°. For casual viewing, 5–10° is acceptable. Smaller margins minimize false positives; larger margins expand coverage.
• Prediction Mode: Higher values (e.g., 20–30 sec) can catch fast-moving jets just before transit, but very large projections may miss extremely high-speed aircraft if data latency exists. Default is 10 sec.
• API Source Differences:
  • OpenSky: Free, reliable in many regions, but coverage can vary.
  • Aviationstack: Global coverage with rate limits on free tiers.
  • ADS-B Exchange: Highly up-to-date, requires a RapidAPI subscription.
• Performance: A 3 sec Auto Refresh with a 50 km radius can tax browser resources. If you notice lag, increase the interval or decrease the radius.
• Sound Issues: If no audible alert plays, check that:
  • Your system volume is up.
  • The 🔇 Mute Alert Sound checkbox is unchecked.

13. Switching Between Moon & Sun

To toggle between Moon and Sun tracking, select the desired option from the Celestial Body dropdown. The header updates immediately (e.g., 🌙 Moon Transit Tracker or ☀️ Sun Transit Tracker), and all other settings carry over.

14. Getting Help

If you encounter bugs or have questions:

• Use the “How to Use” or “Contact” links in the footer.
• Email the creator: sandu.godakumbura@gmail.com.
• Refer to the footer’s About Us, Privacy & Cookies pages for additional resources.

15. Additional Transit Modes