sgoudelis/ground-stationPublic

Browser-based ground station suite for celestial body, mission and satellite tracking, SDR reception, hardware control, and telemetry decoding

AI summary: An open-source, browser-based ground station suite for satellite tracking and telemetry decoding.

Stars
4.9K
+1 today
Forks
849
Watchers
77
Open issues
1
Open PRs
0
Contributors
~6
Commits
3.9K
Branches
3

JavaScriptGPL-3.0Created Mar 1, 2025Last push 1d agoLatest release v0.8.26+1 stars this week+36 this month

Quick answers

What is ground-station?
An open-source, browser-based ground station suite for satellite tracking and telemetry decoding.
What does ground-station do?
Ground Station provides a comprehensive, browser-based interface for managing amateur radio and satellite tracking operations. It integrates complex orbital mechanics calculations to predict satellite passes with direct hardware control of software-defined radios (SDRs) and motorized antenna rotators. The application allows users to visualize orbits, analyze SDR waterfalls, and decode complex telemetry packets directly within a web browser. By consolidating tracking, reception, and hardware management into a single platform, it eliminates the need for multiple disparate pieces of desktop software, streamlining the observation of celestial targets.
Who is ground-station for?
Amateur radio operators (hams), satellite tracking enthusiasts, and aerospace researchers who require a modern, integrated solution for predicting passes, controlling hardware, and decoding telemetry data. It requires familiarity with modern development workflows and scalable architectures.
How do I get started with ground-station?
Please consult the repository documentation for setup instructions depending on your specific hardware configuration.
How popular is ground-station on GitHub?
sgoudelis/ground-station has 4,895 stars and 849 forks on GitHub, and gained 1 stars in the last 7 days.
What license does ground-station use?
sgoudelis/ground-station is released under the GPL-3.0 license.

Star history

since Jul 29, 2026
02K4KJul 2026Sep 2026Oct 2026Nov 2026
4.9K stars as of Nov 20, 2026. Measured daily since Jul 29, 2026; GitHub no longer exposes earlier star timestamps.

Update history

5 recorded
  • Nov 16, 2026New release v0.8.26 (previously v0.8.24).
  • Nov 5, 2026New release v0.8.24 (previously v0.8.21).
  • Oct 26, 2026New release v0.8.21 (previously v0.8.19).
  • Oct 18, 2026New release v0.8.19 (previously v0.8.18).
  • Oct 9, 2026New release v0.8.18 (previously v0.8.15).

Contribution activity

commits per day, last 52 weeks
NovDecJanFebMarAprMayJunJulAugSepOctNovMonWedFri2025-11-23: 14 commits2025-11-24: 14 commits2025-11-25: 12 commits2025-11-26: 0 commits2025-11-27: 9 commits2025-11-28: 3 commits2025-11-29: 2 commits2025-11-30: 8 commits2025-12-01: 15 commits2025-12-02: 6 commits2025-12-03: 5 commits2025-12-04: 13 commits2025-12-05: 13 commits2025-12-06: 4 commits2025-12-07: 30 commits2025-12-08: 7 commits2025-12-09: 2 commits2025-12-10: 6 commits2025-12-11: 7 commits2025-12-12: 7 commits2025-12-13: 8 commits2025-12-14: 4 commits2025-12-15: 4 commits2025-12-16: 2 commits2025-12-17: 28 commits2025-12-18: 10 commits2025-12-19: 11 commits2025-12-20: 17 commits2025-12-21: 26 commits2025-12-22: 18 commits2025-12-23: 16 commits2025-12-24: 1 commit2025-12-25: 15 commits2025-12-26: 11 commits2025-12-27: 8 commits2025-12-28: 3 commits2025-12-29: 5 commits2025-12-30: 0 commits2025-12-31: 12 commits2026-01-01: 6 commits2026-01-02: 5 commits2026-01-03: 3 commits2026-01-04: 9 commits2026-01-05: 11 commits2026-01-06: 9 commits2026-01-07: 15 commits2026-01-08: 9 commits2026-01-09: 8 commits2026-01-10: 15 commits2026-01-11: 16 commits2026-01-12: 16 commits2026-01-13: 13 commits2026-01-14: 3 commits2026-01-15: 16 commits2026-01-16: 5 commits2026-01-17: 6 commits2026-01-18: 5 commits2026-01-19: 7 commits2026-01-20: 4 commits2026-01-21: 5 commits2026-01-22: 9 commits2026-01-23: 18 commits2026-01-24: 14 commits2026-01-25: 12 commits2026-01-26: 5 commits2026-01-27: 10 commits2026-01-28: 9 commits2026-01-29: 3 commits2026-01-30: 4 commits2026-01-31: 6 commits2026-02-01: 0 commits2026-02-02: 3 commits2026-02-03: 8 commits2026-02-04: 4 commits2026-02-05: 6 commits2026-02-06: 1 commit2026-02-07: 5 commits2026-02-08: 12 commits2026-02-09: 13 commits2026-02-10: 1 commit2026-02-11: 6 commits2026-02-12: 0 commits2026-02-13: 0 commits2026-02-14: 1 commit2026-02-15: 6 commits2026-02-16: 1 commit2026-02-17: 4 commits2026-02-18: 0 commits2026-02-19: 1 commit2026-02-20: 0 commits2026-02-21: 0 commits2026-02-22: 0 commits2026-02-23: 4 commits2026-02-24: 3 commits2026-02-25: 5 commits2026-02-26: 3 commits2026-02-27: 2 commits2026-02-28: 6 commits2026-03-01: 4 commits2026-03-02: 0 commits2026-03-03: 6 commits2026-03-04: 5 commits2026-03-05: 3 commits2026-03-06: 0 commits2026-03-07: 5 commits2026-03-08: 0 commits2026-03-09: 0 commits2026-03-10: 0 commits2026-03-11: 0 commits2026-03-12: 4 commits2026-03-13: 1 commit2026-03-14: 0 commits2026-03-15: 0 commits2026-03-16: 0 commits2026-03-17: 0 commits2026-03-18: 2 commits2026-03-19: 0 commits2026-03-20: 0 commits2026-03-21: 2 commits2026-03-22: 5 commits2026-03-23: 0 commits2026-03-24: 0 commits2026-03-25: 1 commit2026-03-26: 2 commits2026-03-27: 0 commits2026-03-28: 0 commits2026-03-29: 0 commits2026-03-30: 2 commits2026-03-31: 2 commits2026-04-01: 6 commits2026-04-02: 18 commits2026-04-03: 8 commits2026-04-04: 8 commits2026-04-05: 21 commits2026-04-06: 11 commits2026-04-07: 16 commits2026-04-08: 11 commits2026-04-09: 17 commits2026-04-10: 4 commits2026-04-11: 16 commits2026-04-12: 1 commit2026-04-13: 3 commits2026-04-14: 3 commits2026-04-15: 9 commits2026-04-16: 5 commits2026-04-17: 5 commits2026-04-18: 9 commits2026-04-19: 3 commits2026-04-20: 1 commit2026-04-21: 5 commits2026-04-22: 10 commits2026-04-23: 13 commits2026-04-24: 21 commits2026-04-25: 25 commits2026-04-26: 15 commits2026-04-27: 10 commits2026-04-28: 7 commits2026-04-29: 6 commits2026-04-30: 0 commits2026-05-01: 1 commit2026-05-02: 1 commit2026-05-03: 6 commits2026-05-04: 2 commits2026-05-05: 13 commits2026-05-06: 7 commits2026-05-07: 8 commits2026-05-08: 12 commits2026-05-09: 11 commits2026-05-10: 22 commits2026-05-11: 10 commits2026-05-12: 2 commits2026-05-13: 0 commits2026-05-14: 6 commits2026-05-15: 6 commits2026-05-16: 2 commits2026-05-17: 1 commit2026-05-18: 0 commits2026-05-19: 5 commits2026-05-20: 28 commits2026-05-21: 2 commits2026-05-22: 0 commits2026-05-23: 1 commit2026-05-24: 0 commits2026-05-25: 0 commits2026-05-26: 0 commits2026-05-27: 3 commits2026-05-28: 1 commit2026-05-29: 2 commits2026-05-30: 2 commits2026-05-31: 8 commits2026-06-01: 0 commits2026-06-02: 19 commits2026-06-03: 0 commits2026-06-04: 8 commits2026-06-05: 9 commits2026-06-06: 0 commits2026-06-07: 4 commits2026-06-08: 7 commits2026-06-09: 17 commits2026-06-10: 3 commits2026-06-11: 12 commits2026-06-12: 2 commits2026-06-13: 5 commits2026-06-14: 12 commits2026-06-15: 7 commits2026-06-16: 7 commits2026-06-17: 2 commits2026-06-18: 5 commits2026-06-19: 1 commit2026-06-20: 23 commits2026-06-21: 11 commits2026-06-22: 4 commits2026-06-23: 3 commits2026-06-24: 1 commit2026-06-25: 12 commits2026-06-26: 8 commits2026-06-27: 10 commits2026-06-28: 10 commits2026-06-29: 3 commits2026-06-30: 15 commits2026-07-01: 3 commits2026-07-02: 7 commits2026-07-03: 8 commits2026-07-04: 3 commits2026-07-05: 16 commits2026-07-06: 14 commits2026-07-07: 13 commits2026-07-08: 2 commits2026-07-09: 8 commits2026-07-10: 1 commit2026-07-11: 0 commits2026-07-12: 1 commit2026-07-13: 0 commits2026-07-14: 0 commits2026-07-15: 0 commits2026-07-16: 7 commits2026-07-17: 0 commits2026-07-18: 0 commits2026-07-19: 0 commits2026-07-20: 0 commits2026-07-21: 0 commits2026-07-22: 0 commits2026-07-23: 0 commits2026-07-24: 0 commits2026-07-25: 0 commits2026-07-26: 0 commits2026-07-27: 0 commits2026-07-28: 0 commits2026-07-29: 0 commits2026-07-30: 0 commits2026-07-31: 1 commit2026-08-01: 5 commits2026-08-02: 1 commit2026-08-03: 3 commits2026-08-04: 0 commits2026-08-05: 1 commit2026-08-06: 0 commits2026-08-07: 0 commits2026-08-08: 0 commits2026-08-09: 0 commits2026-08-10: 0 commits2026-08-11: 0 commits2026-08-12: 0 commits2026-08-13: 0 commits2026-08-14: 0 commits2026-08-15: 0 commits2026-08-16: 4 commits2026-08-17: 0 commits2026-08-18: 0 commits2026-08-19: 7 commits2026-08-20: 0 commits2026-08-21: 0 commits2026-08-22: 0 commits2026-08-23: 1 commit2026-08-24: 5 commits2026-08-25: 1 commit2026-08-26: 9 commits2026-08-27: 3 commits2026-08-28: 11 commits2026-08-29: 13 commits2026-08-30: 1 commit2026-08-31: 2 commits2026-09-01: 5 commits2026-09-02: 4 commits2026-09-03: 0 commits2026-09-04: 1 commit2026-09-05: 0 commits2026-09-06: 5 commits2026-09-07: 1 commit2026-09-08: 0 commits2026-09-09: 8 commits2026-09-10: 0 commits2026-09-11: 8 commits2026-09-12: 6 commits2026-09-13: 0 commits2026-09-14: 7 commits2026-09-15: 13 commits2026-09-16: 1 commit2026-09-17: 0 commits2026-09-18: 9 commits2026-09-19: 3 commits2026-09-20: 1 commit2026-09-21: 1 commit2026-09-22: 14 commits2026-09-23: 1 commit2026-09-24: 2 commits2026-09-25: 13 commits2026-09-26: 4 commits2026-09-27: 11 commits2026-09-28: 12 commits2026-09-29: 9 commits2026-09-30: 17 commits2026-10-01: 2 commits2026-10-02: 8 commits2026-10-03: 16 commits2026-10-04: 12 commits2026-10-05: 10 commits2026-10-06: 9 commits2026-10-07: 9 commits2026-10-08: 7 commits2026-10-09: 1 commit2026-10-10: 1 commit2026-10-11: 4 commits2026-10-12: 0 commits2026-10-13: 12 commits2026-10-14: 5 commits2026-10-15: 15 commits2026-10-16: 1 commit2026-10-17: 10 commits2026-10-18: 5 commits2026-10-19: 1 commit2026-10-20: 4 commits2026-10-21: 0 commits2026-10-22: 3 commits2026-10-23: 7 commits2026-10-24: 19 commits2026-10-25: 3 commits2026-10-26: 16 commits2026-10-27: 6 commits2026-10-28: 3 commits2026-10-29: 9 commits2026-10-30: 13 commits2026-10-31: 12 commits2026-11-01: 29 commits2026-11-02: 27 commits2026-11-03: 17 commits2026-11-04: 18 commits2026-11-05: 24 commits2026-11-06: 22 commits2026-11-07: 13 commits2026-11-08: 5 commits2026-11-09: 21 commits2026-11-10: 6 commits2026-11-11: 1 commit2026-11-12: 14 commits2026-11-13: 0 commits2026-11-14: 0 commits2026-11-15: 0 commits2026-11-16: 0 commits2026-11-17: 0 commits2026-11-18: 0 commits2026-11-19: 0 commits2026-11-20: 0 commits2026-11-21: 0 commits
2,187 commits in the last yearLessMore

