sats-receiver 0.1.0

Satellites data receiver based on GNU Radio

Sats Receiver

Satellites data receiver based on GNURadio

• About
• Requirements
• Installation
• Usage
• Configure
  • observer
  • tle
  • receivers
    • sats
      • frequencies
        • modulations
        • decoders
• 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

• if you need a virtual environment, you need to create it with the --system-site-packages option:
  python3 -m venv --system-site-packages venv
source venv/bin/activate
• from source
  git clone https://github.com/baskiton/sats-receiver.git
cd sats-receiver
pip install -r requirements.txt
• from pip
  pip install sats_receiver

Usage

python3 -m sats_receiver [-h, --help] [--log LOG] [--sysu SYSU] config
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 info timeout in seconds, 1 hour default

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

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
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
qpsk_baudrate	Number	Required only for QPSK mode. QPSK Baudrate, bps
qpsk_excess_bw	Number	Optional. Only for QPSK mode. QPSK Excess bandwidth. 0.35 by default
qpsk_ntaps	Integer	Optional. Only for QPSK mode. QPSK number of taps. 33 by default
qpsk_costas_bw	Number	Optional. Only for QPSK mode. QPSK Costas bandwidth. 0.005 by default

modulations

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

decoders

• RAW Saved to 2-channel float32 WAV file with bandwidth sample rate
• RSTREAM Raw Stream - binary int8. Suitable for further processing, for example, in SatDump
• APT sats_receiver APT binary file format. See APT
• LRPT Not implemented yet

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_dir	String	Path to directory contains shapes file
shapes	Array of Array	List of shapes data (see shapes)
line_width	Number	Optional. Overlay lines width, pixels. 1 by default
points	Object of Object	Optional. Additional points to draw on map (see points)

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