← 返回列表

ground-station:开源一站式卫星追踪与信号本地解码工具包

聚合站 SecWiki技术 入库 2026-11-18T02:35:39

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.

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 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

Ground Station login screen (desktop)

Ground Station login screen on mobile

Login screen for user authentication before accessing the Ground Station interface

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 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

Radiosonde map with live telemetry and manual rotator control

Waterfall view with live transcription overlay during active satellite communication

Waterfall view receiving GMSK and decoding with two VFOs

Waterfall view receiving and decoding radiosonde signals with multiple VFOs

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

Orbital data sync with synchronization progress and satellite and transmitter updates

Add SDR dialog for discovering and configuring radio devices

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

Monitored satellites with hardware and tasks configured for automatic observations

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

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

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

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

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

IQ Broadcaster (Pub/Sub Pattern):

Audio Broadcaster (Decoder Pattern):

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?

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

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

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.

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

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

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

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.

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.

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

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 .

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

# 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

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:

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.

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.

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

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 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.

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.

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

原文链接:https://github.com/sgoudelis/ground-station