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] [--exec EXECUTOR --exec_config CONFIG] [--log LOG] [--sysu SYSU] config

• config Config file path. See Configure
• -h, --help Help message
• --exec EXECUTOR Python script path containing specified executor named Executor
• --exec_config CONFIG Executor specific config file path
• --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.
ignore_checksum	Boolean	Optional. Ignore TLE checksum. false by default

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)
decim_power	Integer	Optional. Power (for 2) sample rate decimation. 0 by default
dc_block	Boolean	Optional. Enable DC correction. false by default
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. false by default. WARNING! Be careful when enabling this option! Use only if you know what it is and why!
gain	Number, Map	Optional. Receiver gain, dB. 0 by default. It could also be a dictionary {name: value}
freq_correction	Number	Optional. Receiver frequency correction, PPM. 0.0 by default
freq_correction_hz	Integer	Optional. Receiver frequency correction, Hz. 0 by default
wf_minmax	Array of Number	Optional. Waterfall min/max 2-array value. [null, null] 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
tle_strings	2-String Array	Optional. Specific TLE strings. null by default

frequencies

Each frequency object contain:

Field	Type	Description
freq	Number	Basic signal frequency, Hz
bandwidth	Number	Received signal bandwidth, Hz
demode_out_sr	Number	Optional. Demodulator out samplerate. Equal to bandwidth by default
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
iq_waterfall	Object	Optional. Write also IQ waterfall for bandwidth. none by default. See below for object info
iq_dump	Boolean	Optional. Dump and send IQ file for current bandwidth. false by default
channels	Array of Number	Required only for FSK, GFSK, GMSK mode. Demodulation baudrates, bps. [1200, 2400, 4800, 9600] by default
deviation_factor	Number	Required only for FSK, GFSK, GMSK, QUAD2FSK mode. Deviation frequency factor (baudrate / factor), 5 by default
fsk_baudrate	Integer	Optional. Required for QUAD2FSK mode.
proto_mode	String	Optional. Required for QUAD2FSK mode.
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
sstv_live_exec	Number	Optional. Only for SSTV decoder. SSTV live executing. false by default
ccc_frame_size	Number	Optional. Only for CCSDSCC decoder. Frame size, bytes. 892 by default
ccc_pre_deint	Boolean	Optional. Only for CCSDSCC decoder. Pre-Deinterleaving. false by default
ccc_diff	Boolean	Optional. Only for CCSDSCC decoder. Differential Decoding. true by default
ccc_rs_dualbasis	Boolean	Optional. Only for CCSDSCC decoder. Reed-Solomon Dualbasis. false by default
ccc_rs_interleaving	Number	Optional. Only for CCSDSCC decoder. Reed-Solomon Interleaving. 4 by default
ccc_derandomize	Boolean	Optional. Only for CCSDSCC decoder. Descrambling. true by default
quad_gain	Number	Optional. Only for QUAD, SSTV_QUAD, QUAD2FSK modes. Quadrature demodulation gain. 1.0 by default
raw_out_format	String	Optional. Only for RAW decoder. WAV output format. WAV by default
raw_out_subformat	String	Optional. Only for RAW decoder. WAV output subformat. FLOAT by default
proto_deframer	String	Optional. Only for PROTO decoder. Name of the gr-satellites deframer. See proto for detail.
proto_options	String	Optional. Only for PROTO decoder. Deframer options. See proto for detail.
ssb_bandwidth	Number	Optional. Only for SSB-family mode. SSB Bandwidth, Hz. 4600 for DSB nd 2800 foa another by default
ssb_out_sr	Number	Optional. Only for SSB-family mode. SSB out sample rate, Hz. 8000 by default

• iq_waterfall Create waterfall. Mapping with options (might be empty):
  • fft_size FFT size (int) 4096 by default
  • mode Waterfall mode:
    • MEAN (default)
    • MAX_HOLD
    • DECIMATION

modulations

• RAW
• AM
• FM
• WFM
• WFM_STEREO
• QUAD
• QUAD2FSK
• SSTV_QUAD
• QPSK
• OQPSK
• FSK
• GFSK
• GMSK
• USB
• LSB
• DSB

decoders

• RAW Saved to 2-channel float32 WAV file with bandwidth sample rate. Other parameters:
  • raw_out_format WAV output format:
    • NONE do no write
    • WAV default
    • WAV64
    • OGG
  • raw_out_subformat WAV output subformat:
    • FLOAT default
    • DOUBLE
    • PCM_16
    • PCM_24
    • PCM_32
    • PCM_U8
    • VORBIS codec, only for OGG
    • OPUS codec, only for OGG