Signals and awards

derived from tracked data
  • Very active

    2,187 commits in 52 weeks

  • Continuous integration

    Automated checks passing

What ground-station does

Ground Station provides a comprehensive, browser-based interface for managing amateur radio and satellite tracking operations. It integrates complex orbital mechanics calculations to predict satellite passes with direct hardware control of software-defined radios (SDRs) and motorized antenna rotators. The application allows users to visualize orbits, analyze SDR waterfalls, and decode complex telemetry packets directly within a web browser. By consolidating tracking, reception, and hardware management into a single platform, it eliminates the need for multiple disparate pieces of desktop software, streamlining the observation of celestial targets.

Amateur radio operators (hams), satellite tracking enthusiasts, and aerospace researchers who require a modern, integrated solution for predicting passes, controlling hardware, and decoding telemetry data. It requires familiarity with modern development workflows and scalable architectures.

  • Browser-based UI: Offers a modern, unified dashboard accessible from any device on the network.
  • Real-time tracking: Visualizes satellite orbits and calculates precise pass geometries using TLE data.
  • SDR integration: Directly receives, records, and analyzes radio signals with built-in waterfall displays.
  • Automated hardware control: Steers motorized antenna rotators (azimuth/elevation) to track satellites automatically as they pass.
  • Telemetry decoding: Features built-in parsers for protocols like AX.25 and raw-IQ APRS to decode satellite data on the fly.

Where teams use it

Amateur satellite tracking

Automating the tracking and reception of signals from low Earth orbit amateur satellites during brief overhead passes.

Telemetry data collection

Decoding and recording atmospheric data transmitted from high-altitude weather balloons.

Remote station operation

Controlling a fully equipped radio ground station remotely over a local network via the web browser interface.

Educational demonstrations

Visualizing orbital mechanics and radio frequency reception in real-time for university aerospace programs.

Getting started: Please consult the repository documentation for setup instructions depending on your specific hardware configuration.

README

main branch

Ground Station

Tests License: GPL v3 Release Last Release Last Commit Sponsor

Ground Station is an open-source, browser-based application for tracking satellites and celestial targets, controlling station hardware, and receiving, decoding, and recording SDR signals. Built for amateur radio operators, satellite enthusiasts, and researchers, it brings orbit visualization, multi-target tracking consoles, SDR waterfall analysis, packet and telemetry decoding, scheduled observations, and hardware management into a single web interface.

Recent Releases

  • v0.8.26 (2026-11-12): Added an opt-in installation census with disclosed country inference, a dedicated settings card, and localized controls, and grouped system pages with routed maintenance tabs for clearer navigation. Chinese translations are now complete, thanks to a community contribution, and schedule regeneration no longer discards observations that have already started.
  • v0.8.25 (2026-11-11): This release adds live aircraft tracking with ADS-B decoding, flight instruments, playback, and altitude-aware map markers; radiosonde decoding with multi-frame RS41 parsing and per-serial capture grouping; and Meshtastic decoding with regional tuning ranges and node mapping. APRS stations gained info panels, symbol rendering, and packet history, and the Packet Map moved to MapLibre with a live mode, transmitter context actions, and column management. The waterfall gained SDR detachment with background streaming, independent receiving sessions, Soapy server management with manual probing, and Bias-T voltage safeguards, while continuous observations can now be created from live sessions and managed persistently. Manual rotator control arrived with floating draggable controls and tracker handoff, file browsing gained type-based purging and telemetry status badges, and the app adopted new Meridian branding alongside rebuilt satellite icons.
  • v0.8.24 (2026-10-30): This release adds scheduler observation conflict detection that validates shared hardware time across the observation form, satellite selector, and pass selector, plus new packet decoding, telemetry parsing, and housekeeping views with RS18S support in the USP parser. Numeric decoder parameters gain range-validated input fields, toolbar actions adapt to available space with a new responsive button, and artifact dates now consistently prefer capture time across the backend and file browser. Saved satellites and transmitters load reliably by NORAD ID despite autocomplete limits, with expanded test coverage for satellite search, scheduling validation, and decoder workflows.
  • v0.8.23 (2026-10-29): SSTV decoding is now far more robust, with new tone detection and audio resampling, and decoded images open in a reusable image viewer that works across decoded files. Satellite deletion now preserves the catalogs, groups, and schedules it shares with others, and the monitored satellite dialog falls back to option labels when translations are missing. The map re-centers on the selected position while following, solar-system scrolling no longer moves the page, and the decoded-packets drawer and file browser dialogs now scale with the viewport.
  • v0.8.22 (2026-10-26): Added LASARSAT AX.25 beacon decoding with viewer support. Satellite tracking gained observer-context updates, rotator and image-handling improvements, live navigation status indicators, and command expiration with backend epoch tracking. Earth View added map title controls for fullscreen and home centering with steadier globe fitting, and the reorganized VFO panel improves filtering and readability. LoRa decoded packets now show satellite links and refined callsign hints, while connection popovers and traffic statistics render more responsively.
  • v0.8.21 (2026-10-25): Added live and scheduled LoRa decoding with configurable receiver profiles, dynamic VFO controls, and TinyGS transmitter data in orbital synchronization. Earth View and satellite tracking now support OMM orbit propagation, and UMKA-1 USP telemetry is decoded into readable engineering values. Recording views gained transmitter frequency markers and waterfall-generation progress, while the file browser gained observation and type filters with more reliable paging. Satellite and transmitter editing, VFO transmitter locking, and scheduler dialogs also received clearer controls and responsiveness improvements.
  • v0.8.20 (2026-10-20): Ground Station has gained a documented public API with scoped access tokens, live event streams, and artifact downloads. Transcription now supports Parakeet, with Google Translate and LibreTranslate options. GNSS updates improve tuning guidance, pseudorange data, and fix handling, while transmitter settings add FSK framing and deviation controls. Observation scheduling now supports rig selection and clearer conflict choices; the file browser adds a purge preview. This update also improves SDR error reporting and lets Docker deployments configure the Nginx HTTP port with GS_HTTP_PORT.
  • v0.8.19 (2026-10-11): Expanded Simplified Chinese coverage across the current interface and made many previously hardcoded labels, prompts, tooltips, and status messages translatable. Added guidance for extending other language packs and corrected satellite service filtering so translated labels select the right data.
  • v0.8.18 (2026-10-08): Added the ability to join a live SDR stream with independent VFOs, plus improved device capability detection and controls for taking over shared SDR settings. Satellite views now show live positions and future passes, offer quicker access to recent groups, and provide more actions from pass tables. Maintenance gained release status and Docker update guidance. Voice squelch now rejects hiss more effectively, with a longer adjustable close delay and smoother FM demodulation.
  • v0.8.17 (2026-10-06): This release substantially improves interface responsiveness with incremental rendering of maps and dashboard panels, batched live-data updates, fewer unnecessary frame callbacks, and smoother VFO interactions. It also adds synchronized VFO audio controls, richer observation and decoded-file management, improved SatDump failure recovery, and refinements to waterfall, rotator, targeting, and Solar System displays.

