Skip to content

baskiton/sats-receiver

Repository files navigation

Sats Receiver

PyPI PyPI - Downloads PyPI - License
GitHub Workflow Status Codecov branch GitHub Workflow Status

Satellites data receiver based on GNURadio

About

This program is written to automate the process of receiving signals from various orbiting satellites on your SDR. The basis for digital signal processing is GNU Radio - a free software development toolkit that provides signal processing blocks to implement software-defined radios and signal-processing systems. [wikipedia]
For example, this program is perfect for receiving weather satellites like NOAA (image below).
If you have ideas or knowledge on how to improve this project, feel free to submit issues or pull requests.

Requirements

The program has only been tested on Linux. Work on Windows is not guaranteed!

  • Python>=3.10 (or lower, see below)
  • GNURadio>=3.10 (or lower if gr-soapy installed); GUI-modules is not required
  • librtlsdr (if you use RTL-SDR)

Installation

I recommended to use miniconda. So, first of all, install it.

From source

cd sats-receiver
conda create -n sats-receiver-env
conda activate sats-receiver-env
conda config --env --add channels conda-forge
conda config --env --set channel_priority strict
conda env update -f environment.yml
pip install -r requirements.txt

From PYPI

conda create -n sats-receiver-env python
conda activate sats-receiver-env
conda config --env --add channels conda-forge
conda config --env --set channel_priority strict
conda install gnuradio gnuradio-satellites
pip install sats-receiver

Usage

First, activate conda environment:
conda activate sats-receiver-env

python -u -m sats_receiver [-h, --help] [--log LOG] [--sysu SYSU] config

  • config Config file path. See Configure
  • -h, --help Help message
  • --log LOG Logging level, INFO default
  • --sysu SYSU System Usages debug info timeout in seconds, 1 hour default

For example, simple command line to launch program:
python -u -m sats_receiver /path/to/config.json
You can copy the default.json config file from the root of the repository to a location of your choice

Program home directory is ~/sats_receiver
Logfile saved to program home directory (~/sats_receiver/logs)
Tle files stored to program home directory (~/sats_receiver/tle)

Configure

The configuration file is in JSON format.
You can copy the default.json file from the root of the repository to a location of your choice and edit it.

Field Type Description
observer Object Observer/receiver parameters (see observer)
tle Object TLE data parameters (see tle)
receivers Array of Object List of receivers parameters (see receivers)

observer

Field Type Description
latitude Number Receiver Latitude, degrees
longitude Number Receiver Longitude, degrees
elevation Number or null Receiver Elevation, meters. null means that the height will be obtained from the weather information or set to 0
weather Boolean Whether to receive weather information from the Internet. The weather will be taken from the service open-meteo.com

tle

Field Type Description
url String URL to TLE file
update_period Number TLE Update period, hours.

receivers

Each receiver object contain:

Field Type Description
name String Name of the Receiver
source String String value for gr-soapy driver key, e.g. rtlsdr, lime, uhd, remote
tune Number Receiver tune frequency, Hz
samp_rate Number Receiver sample rate, Hz
output_directory String Directory to save received files. You also might specify ~ symbol to specify User home directory
sats Array of Object List of Satellites configurations (see sats)
enabled Boolean Optional. Enable or Disable this Receiver. true by default
serial String Optional. Serial number of the receiver. Empty by default
biast Boolean Optional. Bias-T enable/disable (only for RTL-SDR at this time). false by default. WARNING! Be careful when enabling this option! Use only if you know what it is and why!
gain Boolean Optional. Receiver gain, dB. 0 by default
freq_correction Number Optional. Receiver frequency correction. 0.0 by default

sats

Each satellite object contain:

Field Type Description
name String Name or NORAD number of the satellite. Note: name/norad-number must be contained in the above TLE file
frequencies Array of Object List of frequency configuration (see frequencies)
enabled Boolean Optional. Enable/Disable this frequency. true by default
min_elevation Number Optional. Elevation angle above the horizon, degrees. 0 by default. Negative number is equivalent to 0
doppler Boolean Optional. Enable/Disable doppler correction. true by default

frequencies

Each frequency object contain:

