cbassa/strf

Purpose and execution model

STRF is a native Linux satellite-radio tracking toolkit. It converts SDR I/Q streams into timestamped spectrograms, then supports Doppler-curve visualization, satellite identification, orbit fitting, and trace analysis. It is a collection of C command-line executables rather than a server or web application. Build/install entry points are makefile, Makefile.linux, and Makefile.osx; operational setup and command usage are in README.md.

Acquisition and spectrogram production

rffft.c is the primary ingestion entry point. It accepts complex I/Q from files, stdin pipelines, or FIFOs connected to SDR software, supports several sample encodings, and produces .bin waterfall/spectrogram artifacts. The FFT implementation is split between rffft.c, rffft_internal.c, and rffft_internal.h. This is the key boundary between external SDR/device tools (RTL-SDR, HackRF, Airspy, GNU Radio, Pluto/IIO) and STRF’s stable binary analysis format.

Spectrogram artifact format and I/O

The generated artifact begins with a human-readable fixed header followed by floating-point spectral-power samples. Shared parsing and serialization facilities are centralized in rfio.c and rfio.h; image export is handled by rfpng.c. Downstream tools consume these files rather than raw SDR streams, allowing acquisition and analysis to run separately. Python utilities in contrib/, notably contrib/spectrum_parser.py and contrib/analyze_artifact.py, provide auxiliary artifact inspection and analysis outside the C command suite.

Analysis and visualization commands

rfplot.c is the principal visualization entry point for waterfall plots and analysis of generated spectra. Related command programs provide focused processing stages: rfedit.c for editing spectral data, rffind.c for detection/identification workflows, rftrace.c for Doppler-trace handling, and rffit.c for fitting. rfinfo.c exposes artifact metadata. These tools form a file-oriented analysis pipeline around the .bin output rather than sharing a long-running process.

Orbital prediction, TLE, and site domain model

Satellite propagation and observation geometry are built around SGP4 and Two-Line Element data: sgdp4.c, sgdp4h.h, rftles.c, and rftles.h. Station/site lookup is represented by rfsites.c and rfsites.h, with default reference data in data/sites.txt; frequency reference data resides in data/frequencies.txt. rfdop.c calculates Doppler-related behavior, connecting predicted orbital motion to measured spectral traces.

TLE refresh and external services

The tleupdate executable/script is the TLE acquisition entry point. It depends on configured environment variables including ST_TLEDIR, site identity, and Space-Track credentials (ST_LOGIN), making Space-Track an important external service boundary. Satellite prediction and fitting operate on locally stored TLE files after retrieval, avoiding a runtime dependency on the remote service during normal analysis.

Native dependencies and quality boundary

The C toolchain links material scientific and graphics dependencies: FFTW for FFTs, GSL for numerical work, PGPLOT/X11 for plotting, libpng for image output, and SoX/WAV support for recordings. Numerical fitting support is represented by simplex.c, versafit.c, and deep.c. Unit tests target core binary, FFT, and TLE behavior under CMocka in tests/tests.c, tests/tests_rfio.c, and tests/tests_rftles.c.