Screenshots

Earth View

Earth view with ES'HAIL 2 selected (desktop)     Earth view with ES'HAIL 2 selected on mobile

Earth view with ES'HAIL 2 selected, showing satellite coverage and real-time group status on desktop and mobile


Celestial View

Celestial page with Io selected (desktop)     Celestial page with Io selected on mobile

Celestial page with Io selected, showing its trajectory alongside monitored celestial targets on desktop and mobile


Login Screen

Ground Station login screen (desktop)     Ground Station login screen on mobile

Login screen for user authentication before accessing the Ground Station interface


Multi-Target Tracking Console

ISS tracking with rotator and radio hardware connected (desktop)     ISS tracking with hardware connected on mobile

Multi-target tracking console focused on ISS with connected rotator and radio hardware, live telemetry, and pass predictions on desktop and mobile


Map Page — ADS-B Aircraft

Map page showing ADS-B aircraft positions and flight instruments (desktop)     Map page showing ADS-B aircraft positions on mobile

Map page showing live ADS-B aircraft positions on desktop and mobile, with aircraft details and flight instruments in the desktop view


Map Page — Radiosondes

Map page showing radiosonde positions, telemetry, and manual rotator controls (desktop)

Radiosonde map with live telemetry and manual rotator control


SDR Waterfall View

Waterfall view with live transcription

Waterfall view with live transcription overlay during active satellite communication


Waterfall Packet Decoding (GMSK)

Waterfall packet decoding view with GMSK and two VFOs

Waterfall view receiving GMSK and decoding with two VFOs


Waterfall Radiosonde Decoding

Waterfall view decoding radiosonde signals with multiple VFOs and decoded packets (desktop)

Waterfall view receiving and decoding radiosonde signals with multiple VFOs


Telemetry Packet Viewer (Hex + ASCII)

Telemetry packet viewer with hex and ASCII columns

Packet viewer showing telemetry payload bytes in hex with ASCII side-by-side


Orbital Data Synchronization

Orbital data synchronization page showing progress and added, modified, and removed items

Orbital data sync with synchronization progress and satellite and transmitter updates


SDR Hardware Management

Add SDR dialog with remote SoapySDR discovery, device probing, and antenna port labels

Add SDR dialog for discovering and configuring radio devices


File Browser & Decoders

File browser with decoded outputs and transcriptions

File browser view showing decoded weather images, packet outputs, and saved transcriptions


Scheduler — Monitored Satellites

Scheduler page showing monitored satellites, hardware, and observation tasks

Monitored satellites with hardware and tasks configured for automatic observations


DSP Topology & Performance

DSP topology and performance view

Chain of threads and processes IQ samples pass through, showing performance and data flow across the DSP pipeline


Key Features

  • Real-time Orbit Tracking: Track Earth-orbiting targets using Skyfield/SGP4 propagation from stored orbital elements.
  • Configurable Orbital Sources + Metadata Enrichment: Sync orbital data from configured sources (default CelesTrak feeds) and enrich satellites/transmitters from SatNOGS APIs.
  • Multi-Target Tracker Instances: Run multiple tracker instances in parallel (target-N slots), each with independent runtime state.
  • Automated Antenna Rotator Control: Drive connected rotators with continuous az/el updates, limit checks, and anti-thrashing retarget logic.
  • Rig Control with Doppler Correction: Control compatible rigs (rigctld/Hamlib paths) with RX/TX Doppler-corrected tuning during tracking.
  • SDR Hardware Support: RTL-SDR (USB/rtl_tcp), MiriSDR (through SoapyMiri), SoapySDR (local/remote), UHD/USRP, plus a virtual SigMF Playback SDR.
  • Live DSP Pipeline: Stream IQ to FFT/waterfall, demodulators, decoders, recorders, and browser consumers through queue-based worker orchestration.
  • Background Reception: Enable Keep receiving in background in the waterfall's SDR accordion to retain VFOs, decoders, and recordings after pressing Stop or closing the tab. Unattended VFOs hold their last frequency without Doppler updates. The first user to JOIN adopts the running observation; other viewers keep independent VFOs and can use Take control when it becomes unattended. To end an observation, uncheck Keep receiving in background before pressing Stop; other SDR participants can continue receiving. Background reception lasts until stopped or the backend shuts down; it does not resume automatically after a backend restart.
  • IQ Recording (SigMF): Record IQ as .sigmf-data + .sigmf-meta with center frequency, sample rate, session stats, and target satellite metadata.
  • SigMF Playback: Replay recorded IQ through the same processing pipeline used for live SDR operation.
  • Data Decoding + Framing Protocols: Supported decoder paths include SSTV, APRS, FSK, GFSK, GMSK, BPSK, and GNSS, with AX.25/USP/GEOSCAN framing support in the packet pipelines.
  • Radiosonde Telemetry: Automatic RS41, DFM and M10/M20 detection and decoding from the selected VFO, with binary frames, JSON telemetry and live packet display.
  • APRS Packet Decoding: Dedicated raw-IQ APRS decoding with integrated NBFM/Bell 202 demodulation, AX.25 parsing, batch-boundary recovery, and decoded packet/metadata output files.
  • Transcription Services: Demodulated-audio transcription via Gemini Live, Deepgram, or Parakeet, with optional translation and file output under backend/data/transcriptions/.
  • Scheduled Observations: APScheduler-driven AOS/LOS orchestration for automatic start/stop of tracking, SDR, decoding, recording, and transcription tasks.
  • SatDump Post-Processing: Optional SatDump processing for IQ recordings, including METEOR LRPT/HRPT pipelines.
  • Performance Monitoring: Live pipeline metrics (queue utilization, throughput, drops, and component health) streamed to the frontend.
  • Responsive Web Interface: Material-UI + Socket.IO frontend for desktop, tablet, and mobile operation.
  • Authentication + User Management: Built-in login screen with role-based access control for two user types: admins and operators.
  • Interactive Solar System View: Dedicated Solar System page with live orbital context for planets and other supported bodies.
  • Celestial Body + Mission Targeting: Track selected solar-system bodies and deep-space mission targets through NASA/JPL Horizons-backed vectors.

Scheduled Observations & Automated Pass Recording

Ground Station includes a comprehensive automated observation system that can schedule and execute satellite passes without user intervention:

  • Monitored Satellites: Define satellite monitoring templates with hardware configurations, signal parameters, and task definitions. The system automatically generates scheduled observations for all qualifying passes.
  • Automated Pass Scheduling: Automatically calculate and schedule upcoming satellite passes based on configurable criteria (minimum elevation, lookahead window). The scheduler uses APScheduler to trigger observations at AOS (Acquisition of Signal) and stop at LOS (Loss of Signal).
  • Flexible Task Composition: Each observation can include multiple concurrent tasks: IQ recording (SigMF format), audio recording (WAV), protocol decoding (AFSK, GMSK, SSTV), and optional AI transcription.
  • Hardware Orchestration: Automatically controls SDR devices, antenna rotators (with satellite tracking), and rigs (with Doppler correction) during scheduled observations.
  • Live Observation Capability: Users can observe any automated pass in real-time through the web interface - view the spectrum waterfall, listen to demodulated audio, and watch live decoder output. When using the same SDR as an automated observation, users can monitor without interference, but be aware that changing the SDR's center frequency or bandwidth will affect the ongoing observation.
  • Multi-SDR Observing: Automated observations can run on one SDR while additional SDRs record, decode, and listen to the same pass in parallel.
  • Status Management: Real-time observation status tracking (scheduled, running, completed, failed, cancelled, missed) with automatic cleanup of old completed observations.
  • Session Management: Automated observations run in isolated internal VFO sessions (namespace: "internal:<observation_id>"). When using different SDRs, user sessions and automated observations operate completely independently without any interference.