Field Type Description
freq Number Basic signal frequency, Hz
bandwidth Number Received signal bandwidth, Hz
enabled Boolean Optional. Enable/Disable this frequency. true by default
subname String Optional. Subname added to result filename. Empty by default
freq_correction Boolean Optional. Correction for basic frequency, Hz. 0 by default
mode String Optional. Modulation option (see modulations). RAW by default
decode String Optional. Decoder option (see decoders). RAW by default
channels Array of Number Required only for GMSK mode. Demodulation baudrates, bps
grs_file String Optional. Only for SATS decoder. See gr-satellites for details
grs_name String Optional. Only for SATS decoder. See gr-satellites for details
grs_norad Integer Optional. Only for SATS decoder. See gr-satellites for details
grs_tlm_decode Boolean Optional. Only for SATS decoder. Save decoded telemetry. true by default
qpsk_baudrate Number Required only for (O)QPSK mode. (O)QPSK Baudrate, bps
qpsk_excess_bw Number Optional. Only for (O)QPSK mode. (O)QPSK Excess bandwidth. 0.35 by default
qpsk_ntaps Integer Optional. Only for (O)QPSK mode. (O)QPSK number of taps. 33 by default
qpsk_costas_bw Number Optional. Only for (O)QPSK mode. (O)QPSK Costas bandwidth. 0.005 by default
sstv_wsr Number Optional. Only for SSTV decoder. SSTV work samplerate. 16000 by default
sstv_sync Number Optional. Only for SSTV decoder. SSTV syncing. true by default

modulations

  • RAW
  • AM
  • FM
  • WFM
  • WFM_STEREO
  • QUAD
  • QPSK
  • OQPSK
  • GMSK

decoders

  • RAW Saved to 2-channel float32 WAV file with bandwidth sample rate
  • CSOFT Constellation Soft Decoder - 1-channel binary int8. Suitable for further processing, for example, in SatDump
  • APT Sats-Receiver APT binary file format. See APT
  • SSTV SSTV saved to PNG image with EXIF. Supported modes:
    • Robot (24, 24, 72)
    • Martin (M1, M2, M3, M4)
    • PD (50, 90, 120, 160, 180, 240, 290)
    • Scottie (S1, S2, S3, S4)
  • SATS See gr-satellites for details
  • LRPT Not implemented yet
gr-satellites

See gr-satellites Documentation
IMPORTANT: For this decoder need to leave the modulation on RAW

This decoder need to specify one of the parameters for recognize satellite option:

  • grs_file - Path to your own SatYAML-file
  • grs_name - Satellite name (may different from sats name)
  • grs_norad - Satellite NORAD ID

List of builtin supported satellites
Additionally supported satellites can be found in the satyaml directory of this repository

Map Shapes

Map shapes config file map_shapes.json can be found at the root of this repository. Shapefiles can be downloaded from Natural Earth

Field Type Description
shapes Array of Array Optional. List of shapes data (see shapes)
shapes_dir String Optional. Only when shapes specified. Path to directory contains shapes file
points Object of Object Optional. Additional points to draw on map (see points)
line_width Number Optional. Overlay lines width, pixels. 1 by default

shapes

Each shape contain:

Offset Field Type Description
0 order Number Num in order of drawing. The more, the later it will be drawn.
1 shapefile String Filename of shapefile in shapes dir. Can be separates file or ZIP archive
2 color String or Array of Integer Color. Can be string representing (red e.g.), web hex (#abcdef e.g.) or 3-4-Array 0-255 ([0, 127, 255] e.g.)

points

Each point object has name.
If name is observer, then lonlat field is filled with lonlat from apt-file.
Each point object contain:

Field Type Description
color String or Array of Integer Color. Can be string representing (red e.g.), web hex (#abcdef e.g.) or 3-4-Array 0-255 ([0, 127, 255] e.g.)
type String Type of marker view. Can be +, o
size Integer or Array of Integer If type is + then Array with line width and line length, pixels. If type is o then Integer as radius of circle, pixels
lonlat Array of Number Optional. Only for non-observer name. 2-Array of point longitude and latitude, degrees
order Number Optional. Same as in shapes. Default to last