• CSOFT Constellation Soft Decoder - 1-channel binary int8. Suitable for further processing, for example, in SatDump. Only for constellation-mode.
• CCSDSCC CCSDS Conv Concat Decoder - CADU data. Suitable for further processing, for example, in SatDump. Only for constellation-mode.
• APT Sats-Receiver APT binary file format. See APT
• SSTV SSTV saved to PNG image with EXIF. Supported modes:
  • Robot (24, 36, 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
• PROTO Satellite deframer based decoder. KISS file on output. See proto for detail. Only for *FSK mode.
• PROTO_RAW
• 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

proto

IMPORTANT: For this decoder the modulation need to be set on *FSK!

Supported deframers and their options:

• AALTO1:
  • syncword_threshold: number of bit errors allowed in syncword (int), 4 by default
• AAUSAT4:
  • syncword_threshold: 8 by default
• AISTECHSAT_2:
  • syncword_threshold: 4 by default
• AO40_FEC:
  • syncword_threshold: 8 by default
  • short_frames: use short frames (used in SMOG-P) (bool), false by default
  • crc: use CRC-16 ARC (used in SMOG-P) (bool), false by default
• AO40_UNCODED:
  • syncword_threshold: 3 by default
• ASTROCAST_FX25:
  • syncword_threshold: 8 by default
  • nrzi: use NRZ-I instead of NRZ (bool), true by default
• AX100:
  • mode: mode to use ('RS' or 'ASM') (string) REQUIRED!
  • scrambler: scrambler to use, either CCSDS or none (only for ASM mode) (str), CCSDS by default
  • syncword: syncword to use (str), 10010011000010110101000111011110 by default
  • syncword_threshold: 4 by default
• AX25:
  • g3ruh_scrambler: use G3RUH descrambling (boolean). REQUIRED!
• AX5043
• BINAR1:
  • syncword_threshold: 0 by default
• CCSDS_CONCATENATED:
  • frame_size: frame size (not including parity check bytes) (int) 223 by default
  • precoding: either none or differential for differential precoding (str) none by default
  • rs_en: If Reed-Solomon should be enabled or not (bool) true by default
  • rs_basis: Reed-Solomon basis, either conventional or dual (str) dual by default
  • rs_interleaving: Reed-Solomon interleaving depth (int) 1 by default
  • scrambler: scrambler to use, either CCSDS or none (str) CCSDS by default
  • convolutional: convolutional code to use (str) CCSDS by default. One of the following:
    • CCSDS
    • NASA-DSN
    • CCSDS uninverted
    • NASA-DSN uninverted
  • syncword_threshold: 4 by default
• CCSDS_RS:
  • frame_size: frame size (not including parity check bytes) (int) 223 by default
  • precoding: either none or differential for differential precoding (str) none by default
  • rs_en: If Reed-Solomon should be enabled or not (bool) true by default
  • rs_basis: Reed-Solomon basis, either conventional or dual (str) dual by default
  • rs_interleaving: Reed-Solomon interleaving depth (int) 1 by default
  • scrambler: scrambler to use, either CCSDS or none (str) CCSDS by default
  • syncword_threshold: 4 by default
• DIY1
• ENDUROSAT:
  • syncword_threshold: 0 by default
• ESEO:
  • syncword_threshold: 0 by default
• FOSSASAT:
  • syncword_threshold: 0 by default
• GEOSCAN:
  • syncword_threshold: 4 by default
• GRIZU263A:
  • syncword_threshold: 8 by default
• HADES:
  • syncword_threshold: 0 by default
• HSU_SAT1
• IDEASSAT
• K2SAT:
  • syncword_threshold: 0 by default
• LILACSAT_1:
  • syncword_threshold: 4 by default
• LUCKY7:
  • syncword_threshold: 1 by default
• MOBITEX:
  • nx: use NX mode (bool) false by default
• NGHAM:
  • decode_rs: use Reed-Solomon decoding (bool) false by default
  • syncword_threshold: 4 by default
• NUSAT:
  • syncword_threshold: 0 by default
• OPS_SAT
• REAKTOR_HELLO_WORLD:
  • syncword_threshold: 4 by default
  • syncword: reaktor hello world or light-1 (str) reaktor hello world by default
• SANOSAT:
  • syncword_threshold: 0 by default
• SAT_3CAT_1:
  • syncword_threshold: 4 by default
• SMOGP_RA:
  • frame_size: size of the frame before FEC (int) REQUIRED!
  • variant: variant of the protocol to use (SMOG-P (0), SMOG-1 (6) or MRC-100 (4)) (str) SMOG-1 by default
  • syncword_threshold: -1 by default. Use variant defaults when <0
• SMOGP_SIGNALLING:
  • new_protocol: enable new protocol used in SMOG-1 (bool) false by default
  • syncword_threshold: 8 by default
• SNET:
  • buggy_crc: use buggy CRC implementation of S-NET (bool) true by default
  • syncword_threshold: 4 by default
• SPINO:
  • syncword_threshold: 0 by default
• SWIATOWID:
  • syncword_threshold: 0 by default
• TT64:
  • syncword_threshold: 1 by default
• U482C:
  • syncword_threshold: 4 by default
• UA01
• USP:
  • syncword_threshold: 13 by default
• YUSAT

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