Architecture

The Ground Station application is composed of a frontend, a backend, and a set of worker processes.

High-Level System Architecture

flowchart TB
    %% Cache buster: v5-20251115-updated
    %% Frontend Layer
    A[Frontend: React + Redux + MUI<br/>- Real-time UI updates<br/>- State management<br/>- Interactive satellite maps<br/>- Spectrum & waterfall display<br/>- Audio playback & recording<br/>- IQ recording & playback controls<br/>- Decoder monitoring & output display]

    %% Backend Layer
    B[Backend: FastAPI + Socket.IO<br/>- WebSocket connections<br/>- Worker process management<br/>- Database operations<br/>- TLE data fetching<br/>- Recording & file management<br/>- Decoder lifecycle management]

    %% Worker Layer
    subgraph Workers["Worker Processes"]
        direction TB
        W1[Tracker Supervisor + Tracker Instances<br/>- One tracker instance per rotator<br/>- Antenna rotator control<br/>- Rig/radio control<br/>- Real-time tracking calculations<br/>- Hardware state management]
        W2[SDR IQ Acquisition<br/>- Raw IQ sample streaming<br/>- IQ Broadcaster pub/sub<br/>- Multi-consumer support]
        W2A[FFT Processor<br/>- Spectrum computation<br/>- Waterfall generation<br/>- Real-time FFT analysis]
        W2B[Demodulators<br/>- FM/SSB/AM modes<br/>- Normal & Internal modes<br/>- Frequency translation<br/>- Audio processing<br/>- Multi-VFO support]
        W2C[IQ Recorder<br/>- SigMF format recording<br/>- Metadata capture<br/>- Satellite info tagging<br/>- Waterfall snapshot saving]
        W2D[Decoders<br/>- SSTV image decoder ✓<br/>- AFSK packet decoder WIP<br/>- LoRa/GMSK decoders WIP<br/>- Audio Broadcaster for monitoring]
        W3[SDR Local Probe<br/>- Device discovery<br/>- Local SoapySDR enumeration<br/>- Hardware capability detection]
        W4[SDR Remote Probe<br/>- Remote SoapySDR discovery<br/>- Network device scanning<br/>- Remote capability detection]
    end

    %% Hardware Layer
    subgraph Hardware["Hardware Interfaces"]
        direction LR
        H1[Antenna Rotators<br/>- Hamlib compatible<br/>- Az/El control]
        H2[Radios/Rigs<br/>- CAT control<br/>- Frequency tuning]
        H3[Local SDR Devices<br/>- RTL-SDR<br/>- SoapySDR devices<br/>- UHD/USRP]
        H4[Remote SDR Devices<br/>- SoapyRemote<br/>- rtl_tcp servers<br/>- Network receivers]
        H5[SigMF Playback<br/>- Virtual SDR device<br/>- Recording playback<br/>- SigMF metadata reader]
    end

    %% Storage Layer
    subgraph Storage["Data Storage"]
        S1[SigMF Recordings<br/>- .sigmf-data files<br/>- .sigmf-meta files<br/>- Waterfall snapshots]
        S2[Decoded Outputs<br/>- SSTV images<br/>- Packet data]
    end

    %% External Services
    subgraph External["External Data Sources"]
        E1[TLE Data Sources<br/>- CelesTrak<br/>- SatNOGS DB]
        E2[Satellite Databases<br/>- Transmitter info<br/>- Orbital data]
    end

    %% Connections - Frontend to Backend
    A <---|Socket.IO<br/>Bidirectional| B

    %% Backend to Workers
    B ---|Message Queues<br/>Commands & Status| W1
    B ---|Message Queues<br/>Stream Control| W2
    B ---|Message Queues<br/>Discovery Requests| W3
    B ---|Message Queues<br/>Remote Scanning| W4

    %% SDR IQ Distribution via IQ Broadcaster
    W2 ---|IQ Broadcaster<br/>Subscribe| W2A
    W2 ---|IQ Broadcaster<br/>Subscribe| W2B
    W2 ---|IQ Broadcaster<br/>Subscribe| W2C
    W2 ---|IQ Broadcaster<br/>Subscribe Raw IQ| W2D

    %% Demodulator to Decoder Chain
    W2B ---|Internal Mode<br/>Audio Broadcaster| W2D

    %% Data back to Backend
    W2A ---|FFT Data<br/>Spectrum/Waterfall| B
    W2B ---|Audio Data<br/>Demodulated| B
    W2D ---|Decoded Data<br/>Images/Text/Packets| B
    W2D ---|UI Audio Stream<br/>Live Monitoring| B

    %% Recording Storage
    W2C ---|Write SigMF<br/>Recording Files| S1
    W2D ---|Write Decoded<br/>Output Files| S2

    %% Hardware Control
    W1 ---|Control Commands| H1
    W1 ---|Frequency Control| H2
    W2 ---|IQ Data Streaming| H3
    W2 ---|Network Streaming| H4
    W2 ---|Playback Source| H5
    W3 ---|Device Enumeration| H3
    W4 ---|Remote Discovery| H4

    %% Storage Access
    H5 ---|Read Files| S1
    B ---|File Management| S1
    B ---|File Management| S2

    %% External Data
    B ---|HTTP/API Requests| E1
    B ---|Database Queries| E2

    %% Dark Mode Styling
    classDef frontend fill:#1a237e,stroke:#3f51b5,stroke-width:2px,color:#ffffff
    classDef backend fill:#2e7d32,stroke:#4caf50,stroke-width:2px,color:#ffffff
    classDef worker fill:#e65100,stroke:#ff9800,stroke-width:2px,color:#ffffff
    classDef hardware fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
    classDef storage fill:#01579b,stroke:#0288d1,stroke-width:2px,color:#ffffff
    classDef external fill:#b71c1c,stroke:#f44336,stroke-width:2px,color:#ffffff

    class A frontend
    class B backend
    class W1,W2,W2A,W2B,W2C,W2D,W3,W4 worker
    class H1,H2,H3,H4,H5 hardware
    class S1,S2 storage
    class E1,E2 external

    %% Dashed borders for subgraphs
    style Workers stroke-dasharray: 5 5
    style Hardware stroke-dasharray: 5 5
    style Storage stroke-dasharray: 5 5
    style External stroke-dasharray: 5 5
Loading

Signal Processing Data Flow

This diagram shows how radio signals flow through the system from SDR hardware to decoders and UI:

flowchart TB
    %% SDR Source
    SDR[SDR Hardware<br/>RTL-SDR, SoapySDR, UHD]

    %% IQ Broadcaster
    IQB[IQ Broadcaster<br/>Pub/Sub Pattern<br/>Deep copy for each subscriber]

    %% Primary Consumers
    subgraph Consumers["IQ Consumers"]
        FFT[FFT Processor<br/>→ Spectrum Display]
        REC[IQ Recorder<br/>→ SigMF Files]
        DEMOD[Demodulator<br/>FM/SSB/AM]
        IQDEC[IQ Decoders<br/>GMSK/FSK/BPSK]
    end

    %% Demodulator Branches
    subgraph DemodBranch["Demodulator Types"]
        direction TB
        NORM[Normal Mode<br/>User Playback]
        INT[Internal Mode<br/>For Decoders]
    end

    %% Audio Broadcaster for Internal Demodulators
    AUDIOB[Audio Broadcaster<br/>Pub/Sub Pattern<br/>Deep copy for each subscriber]

    %% Decoder Chain
    subgraph DecoderChain["Audio-based Decoder Processing"]
        direction TB
        DEC[Decoder<br/>AFSK]
        UIAUDIO[UI Audio Stream<br/>Live Monitoring]
    end

    %% Output Destinations
    subgraph Outputs["Outputs"]
        SPECUI[Spectrum/Waterfall UI]
        SIGFILE[SigMF Recording Files]
        PLAYBACK[Audio Playback to User]
        DECOUT[Decoded Data<br/>Images/Text/Packets]
        AUDIOUI[UI Audio Player<br/>Decoder Monitoring]
    end

    %% Connections
    SDR -->|Raw IQ Samples| IQB
    SDR -->|Raw IQ Samples| FFT
    IQB -->|Subscribe| REC
    IQB -->|Subscribe| DEMOD
    IQB -->|Subscribe| IQDEC

    DEMOD -->|Branch| NORM
    DEMOD -->|Branch| INT

    NORM -->|Audio Queue| PLAYBACK
    INT -->|Audio Queue| AUDIOB

    AUDIOB -->|Subscribe: decoder| DEC
    AUDIOB -->|Subscribe: ui| UIAUDIO

    FFT -->|FFT Data| SPECUI
    REC -->|Write| SIGFILE
    DEC -->|Decoded Output| DECOUT
    IQDEC -->|Decoded Output| DECOUT
    UIAUDIO -->|Audio Chunks| AUDIOUI

    %% Styling
    classDef hardware fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
    classDef broadcaster fill:#d84315,stroke:#ff5722,stroke-width:3px,color:#ffffff
    classDef processor fill:#e65100,stroke:#ff9800,stroke-width:2px,color:#ffffff
    classDef output fill:#01579b,stroke:#0288d1,stroke-width:2px,color:#ffffff
    classDef decoder fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff

    class SDR hardware
    class IQB,AUDIOB broadcaster
    class FFT,REC,DEMOD,NORM,INT processor
    class SPECUI,SIGFILE,PLAYBACK,DECOUT,AUDIOUI output
    class DEC,UIAUDIO decoder
