Sats Receiver

Satellites data receiver based on GNURadio

• About
• Requirements
• Installation
  • From source
  • From PYPI
• Usage
• Configure
  • observer
  • tle
  • receivers
    • sats
      • frequencies
        • modulations
        • decoders
          • gr-satellites
• Map Shapes
  • shapes
  • points

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