Loading
Key Concepts

IQ Broadcaster (Pub/Sub Pattern):

  • SDR produces raw IQ samples at high rate
  • IQBroadcaster distributes to multiple consumers simultaneously
  • Each subscriber gets independent queue with deep-copied samples
  • Slow consumers: messages dropped rather than blocking producer
  • Supports: FFT processor, demodulators, IQ recorder, decoders (LoRa/GMSK)

Audio Broadcaster (Decoder Pattern):

  • Only used for internal demodulators feeding decoders
  • Distributes demodulated audio to:
    • Decoder subscriber: SSTV/AFSK decoder processing
    • UI subscriber: Live audio monitoring in browser
  • Statistics tracking: delivered/dropped message counts per subscriber
  • Graceful slow consumer handling

Chain Processing Example (SSTV):

  1. SDR → IQBroadcaster → Internal FM Demodulator (SSTV)
  2. FM Demodulator → AudioBroadcaster input queue
  3. AudioBroadcaster → Decoder subscriber → SSTV Decoder → Image output
  4. AudioBroadcaster → UI subscriber → Browser audio player

Why Broadcasters?

  • Decoupling: Producers don't know about consumers
  • Scalability: Add consumers without modifying producers
  • Monitoring: Per-subscriber statistics and health monitoring
  • Reliability: Slow consumers don't block fast producers
  • Frontend: The frontend is a single-page application built with React, Redux Toolkit, and Material-UI. It communicates with the backend using a socket.io connection for real-time updates, including decoded data display and live audio monitoring.
  • Backend: The backend is a Python application built with FastAPI. It provides a REST API and a socket.io interface for the frontend. It manages worker processes, decoder lifecycle, and coordinates the pub/sub architecture for signal distribution.
  • Workers: The worker processes are responsible for the heavy lifting. They perform tasks such as satellite tracking, SDR streaming, signal demodulation, data decoding (SSTV implemented, AFSK/LoRa in development), and antenna control. Workers use IQ Broadcaster and Audio Broadcaster for efficient multi-consumer signal distribution.

Third-Party Libraries & Technologies

Backend

  • FastAPI: A modern, fast (high-performance), web framework for building APIs with Python 3.7+ based on standard Python type hints.
  • SQLAlchemy: The Python SQL Toolkit and Object Relational Mapper that gives application developers the full power and flexibility of SQL.
  • Skyfield: A modern astronomy library for Python that computes positions for the stars, planets, and satellites in orbit around the Earth.
  • NASA/JPL Horizons API: Ephemeris vectors and observer geometry for solar-system body tracking.
  • SGP4: A Python implementation of the SGP4 satellite propagation model.
  • Socket.IO: A library for real-time, bidirectional, event-based communication.
  • pyrtlsdr: A Python wrapper for the RTL-SDR library.
  • SoapySDR: A vendor and platform neutral SDR support library.
  • SatDump: Satellite decoder suite used for weather image decoding workflows.
  • RS (rs1729): Radiosonde detection and telemetry decoding for RS41, DFM and M10/M20 from VFO-centered IQ, with automatic decoder selection.
  • gr-satellites: GNU Radio out-of-tree modules for satellite communications decoding.
  • GNSS-SDR: Open-source software-defined GNSS receiver used by the GNSS decoder path.

Frontend

  • React: A JavaScript library for building user interfaces.
  • Redux Toolkit: The official, opinionated, batteries-included toolset for efficient Redux development.
  • Material-UI: A popular React UI framework with a comprehensive suite of UI tools.
  • Vite: A build tool that aims to provide a faster and leaner development experience for modern web projects.
  • Socket.IO Client: The client-side library for Socket.IO.
  • Leaflet: An open-source JavaScript library for mobile-friendly interactive maps.
  • MapLibre Maps: Open-source map rendering engine used for 2D and globe map views.
  • satellite.js: A JavaScript library to propagate satellite orbits.

SDR Device Support

Dedicated worker processes provide IQ acquisition, FFT processing, and demodulation support for multiple receiver families:

  • RTL-SDR (USB or rtl_tcp) workers
  • Airspy / Airspy HF+ native worker support (Airspy HF+ currently untested)
  • SoapySDR devices locally or through SoapyRemote: RTL-SDR, Airspy, HackRF, HydraSDR, LimeSDR, MiriSDR, PlutoSDR, UHD/USRP, and SDRplay (RSP series)
  • UHD/USRP radios via a UHD worker
  • Need another SoapySDR device? Open a GitHub issue and request support.

The SDR architecture uses a pub/sub pattern (IQ Broadcaster) to separate IQ acquisition from signal processing:

  • IQ Acquisition Workers stream raw samples to IQ Broadcaster
  • IQ Broadcaster distributes to multiple subscribers independently:
    • FFT Processor for spectrum/waterfall display
    • Demodulators (FM/SSB/AM) for audio output in normal and internal modes
    • IQ Recorder for SigMF format file capture
  • Raw IQ Decoders (BPSK, GMSK) that bypass demodulation
  • Audio Broadcaster distributes demodulated audio from internal demodulators to:
  • Data Decoders (AFSK) for signal decoding
    • UI Audio Stream for live monitoring in browser

Note: The signal processing components (demodulators, broadcasters, decoders) were developed with assistance from Claude AI (Anthropic) to handle complex DSP algorithms. These components are clearly marked in the source code and are licensed under GPL-3.0 like the rest of the project.

IQ Recording & Playback

Ground Station includes comprehensive IQ recording and playback capabilities using the SigMF (Signal Metadata Format) standard:

Recording Features

  • SigMF Format: Records IQ data as .sigmf-data files with accompanying .sigmf-meta JSON metadata
  • Automatic Metadata: Captures center frequency, sample rate, timestamp, and recording duration
  • Satellite Tracking: Automatically tags recordings with target satellite name and NORAD ID
  • Waterfall Snapshots: Saves PNG snapshots of the waterfall display alongside recordings
  • Multi-segment Support: Handles parameter changes (frequency, sample rate) as separate capture segments
  • Real-time Monitoring: Live duration counter and visual recording indicator in the UI

Playback Features

  • Virtual SDR Device: Recordings appear as "SigMF Playback" SDR in the device list
  • Full Processing Pipeline: Playback supports FFT display, demodulation, and all signal processing
  • Live-equivalent Decoding: During playback, demodulators and decoders run exactly as they do with live SDR input
  • Recording Browser: Sortable list of recordings with metadata preview (sample rate, duration, timestamp)
  • Timeline Scrubbing: A playback position slider above the waterfall status bar shows elapsed/total time and supports seeking to a target time
  • Seamless Integration: Switch between live SDR and playback without changing workflows

Automated Observations

Ground Station includes an automated observation system for scheduled satellite passes:

  • Monitored Satellites: Define satellite monitoring templates with hardware configurations, signal parameters, and task definitions.
  • Automated Pass Scheduling: Automatically calculate and schedule upcoming passes based on configurable criteria (minimum elevation, lookahead window).
  • Flexible Task Composition: Combine IQ recording (SigMF), audio recording, protocol decoding, and AI transcription in a single observation.
  • Hardware Orchestration: Control SDR devices, antenna rotators (with satellite tracking), and rigs (with Doppler correction) during scheduled runs.
  • Live Observation Capability: Watch the spectrum waterfall, listen to demodulated audio, and view live decoder output during automated passes.
  • Multi-SDR Observing: Run automated observations on one SDR while additional SDRs record, decode, and listen to the same pass in parallel.
  • Status Management: Track observation status (scheduled, running, completed, failed, cancelled, missed) with automatic cleanup of old entries.
  • Session Management: Automated observations run in isolated internal VFO sessions (namespace: "internal:<observation_id>").

Getting Started

For development setup, build steps, and testing, see DEVELOPMENT.md.

Security

Ground Station is intended for hobby use on a trusted private network with trusted administrators. Before reporting a vulnerability, read the project's security policy for its supported versions, trust boundaries, and reporting process.

Application Configuration

Optional installation census reporting is off by default. First-time setup and Settings → Feedback offer the same full disclosure and opt-in choice. Administrators can preview the payload, check delivery and withdraw consent. See census reporting and privacy details for the fields, IP-address handling, retention and local state. Performance reporting is inactive.

Ground Station backend runtime options are stored in backend/data/configs/app_config.json and are editable in the UI at Settings -> Settings.

Configuration precedence is:

  1. CLI flags (highest priority)
  2. app_config.json
  3. built-in defaults (lowest priority)

The UI also exposes when a value is currently CLI-overridden and whether a change is hot-applied or restart-required.

The Parakeet transcription endpoint is the parakeet_url backend setting. It is empty by default; set it to the base URL of your Parakeet service in Settings -> Settings -> Transcription or in app_config.json. UI changes apply to new transcription workers without a backend restart; direct file edits require a restart. Active workers keep their current endpoint until they are stopped and started again. Parakeet transcription cannot start until a URL is configured.

For Deepgram and Parakeet transcripts, choose No translation, Google Translate, or LibreTranslate in the waterfall transcription options or in a scheduled transcription task. New VFOs and tasks default to No translation; existing saved Google selections remain in place. Selecting No translation clears the target language and skips translation requests. The libretranslate_url backend setting is empty by default; set it to your LibreTranslate base URL in the same Transcription settings group. The backend queries /languages to show supported target languages and sends transcript text to /translate when LibreTranslate is selected. Gemini continues to translate through Gemini. If local translation fails, the original transcript is shown; it is never sent to Google as a fallback.

When the transcription source language is Auto, the backend identifies the language from recent original transcript text before any Deepgram or Parakeet translation. Gemini text is identified only when translation is off. The detected language appears in the waterfall subtitle title bar when there is enough text for a confident result; otherwise it remains Auto.

/settings/preferences is kept as a compatibility route and is now rendered as a tab inside the unified Settings page.

Docker

Building from Source

The repository includes a multi-stage Dockerfile that builds the React frontend and a Python environment with SDR libraries.

docker build -t ground-station .

# Option 1: Standard bridge mode (works for local SDRs)
docker run --rm -p 7000:7000 --device /dev/bus/usb ground-station

# Option 2: Host networking (required for SoapySDR remote server discovery via mDNS)
docker run --rm --network host --device /dev/bus/usb ground-station
SDRplay build dependency

The image includes the legacy SDRplay RSP API v3.15 required by SoapySDRPlay3; it does not use SDRplay's current SDRconnect installer, which has a different API/installation layout. The Dockerfile downloads a pinned archive commit and verifies its SHA-256 before installation. The archive contains the v3.15 API's amd64 and arm64 libraries, so both Docker target architectures remain supported.

The API is proprietary SDRplay software. Review and accept its included EULA before building or distributing an image that contains it. To update the archive deliberately, provide matching values for both arguments; never update only the commit or only the checksum:

docker build \
  --build-arg SDRPLAY_API_ARCHIVE_COMMIT=<immutable-commit> \
  --build-arg SDRPLAY_API_ARCHIVE_SHA256=<sha256-of-the-codeload-tarball> \
  -t ground-station .

Using Pre-built Docker Images

Pre-built multi-architecture Docker images are available for each release. For detailed instructions on using a specific release, see the Releases page.

Pull the image

# Latest release tag (recommended)
docker pull ghcr.io/sgoudelis/ground-station:<version>

# Or pull architecture-specific tags directly
docker pull ghcr.io/sgoudelis/ground-station:<version>-amd64
docker pull ghcr.io/sgoudelis/ground-station:<version>-arm64

Run the container

Option 1: With SoapySDR Remote Server Discovery (Recommended)

Uses host networking to enable mDNS discovery of SoapySDR remote servers:

# AMD64
docker run -d \
  --platform linux/amd64 \
  --network host \
  -e GS_HTTP_PORT=7000 \
  --name ground-station \
  --restart unless-stopped \
  --device=/dev/bus/usb \
  --privileged \
  -v /path/to/data:/app/backend/data \
  ghcr.io/sgoudelis/ground-station:<version>

# ARM64 (Raspberry Pi, etc)
docker run -d \
  --platform linux/arm64 \
  --network host \
  -e GS_HTTP_PORT=7000 \
  --name ground-station \
  --restart unless-stopped \
  -v /dev:/dev \
  --privileged \
  -v /path/to/data:/app/backend/data \
  ghcr.io/sgoudelis/ground-station:<version>

Option 2: Standard Bridge Mode (No SoapySDR Remote Discovery)

Uses standard bridge networking with port mapping:

# AMD64
docker run -d \
  --platform linux/amd64 \
  -p 7000:7000 \
  --name ground-station \
  --restart unless-stopped \
  --device=/dev/bus/usb \
  --privileged \
  -v /path/to/data:/app/backend/data \
  ghcr.io/sgoudelis/ground-station:<version>

# ARM64 (Raspberry Pi, etc)
docker run -d \
  --platform linux/arm64 \
  -p 7000:7000 \
  --name ground-station \
  --restart unless-stopped \
  -v /dev:/dev \
  --privileged \
  -v /path/to/data:/app/backend/data \
  ghcr.io/sgoudelis/ground-station:<version>

Important Notes:

  • Replace /path/to/data with your desired data directory path
  • With host networking, change GS_HTTP_PORT=7000 to choose the HTTP port (for example, GS_HTTP_PORT=8080). Docker ignores -p in this mode.
  • With bridge networking, change the host side of -p 7000:7000 (for example, -p 8080:7000). Leave the container port at 7000.
  • The backend stays on 127.0.0.1:7001 inside the container; its port is controlled by the image startup command.
  • Option 1 (host networking) is required for discovery of SoapySDR remote servers via mDNS
  • Option 2 works for local SDRs and all other features
  • For Raspberry Pi hardware, only the Raspberry Pi 5 is recommended
  • For ARM64, using -v /dev:/dev ensures all USB devices are accessible
  • Access the web interface at http://<YOUR_HOST>:7000, or at the host port selected above.
  • While the backend initializes, a lobby page appears and opens the app automatically when it is ready.
  • For readiness checks, use GET http://<YOUR_HOST>:<HTTP_PORT>/api/ready; it returns HTTP 200 only after the backend is serving requests.
  • For TLS reverse-proxy deployments, see deploy/nginx/README.md

Private DNS and HTTPS services in Docker

Docker chooses DNS servers when a container starts; the image does not contain a fixed resolver. If your Docker daemon uses public DNS, containers cannot resolve names served only by your LAN or VPN DNS. Configure the Docker host's /etc/docker/daemon.json with "dns": ["<LAN-DNS-IP>"], then restart Docker and verify the containers' resolver settings. For a single container using --network host on a Linux host with systemd-resolved, --dns 127.0.0.53 can instead use the host's DNS stub and its split-DNS routing. With bridge networking, use a reachable LAN DNS address: 127.0.0.53 would point at the container itself. Recreate the container after changing per-container DNS options.

If a local HTTPS service uses a private certificate authority, DNS alone is not enough. Trust that CA inside the container as well. On an Ubuntu host where the CA has been installed with update-ca-certificates, one option for this Ubuntu-based image is to add -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro to docker run, so the container uses the host's trusted CA bundle.

Preparing local SDR hardware

For direct USB receivers, the host administrator must configure USB access before starting the container. See Preparing SDR Hardware on the Host for device-specific udev rules, USB passthrough, and verification steps.

Contributing

We welcome contributions! Please see the CONTRIBUTING.md file for details on how to get started.

AI-Assisted Development

Ground Station is developed with the assistance of large language model (LLM) coding agents. They are used for tasks such as implementation, debugging, testing, documentation, and code review. The project maintainer directs their work, manages architectural decisions, serves as the final reviewer of all changes, and remains responsible for what is accepted into the project.

Sponsorship

Sponsorship through GitHub Sponsors is voluntary support for the continued development and maintenance of Ground Station. It does not purchase development time, technical support, consulting, feature priority, influence over the project roadmap, or any promise of future work. Contributions and requests are considered through the project's normal process.

Acknowledgments

This project uses the SatNOGS API for transmitter information.

Contains information from the Mictronics Aircraft Database, which is made available under the ODC Attribution License. The bundled snapshot is version 529, dated 2026-11-01. Its license and notices are included with the installed database; the database remains under ODC-By separately from Ground Station's application code.

Aircraft map silhouettes and ICAO model mappings are adapted from tar1090 (GPL-2.0-or-later). The C130 silhouette is by Peter Lowden, licensed under CC BY 4.0. Supplementary icons are from Tabler (MIT, Paweł Kuna). The artwork notices include all upstream credits, pinned sources, adaptation details and bundled licenses.

License

This project is licensed under the GNU GPL v3. See the LICENSE file for details.

Visitors

View on GitHub

Recent activity

commits and pull requests

Releases and announcements

157 total
  1. v0.8.26v0.8.26Nov 12, 2026

    ## Docker Image **Version:** 0.8.26 **Environment:** production **Git Commit:** b0023aeb **Build Date:** 20261112 📖 **[View Project Documentation](https://github.com/sgoudelis/ground-station)** ### Commits in this release: - b0023aeb chore(version): bump to v0.8.26 - 73737bf1 test(setup-wizard): expect census opt-in switch to be enabled - 7b45a747 feat(feedback): improve census opt-in settings card - bfc774a6 feat(feedback): add localized settings translations - 7ba3acbf fix(feedback): derive reporting environment from deployment config - 26236dfe feat(navigation): group system pages and route maintenance tabs - 78fca5b0 feat(navigation): group system pages and route maintenance tabs - 387f45ac Pin browser tests to supported Ubuntu runner - b6d23af2 Add opt-in installation census with disclosed country inference - 555be8d4 i18n: complete and refine Chinese translations - 272c1b64 fix(scheduler): preserve started observations during regeneration ### Pull the Docker image: **For AMD64 systems:** ```bash docker pull --platform linux/amd64 ghcr.io/sgoudelis/ground-station:0.8.26 ``` **For ARM64 systems (Raspberry Pi, etc):** ```bash docker pull --platform linux/arm64 ghcr.io/sgo

  2. v0.8.25v0.8.25Nov 11, 2026

    ## Docker Image **Version:** 0.8.25 **Environment:** production **Git Commit:** 8438e309 **Build Date:** 20261111 📖 **[View Project Documentation](https://github.com/sgoudelis/ground-station)** ### Commits in this release: - 8438e309 chore(version): bump to v0.8.25 - db2dfb4c test: reflect legacy UUID schema for inserts - f362b1ca feat(earthview): add recent group visibility settings - 85c69d33 test: update scheduler transmitter option queries - e607ce7b feat(filebrowser): show APRS station paths and packet history - 06f29521 feat(scheduler): group transmitter search results by band - dd6d33ae fix(horizons): request CSV vector table with state columns - ec4e8bf6 feat(packetmap): lift aircraft markers by altitude - 2386980d fix(satellites): keep catalog controls disabled while loading - dc32441f test: stabilize frontend component queries - 20a363aa fix(packetmap): apply transmitter type filters to map markers - a91ea964 feat(packetmap): add APRS station info panel - bd611d34 fix(navigation): show continuous observation count badge in scheduler nav - a1609a0b fix(navigation): show only latest observation failure in scheduler nav - 61bb14a9 feat(navigation): show scheduled and con

  3. v0.8.24v0.8.24Oct 30, 2026

    ## Docker Image **Version:** 0.8.24 **Environment:** production **Git Commit:** 1ec3c412 **Build Date:** 20261030 📖 **[View Project Documentation](https://github.com/sgoudelis/ground-station)** ### Commits in this release: - 1ec3c412 chore(version): bump to v0.8.24 - 66efe295 **feat(scheduler): add observation conflict detection and validation across components** - Implemented `findObservationConflict` and `getObservationForPass` utilities to identify hardware conflicts and manage task times. - Updated `observation-form-dialog`, `satellite-selector`, and `pass-selector` to validate conflicting observations using the shared logic. - Enhanced transmitter configuration with `DecoderNumberField` for numeric parameter support, validation, and optional values. - Added frontend tests to cover conflict resolution, form validation, and transmitter modal behaviors. - Refined test logic to support SDR hardware changes and ensure robust validation. - 00033d72 feat(scheduler): ensure saved satellites and transmitters load correctly by NORAD ID, even with autocomplete limits - 0fd592ff chore(telemetry): remove extraneous newline in USP parser - b260d088 **feat(telemetry): enable parsing of u

  4. v0.8.23v0.8.23Oct 29, 2026

    ## Docker Image **Version:** 0.8.23 **Environment:** production **Git Commit:** d50e4b91 **Build Date:** 20261029 📖 **[View Project Documentation](https://github.com/sgoudelis/ground-station)** ### Commits in this release: - d50e4b91 chore(version): bump to v0.8.23 - 6e74f55d **feat(frontend): add reusable ImageViewerDialog for SSTV and general image previews** - df5bae01 fix(frontend): adjust dialog dimensions to use dynamic viewport height in DecodedPacketsDrawer and FileBrowser - 303372a6 **fix(frontend): adjust dialog height to improve UX in DecodedPacketsDrawer and FileBrowser** - 39539d5b **fix(backend): refine satellite deletion logic to preserve shared items** - fd08c559 **test(backend): add unit tests for satellite and orbit deletion workflows** - 3fde428a **test(filebrowser): add toast behavior tests for PurgeDialog** - 89b56aab test(scheduler): extend timeout for monitored satellite dialog retries on CI - 4ddd0caa **fix(scheduler): fallback to option label before translation lookup** - d450b7a8 **test(scheduler): add unit tests for MonitoredSatelliteDialog behavior** - 19774b2f **feat(backend): add robust SSTV signal decoding with new tone detection and audio resampl

  5. v0.8.22v0.8.22Oct 26, 2026

    ## Docker Image **Version:** 0.8.22 **Environment:** production **Git Commit:** 529d6d5a **Build Date:** 20261026 📖 **[View Project Documentation](https://github.com/sgoudelis/ground-station)** ### Commits in this release: - 529d6d5a chore(version): bump to v0.8.22 - c0c2c7d8 **feat(telemetry): add LASARSAT AX.25 beacon parser and viewer support** - e223e87c feat(frontend): enhance satellite group button styles and focus behavior - 3552de42 **feat(frontend): optimize connection popover rendering and enhance traffic stats tracking** - 02533ae0 fix(frontend): maintain scroll position in VFO settings column during tab switches - e4a8ebd7 fix(frontend): adjust tracking navigation badge positioning for better alignment - 1a5f02d6 feat(frontend): add satellite links and tooltips in LoRa decoded packets - 3ccd2fee feat(frontend): refine LoRa callsign hints in decoded packets display - 97af2798 feat(frontend): add custom padding to error dialog content for improved spacing - e25612df feat(frontend): add reusable map title controls and enable fullscreen and home centering functions - bb977830 feat(frontend): reorganize VFO panel to improve component grouping and readability - dd9e3b71 f

Code frequency

additions and deletions
+58.6K-58.6KWeek of 2025-11-23: +10,738 linesWeek of 2025-11-23: -7,048 linesWeek of 2025-11-30: +5,630 linesWeek of 2025-11-30: -2,480 linesWeek of 2025-12-07: +10,789 linesWeek of 2025-12-07: -2,662 linesWeek of 2025-12-14: +7,556 linesWeek of 2025-12-14: -2,554 linesWeek of 2025-12-21: +9,036 linesWeek of 2025-12-21: -3,682 linesWeek of 2025-12-28: +20,681 linesWeek of 2025-12-28: -8,665 linesWeek of 2026-01-04: +10,783 linesWeek of 2026-01-04: -3,602 linesWeek of 2026-01-11: +8,418 linesWeek of 2026-01-11: -2,601 linesWeek of 2026-01-18: +8,137 linesWeek of 2026-01-18: -2,384 linesWeek of 2026-01-25: +9,596 linesWeek of 2026-01-25: -7,003 linesWeek of 2026-02-01: +1,954 linesWeek of 2026-02-01: -743 linesWeek of 2026-02-08: +8,308 linesWeek of 2026-02-08: -7,618 linesWeek of 2026-02-15: +196 linesWeek of 2026-02-15: -79 linesWeek of 2026-02-22: +2,117 linesWeek of 2026-02-22: -163 linesWeek of 2026-03-01: +2,799 linesWeek of 2026-03-01: -802 linesWeek of 2026-03-08: +883 linesWeek of 2026-03-08: -323 linesWeek of 2026-03-15: +356 linesWeek of 2026-03-15: -271 linesWeek of 2026-03-22: +244 linesWeek of 2026-03-22: -17 linesWeek of 2026-03-29: +8,879 linesWeek of 2026-03-29: -7,249 linesWeek of 2026-04-05: +7,515 linesWeek of 2026-04-05: -3,489 linesWeek of 2026-04-12: +10,628 linesWeek of 2026-04-12: -1,596 linesWeek of 2026-04-19: +15,469 linesWeek of 2026-04-19: -5,371 linesWeek of 2026-04-26: +7,409 linesWeek of 2026-04-26: -2,392 linesWeek of 2026-05-03: +22,381 linesWeek of 2026-05-03: -9,964 linesWeek of 2026-05-10: +8,025 linesWeek of 2026-05-10: -2,017 linesWeek of 2026-05-17: +3,400 linesWeek of 2026-05-17: -1,120 linesWeek of 2026-05-24: +862 linesWeek of 2026-05-24: -622 linesWeek of 2026-05-31: +12,106 linesWeek of 2026-05-31: -6,653 linesWeek of 2026-06-07: +33,511 linesWeek of 2026-06-07: -15,785 linesWeek of 2026-06-14: +9,242 linesWeek of 2026-06-14: -2,547 linesWeek of 2026-06-21: +4,872 linesWeek of 2026-06-21: -8,941 linesWeek of 2026-06-28: +12,306 linesWeek of 2026-06-28: -2,243 linesWeek of 2026-07-05: +6,621 linesWeek of 2026-07-05: -1,178 linesWeek of 2026-07-12: +275 linesWeek of 2026-07-12: -15 linesWeek of 2026-07-19: +0 linesWeek of 2026-07-19: -0 linesWeek of 2026-07-26: +2,722 linesWeek of 2026-07-26: -258 linesWeek of 2026-08-02: +1,213 linesWeek of 2026-08-02: -84 linesWeek of 2026-08-09: +0 linesWeek of 2026-08-09: -0 linesWeek of 2026-08-16: +3,155 linesWeek of 2026-08-16: -1,254 linesWeek of 2026-08-23: +8,361 linesWeek of 2026-08-23: -1,747 linesWeek of 2026-08-30: +698 linesWeek of 2026-08-30: -577 linesWeek of 2026-09-06: +5,967 linesWeek of 2026-09-06: -2,087 linesWeek of 2026-09-13: +12,292 linesWeek of 2026-09-13: -2,067 linesWeek of 2026-09-20: +11,604 linesWeek of 2026-09-20: -1,770 linesWeek of 2026-09-27: +17,493 linesWeek of 2026-09-27: -6,834 linesWeek of 2026-10-04: +16,324 linesWeek of 2026-10-04: -5,935 linesWeek of 2026-10-11: +14,221 linesWeek of 2026-10-11: -2,169 linesWeek of 2026-10-18: +10,551 linesWeek of 2026-10-18: -2,995 linesWeek of 2026-10-25: +24,580 linesWeek of 2026-10-25: -7,434 linesWeek of 2026-11-01: +58,647 linesWeek of 2026-11-01: -14,577 linesWeek of 2026-11-08: +15,726 linesWeek of 2026-11-08: -2,129 linesWeek of 2026-11-15: +0 linesWeek of 2026-11-15: -0 linesNov 23, 2025Nov 15, 2026
+485.3K lines added, -175.8K removed over the last year.

Commits per week

last 52 weeks
1500Week of 2025-11-23: 54 commitsWeek of 2025-11-30: 64 commitsWeek of 2025-12-07: 67 commitsWeek of 2025-12-14: 76 commitsWeek of 2025-12-21: 95 commitsWeek of 2025-12-28: 34 commitsWeek of 2026-01-04: 76 commitsWeek of 2026-01-11: 75 commitsWeek of 2026-01-18: 62 commitsWeek of 2026-01-25: 49 commitsWeek of 2026-02-01: 27 commitsWeek of 2026-02-08: 33 commitsWeek of 2026-02-15: 12 commitsWeek of 2026-02-22: 23 commitsWeek of 2026-03-01: 23 commitsWeek of 2026-03-08: 5 commitsWeek of 2026-03-15: 4 commitsWeek of 2026-03-22: 8 commitsWeek of 2026-03-29: 44 commitsWeek of 2026-04-05: 96 commitsWeek of 2026-04-12: 35 commitsWeek of 2026-04-19: 78 commitsWeek of 2026-04-26: 40 commitsWeek of 2026-05-03: 59 commitsWeek of 2026-05-10: 48 commitsWeek of 2026-05-17: 37 commitsWeek of 2026-05-24: 8 commitsWeek of 2026-05-31: 44 commitsWeek of 2026-06-07: 50 commitsWeek of 2026-06-14: 57 commitsWeek of 2026-06-21: 49 commitsWeek of 2026-06-28: 49 commitsWeek of 2026-07-05: 54 commitsWeek of 2026-07-12: 8 commitsWeek of 2026-07-19: 0 commitsWeek of 2026-07-26: 6 commitsWeek of 2026-08-02: 5 commitsWeek of 2026-08-09: 0 commitsWeek of 2026-08-16: 11 commitsWeek of 2026-08-23: 43 commitsWeek of 2026-08-30: 13 commitsWeek of 2026-09-06: 28 commitsWeek of 2026-09-13: 33 commitsWeek of 2026-09-20: 36 commitsWeek of 2026-09-27: 75 commitsWeek of 2026-10-04: 49 commitsWeek of 2026-10-11: 47 commitsWeek of 2026-10-18: 39 commitsWeek of 2026-10-25: 62 commitsWeek of 2026-11-01: 150 commitsWeek of 2026-11-08: 47 commitsWeek of 2026-11-15: 0 commitsNov 23, 2025Nov 15, 2026
2.2K commits in the last 52 weeks.

When work happens

weekday and hour
SunMonTueWedThuFriSat036912151821Sun 0:00 — 15 commitsSun 1:00 — 2 commitsSun 2:00 — 0 commitsSun 3:00 — 0 commitsSun 4:00 — 0 commitsSun 5:00 — 3 commitsSun 6:00 — 1 commitsSun 7:00 — 6 commitsSun 8:00 — 27 commitsSun 9:00 — 44 commitsSun 10:00 — 36 commitsSun 11:00 — 44 commitsSun 12:00 — 46 commitsSun 13:00 — 28 commitsSun 14:00 — 32 commitsSun 15:00 — 38 commitsSun 16:00 — 33 commitsSun 17:00 — 54 commitsSun 18:00 — 42 commitsSun 19:00 — 65 commitsSun 20:00 — 65 commitsSun 21:00 — 62 commitsSun 22:00 — 28 commitsSun 23:00 — 21 commitsMon 0:00 — 13 commitsMon 1:00 — 0 commitsMon 2:00 — 0 commitsMon 3:00 — 0 commitsMon 4:00 — 3 commitsMon 5:00 — 0 commitsMon 6:00 — 0 commitsMon 7:00 — 6 commitsMon 8:00 — 19 commitsMon 9:00 — 10 commitsMon 10:00 — 12 commitsMon 11:00 — 15 commitsMon 12:00 — 38 commitsMon 13:00 — 33 commitsMon 14:00 — 22 commitsMon 15:00 — 28 commitsMon 16:00 — 35 commitsMon 17:00 — 31 commitsMon 18:00 — 39 commitsMon 19:00 — 35 commitsMon 20:00 — 44 commitsMon 21:00 — 66 commitsMon 22:00 — 62 commitsMon 23:00 — 29 commitsTue 0:00 — 22 commitsTue 1:00 — 0 commitsTue 2:00 — 0 commitsTue 3:00 — 0 commitsTue 4:00 — 0 commitsTue 5:00 — 1 commitsTue 6:00 — 3 commitsTue 7:00 — 7 commitsTue 8:00 — 14 commitsTue 9:00 — 41 commitsTue 10:00 — 54 commitsTue 11:00 — 39 commitsTue 12:00 — 34 commitsTue 13:00 — 41 commitsTue 14:00 — 37 commitsTue 15:00 — 40 commitsTue 16:00 — 21 commitsTue 17:00 — 31 commitsTue 18:00 — 27 commitsTue 19:00 — 27 commitsTue 20:00 — 38 commitsTue 21:00 — 50 commitsTue 22:00 — 38 commitsTue 23:00 — 19 commitsWed 0:00 — 9 commitsWed 1:00 — 0 commitsWed 2:00 — 0 commitsWed 3:00 — 0 commitsWed 4:00 — 0 commitsWed 5:00 — 0 commitsWed 6:00 — 2 commitsWed 7:00 — 5 commitsWed 8:00 — 11 commitsWed 9:00 — 13 commitsWed 10:00 — 19 commitsWed 11:00 — 21 commitsWed 12:00 — 26 commitsWed 13:00 — 20 commitsWed 14:00 — 17 commitsWed 15:00 — 23 commitsWed 16:00 — 31 commitsWed 17:00 — 25 commitsWed 18:00 — 36 commitsWed 19:00 — 35 commitsWed 20:00 — 47 commitsWed 21:00 — 54 commitsWed 22:00 — 28 commitsWed 23:00 — 33 commitsThu 0:00 — 6 commitsThu 1:00 — 2 commitsThu 2:00 — 2 commitsThu 3:00 — 1 commitsThu 4:00 — 0 commitsThu 5:00 — 1 commitsThu 6:00 — 1 commitsThu 7:00 — 5 commitsThu 8:00 — 25 commitsThu 9:00 — 26 commitsThu 10:00 — 45 commitsThu 11:00 — 40 commitsThu 12:00 — 42 commitsThu 13:00 — 28 commitsThu 14:00 — 23 commitsThu 15:00 — 22 commitsThu 16:00 — 25 commitsThu 17:00 — 37 commitsThu 18:00 — 46 commitsThu 19:00 — 46 commitsThu 20:00 — 33 commitsThu 21:00 — 36 commitsThu 22:00 — 53 commitsThu 23:00 — 22 commitsFri 0:00 — 2 commitsFri 1:00 — 2 commitsFri 2:00 — 0 commitsFri 3:00 — 0 commitsFri 4:00 — 0 commitsFri 5:00 — 2 commitsFri 6:00 — 0 commitsFri 7:00 — 6 commitsFri 8:00 — 11 commitsFri 9:00 — 21 commitsFri 10:00 — 29 commitsFri 11:00 — 34 commitsFri 12:00 — 19 commitsFri 13:00 — 14 commitsFri 14:00 — 21 commitsFri 15:00 — 17 commitsFri 16:00 — 27 commitsFri 17:00 — 15 commitsFri 18:00 — 40 commitsFri 19:00 — 63 commitsFri 20:00 — 40 commitsFri 21:00 — 47 commitsFri 22:00 — 35 commitsFri 23:00 — 31 commitsSat 0:00 — 12 commitsSat 1:00 — 0 commitsSat 2:00 — 0 commitsSat 3:00 — 0 commitsSat 4:00 — 0 commitsSat 5:00 — 3 commitsSat 6:00 — 1 commitsSat 7:00 — 9 commitsSat 8:00 — 13 commitsSat 9:00 — 23 commitsSat 10:00 — 45 commitsSat 11:00 — 33 commitsSat 12:00 — 26 commitsSat 13:00 — 38 commitsSat 14:00 — 36 commitsSat 15:00 — 33 commitsSat 16:00 — 11 commitsSat 17:00 — 32 commitsSat 18:00 — 48 commitsSat 19:00 — 40 commitsSat 20:00 — 68 commitsSat 21:00 — 56 commitsSat 22:00 — 58 commitsSat 23:00 — 31 commits
Commit volume by weekday and hour (UTC). Larger dots mean more commits.

Who is committing

last 52 weeks
Maintainer commits2,301 (100%)
Community commits8 (0%)

2,309 commits in total over the last year.

DateListRankStars gained
Mar 18, 2026daily#21+156
  • morluto/rea

    Reverse engineer anything with agents, from app behavior down to native binaries.

    471.6K stars · TypeScript

  • freeCodeCamp/freeCodeCamp

    freeCodeCamp.org's open-source codebase and curriculum. Learn math, programming, and computer science for free.

    459.4K stars · TypeScript

  • donnemartin/system-design-primer

    Learn how to design large-scale systems. Prep for the system design interview. Includes Anki flashcards.

    378.7K stars · Python

  • affaan-m/ECC

    The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

    307.9K stars · JavaScript

  • practical-tutorials/project-based-learning

    Curated list of project-based tutorials

    290.1K stars · Python

  • react/react

    The library for web and native user interfaces.

    252.8K stars · JavaScript