.. _gr_satellites command line tool: gr_satellites command line tool =============================== The ``gr_satellites`` command line tool is a complete solution that can decode frames using either real-time RF samples from an SDR or conventional radio, or a recording. Basic usage ^^^^^^^^^^^ ``gr_satellites`` can be run from a terminal after gr-satellites has been installed. If run without any arguments, ``gr_satellites`` will only print some basic information about the arguments it allows. .. code-block:: console $ gr_satellites usage: gr_satellites satellite [-h] [--version] [--list_satellites] [--ignore_unknown_args] [--satcfg] (--wavfile WAVFILE | --rawfile RAWFILE | --rawint16 RAWINT16 | --audio [DEVICE] | --udp | --kiss_in KISS_IN) [--samp_rate SAMP_RATE] [--udp_ip UDP_IP] [--udp_port UDP_PORT] [--iq] [--udp_raw] [--input_gain INPUT_GAIN] [--start_time START_TIME] [--throttle] [--kiss_out KISS_OUT] [--kiss_append] [--kiss_server [PORT]] [--kiss_server_address KISS_SERVER_ADDRESS] [--zmq_pub [ADDRESS]] [--hexdump] [--dump_path DUMP_PATH] .. _Specifying the satellite: Specifying the satellite """""""""""""""""""""""" The arguments that ``gr_satellites`` allows depend on the satellite that has been selected. Therefore, to use ``gr_satellites`` it is always necessary to specify the ``satellite`` to be used as an argument immediately following ``gr_satellites``. There are three different ways to specify the satellite: * Using the satellite name, such as *FUNcube-1* or *LilacSat-2*. This can be used with any :ref:`satellite officially supported by gr-satellites`, and it is the most simple way of specifying a satellite. .. code-block:: console $ gr_satellites FUNcube-1 A satellite may have several different names, known as *alternative names*. For example, FUNcube-1 is both known as AO-73 and FUNcube-1. * Using the satellite `NORAD ID`_. This can bue used with any :ref:`satellite officially supported by gr-satellites`, and it can be useful when interfacing ``gr_satellites`` with other tools that use NORAD IDs to classify satellites. Below we show ``gr_satellites`` running with NORAD ID 39444, which corresponds to FUNcube-1. .. code-block:: console $ gr_satellites 39444 * Using a path to an ``.yml`` SatYAML file. SatYAML files are used by gr-satellites to specify the decoding parameters and configuration corresponding to each different satellite. They are described in more detail in the :ref:`SatYAML files` section. gr-satellites comes bundled with a large number of SatYAML files corresponding to all the officially supported satellites. They can be found in the ``python/satyaml/`` directory. Specifying the path of a SatYAML file is useful if the user has modified some of the files bundled with gr-satellites or has created their own ones. .. code-block:: console $ gr_satellites python/satyaml/AO-73.yml .. _NORAD ID: https://en.wikipedia.org/wiki/Satellite_Catalog_Number .. _Specifying the input source: Specifying the input source """"""""""""""""""""""""""" Besides specifying the satellite to use for decoding, it is mandatory to specify the input source by using exactly one of the following options: * ``--wavfile`` can be used to read a recording in WAV/OGG/FLAC format. This uses libsndfile through the GNU Radio WAV File Source block, so any format supported by libsndfile can be used. The sample rate is obtained from the file header, but it can be overriden using the the ``--samp_rate`` argument if necessary. By default, the WAV/OGG/FLAC file is interpreted as a one-channel file containing real RF samples. To read a two-channel file containing IQ RF samples, the ``--iq`` argument needs to be specified. .. note:: All the :ref:`sample recordings ` in the ``satellite-recordings/`` are real 48kHz WAV files and can be read with the ``--wavfile file --samp_rate 48e3`` arguments. For example, this will decode some frames from FUNcube-1: .. code-block:: console $ gr_satellites FUNcube-1 --wavfile satellite-recordings/ao73.wav * ``--rawfile`` can be used to read a recording in ``complex64`` or ``float32`` format (depending on whether the ``--iq`` argument is used or not). The sample rate of the recording needs to be specified with the ``--samp_rate`` argument. .. note:: Files in ``complex64`` format contain a sequence of 32-bit floating point numbers in IEEE 754 format. The sequence alternates between the I (in-phase) and Q (quadrature) componentes of a stream of IQ samples. This format is used by the GNU Radio File Source and File Sink blocks when their type is set to *complex*. Files in ``float32`` format contain a sequence of 32-bit floating point numbers in IEEE 754 format. The sequence contains the elements of a stream of real samples. This format is used by the GNU Radio File Source and File Sink blocks when their type is set to *float*. * ``--rawint16`` can be used to read a recording in ``int16`` format. The file is interpreted as IQ or real data according as to whether the ``--iq`` argument is used or not. The sample rate of the recording needs to be specified with the ``--samp_rate`` argument. .. note:: Files in ``int16`` format contain a sequence of 16-bit integers in host endianness. This format is used by GNU Radio File Source and File Sink blocks when their type is set to *short*. * ``--audio`` can be used to read samples from the soundcard, using GNU Radio's `Audio Source`_. This can be used to receive audio from a conventional radio by using the soundcard or from another application via a "virtual audio cable". The sample rate to use needs to be specified with the ``--samp_rate`` argument. A sample rate of 48000 is typical with audio devices. Both real samples (by default) and IQ samples (using the ``--iq`` argument) are supported. IQ samples use two audio channels (stereo). The ``--audio`` argument can optionally be followed by the name of the audio device to use. Details about how to specify the device name vary between plaform and are described in the `Audio Source`_ documentation. If no device name is entered, the default audio device will be chosen. * ``--udp`` can be used to received RF samples streamed in real-time. The sample rate of the recording needs to be specified with the ``--samp_rate`` argument. The streaming format is the same as for the ``--rawint16`` and both real samples (by default) and IQ samples (using the ``--iq`` argument) are supported. If the ``--udp_raw`` is used the format will be the same as for ``--rawfile``. By default, ``gr_satellites`` will listen on the IP address ``::`` (all addresses) and the UDP port 7355. A different IP address or port can be specified using the parameters ``--udp_ip`` and ``--udp_port``. .. note:: `GQRX`_ can stream audio in UDP using this format and UDP port, and a sample rate of 48ksps by following the instructions `here `_. In this case, ``gr_satellites`` should be run as .. code-block:: console $ gr_satellites FUNcube-1 --udp --samp_rate 48e3 This is recommended as a simple way of interfacing ``gr_satellites`` with SDR hardware for beginner users. It is also possible to use the example GNU Radio companion flographs in `gr-frontends`_ to stream samples by UDP from different sources. For more advanced users, ``nc`` can also be a very useful tool for streaming. * ``--kiss_in`` can be used to process a file containing already decoded frames in KISS format. All the demodulation steps are skipped and only telemetry parsing, file receiving, etc. are done. This can be useful to view the telemetry stored in files previously decoded with gr-satellites or other software. Getting help """""""""""" ``gr_satellites`` prints a detailed description of all the allowed arguments by using the ``-h`` or ``--help`` argument. Note that a satellite needs to be specified, since the set of allowed arguments depends on the decoders used by that satellite. For example, this shows all the options allowed by the FUNcube-1 decoder: .. code-block:: console $ gr_satellites FUNcube-1 --help usage: gr_satellites satellite [-h] [--version] [--list_satellites] (--wavfile WAVFILE | --rawfile RAWFILE | --rawint16 RAWINT16 | --audio [DEVICE] | --udp | --kiss_in KISS_IN) [--samp_rate SAMP_RATE] [--udp_ip UDP_IP] [--udp_port UDP_PORT] [--iq] [--input_gain INPUT_GAIN] [--start_time START_TIME] [--throttle] [--kiss_out KISS_OUT] [--kiss_append] [--kiss_server [PORT]] [--kiss_server_address KISS_SERVER_ADDRESS] [--zmq_pub [ADDRESS]] [--hexdump] [--dump_path DUMP_PATH] [--telemetry_output TELEMETRY_OUTPUT] [--f_offset F_OFFSET] [--rrc_alpha RRC_ALPHA] [--disable_fll] [--fll_bw FLL_BW] [--clk_bw CLK_BW] [--clk_limit CLK_LIMIT] [--costas_bw COSTAS_BW] [--manchester_history MANCHESTER_HISTORY] [--syncword_threshold SYNCWORD_THRESHOLD] [--verbose_rs] gr-satellites - GNU Radio decoders for Amateur satellites optional arguments: -h, --help show this help message and exit --version show program's version number and exit --list_satellites list supported satellites and exit --ignore_unknown_args Treat unknown arguments as warning --satcfg Use default options from sat.cfg for named satellite input: --wavfile WAVFILE WAV/OGG/FLAC input file (using libsndfile) --rawfile RAWFILE RAW input file (float32 or complex64) --rawint16 RAWINT16 RAW input file (int16) --audio [DEVICE] Soundcard device input --udp Use UDP input --kiss_in KISS_IN KISS input file --samp_rate SAMP_RATE Sample rate (Hz) --udp_ip UDP_IP UDP input listen IP [default='::'] --udp_port UDP_PORT UDP input listen port [default='7355'] --iq Use IQ input --input_gain INPUT_GAIN Input gain (can be negative to invert signal) [default=1] --start_time START_TIME Recording start timestamp --throttle Throttle recording input to 1x speed output: --kiss_out KISS_OUT KISS output file --kiss_append Append to KISS output file --kiss_server [PORT] Enable KISS server [default port=8100] --kiss_server_address KISS_SERVER_ADDRESS KISS server bind address [default='127.0.0.1'] --zmq_pub [ADDRESS] Enable ZMQ PUB socket [default address=tcp://127.0.0.1:5555] --hexdump Hexdump instead of telemetry parse --dump_path DUMP_PATH Path to dump internal signals demodulation: --f_offset F_OFFSET Frequency offset (Hz) [default=1500 or 12000] --rrc_alpha RRC_ALPHA RRC roll-off (Hz) [default=0.35] --disable_fll Disable FLL --fll_bw FLL_BW FLL bandwidth (Hz) [default=25] --clk_bw CLK_BW Clock recovery bandwidth (relative to baudrate) [default=0.06] --clk_limit CLK_LIMIT Clock recovery limit (relative to baudrate) [default=0.02] --costas_bw COSTAS_BW Costas loop bandwidth (Hz) [default=50] --manchester_history MANCHESTER_HISTORY Manchester recovery history (symbols) [default=32] deframing: --syncword_threshold SYNCWORD_THRESHOLD Syncword bit errors [default=8] --verbose_rs Verbose RS decoder data sink: --telemetry_output TELEMETRY_OUTPUT Telemetry output file [default=stdout] The satellite parameter can be specified using name, NORAD ID or path to YAML file .. _Output: Output """""" By default, ``gr_satellites`` will "do its best" to show the user the output for the decoded frames. If the telemetry format for the satellite is implemented in gr-satellites, the telemetry frames will be printed to the standard output in human-readable format. Otherwise, the raw frames will be printed out in hex format to the standard output. File decoding, image decoding and other special output options of some particular satellites are enabled by default. Customization of the ouput options is described in the :ref:`Output options` subsection below. Examples """""""" The ``test.sh`` script in the ``gr-satellites/`` directory runs ``gr_satellites`` on several of the :ref:`sample recordings ` in ``satellite-recordings/``. This script can be used as a series of examples of how to run ``gr_satellites``. .. _Output options: Ouput options ^^^^^^^^^^^^^ This subsection explains in detail the different output options that can be used with the ``gr_satellites`` command line tool. The default behaviour when no options are specified has been described in the :ref:`Output` subsection above. .. _Hex dump: Hex dump """""""" By using the option ``--hexdump``, it is possible to make ``gr_satellites`` print the received frames in hexadecimal format, regardless of whether there is a telemetry decoder available or not. The format used to print the frames is the same as used by the GNU Radio block `Message Debug`_ ``print_pdu`` input. An example of the use of this option can be seen here: .. code-block:: console $ gr_satellites FUNcube-1 --wavfile ~/gr-satellites/satellite-recordings/ao73.wav \ --hexdump * MESSAGE DEBUG PRINT PDU VERBOSE * () pdu_length = 256 contents = 0000: 89 00 00 00 00 00 00 00 00 1f cc 00 ce 02 d1 00 0010: 00 07 08 09 09 00 00 05 01 01 00 40 13 2f c8 f2 0020: 5c 8f 34 23 f3 ba 0b 5d 62 74 51 c7 ea fa 69 4a 0030: 9a 9f 00 09 ef a0 1f f4 a7 ea 4a c6 8f 11 40 11 0040: 1e 10 f7 01 3e 20 64 00 d7 8b f8 d7 94 c8 93 a8 0050: 2a da 52 a6 0e 58 0e c8 0f 4e 01 1d 20 5a 00 db 0060: 94 a8 aa 8a 98 13 ac 69 0a a6 a8 10 e6 10 92 0f 0070: b8 01 50 20 64 00 d7 96 a8 c1 8b 48 25 ab a9 ca 0080: ce 9d 10 76 0f c9 10 55 01 3a 20 5a 00 d7 97 29 0090: 08 8c 48 4f a9 6a 5a f2 a4 10 39 0f 7b 0f 86 01 00a0: 49 20 64 00 d7 94 08 d0 8a d8 2a ad 6a 5a 7e b4 00b0: 0e 53 0e 9b 0e b7 01 09 20 5a 00 db 99 a8 f2 8f 00c0: e8 38 af aa 8a c2 9e 0e de 0f 48 0e 31 01 31 20 00d0: 5a 00 ce 9b c8 ff 88 68 1b b2 6a 5a ca a7 0f c3 00e0: 0e 74 0e 58 01 34 20 5a 00 d7 9b 39 1b 97 b8 c5 00f0: b0 2b 3a d6 b5 01 6b 00 6a 02 9e 00 03 20 13 00 *********************************** .. _KISS output: KISS output """"""""""" Decoded frames can be saved to a file in `KISS format`_. This is a simple format that serves to delimit frames stored in a file or sent over a serial bus, and it is frequently used to store telemetry frames. To enable KISS output, the ``--kiss_out`` parameter followed by the path of the output file should be used. By default ``gr_satellites`` will overwrite the file if it already exists. To append to the file instead, the option ``--kiss_append`` can be used in addition to the ``--kiss_out`` option. Appending can be used to concatenate frames obtained in several decoding runs. Files in KISS format can be read with ``gr_satellites`` as indicated above or with other software tools. .. note:: KISS files produced with ``gr_satellites`` use an extension proposed by `Mike Rupprecht`_ to store the reception timestamp of the frames. Before each data frame, a KISS control frame using the control byte ``0x09`` and storing a timestamp with UNIX timestamp in milliseconds stored as a big-endian 64 bit integer is included in the file. Some software, including the decoders by Mike Rupprecht, will be able to read and use these timestamps. Other software that processes KISS will ignore the timestamps. .. _Mike Rupprecht: http://dk3wn.info/ KISS server """"""""""" A KISS TCP server can be enabled with the ``--kiss_server`` parameter, optionally followed by the TCP port to listen on (by default port 8100 is used). This allows other applications to connect to ``gr_satellites`` and receive decoded frames using the KISS protocol. By default the KISS server will only bind on ``127.0.0.1`` and listen to requests from localhost only. If access from other computers on the network is needed, the ``--kiss_server_address`` parameter can be used to specify the address to bind to. For instace, if ``--kiss_server_address ''`` or ``--kiss_server_address 0.0.0.0`` is used, the server will bind to 0.0.0.0 and listen to requests from all addresses. ZMQ PUB socket """""""""""""" Decoded frames can also be sent to other applications by using a `ZeroMQ`_ PUB socket. Several applications can connect to the PUB socket using SUB sockets. The frames are sent using the *ZMQ PUB Message Sink* GNU Radio block, and can be received using the *ZMQ SUB Message Source* GNU Radio block. The ZMQ PUB socket is enabled using the ``--zmq_pub`` parameter, optionally followed by the socket endpoint to use. By default, the endpoint ``tcp://127.0.0.1:5555`` is used. This means that the ZMQ PUB socket will only listen to connections from localhost. If desired, the endpoint ``tcp://*:5555`` can be used to listen on all addresses. .. _ZeroMQ: https://zeromq.org/ Telemetry output """""""""""""""" For satellites supporting telemetry parsing, ``gr_satellites`` will default to printing the decoded telemetry values to the standard output. It is possible to write these messages to a file instead by using the ``--telemetry_output`` parameter followed by the path of the output file. Dump internal signals """"""""""""""""""""" For advanced users and developers, the demodulators used in ``gr_satellites`` can dump the internal signals used inside the demodulator. This option can be enabled by using the ``--dump_path`` parameter followed by a path to the directory where the different files are created. It is recommended to use this option with a short recording, to avoid creating very large files. The details of each of these files are best studied in the Python source code of the demodulators (see ``python/components/demodulators/``). The following example show how to use ``--dump_path`` to plot the symbols with `Numpy`_ and `Matplotlib`_ and optimize the decoding parameters for a particular recording. We first run the following to dump to the path ``/tmp/fsk`` the internal signals produced by decoding a sample recording of AU02. .. code-block:: console $ mkdir -p /tmp/fsk $ gr_satellites AU02 --wavfile satellite-recordings/au02.wav \ --dump_path /tmp/fsk We see that we do not get any decoded packets. Then, we can plot the FSK symbols with the following Python code: .. code-block:: python import numpy as np import matplotlib.pyplot as plt x = np.fromfile('/tmp/fsk/clock_recovery_out.f32', dtype = 'float32') plt.plot(x, '.') plt.show() This produces the figure below, which shows that there has been a clock cycle slip mid packet, which prevents correct decoding. .. figure:: images/au02_default.png :alt: FSK symbols with default parameters FSK symbols with default parameters We can run ``gr_satellites`` again adding the parameter ``--clk_bw 0.1`` to increase the clock recovery loop bandwidth. With this parameter we get a successful decode and if we plot the FSK symbols again, we get the figure below, which shows that the clock recovery is working much better than before. .. figure:: images/au02_nondefault.png :alt: FSK symbols with non-default parameters FSK symbols with non-default parameters .. _Telemetry submission: Telemetry submission ^^^^^^^^^^^^^^^^^^^^ The ``gr_satellites`` command line tool can be used to submit decoded telemetry to an online database server, such as `SatNOGS DB`_ and these others servers used by certain satellite projects: * `FUNcube Warehouse`_, which is used by the FUNcube payloads on FUNcube-1, UKube-1, Nayif-1 and JY1Sat. * `PW-Sat2 Groundstation`_, which is used by PW-Sat2. * The `BME telemetry server`_, which is used by SMOG-P, ATL-1 and SMOG-1. (This server is deprecated, since it is not used anymore by BME). * The `BME telemetry server (WebSocket)`_, which is used by MRC-100. * `Harbin Institute of Technology`_, which connects to the telemetry proxy included in `gr-lilacsat`_ and `gr-dslwp`_. * Any custom server using the SIDS protocol. The `SIDS protocol`_ is an HTTP-based protocol that was first developed by the ESTCube team and later used by the UWE-3 team. It is the basis of the SatNOGS DB server and other telemetry servers. To enable telemetry submission, it is necessary to edit some parameters in ``gr_satellites``'s config file, which is located in ``~/.gr_satellites/config.ini``. If this file does not exist, it will be created with a template when ``gr_satellites`` is first run. The template looks like this: .. code-block:: ini [Groundstation] callsign = latitude = 0 longitude = 0 submit_tlm = no [FUNcube] site_id = auth_code = [PW-Sat2] credentials_file = [BME] user = password = To enable telemetry submission, the ``submit_tlm`` parameter must be set to ``yes``. Additionally, the receiving stations ``callsign`` as well as its location (``latitude`` and ``longitude``) need to be set, since some of the servers need these parameters. Once this is done, telemetry submission to SatNOGS DB will be enabled for all satellites. To enable telemetry submission to the FUNcube warehouse, it is necessary to fill in the ``site_id`` and ``auth_code``. These can be obtained by `registering in the warehouse`_. To enable telemetry submission to the PW-Sat2 server, it is necessary to enter the path to the credentials file in the ``credentials_file`` parameter. This file is a JSON file that is generated and downloaded in the "`Your credentials`_" section of the server web interface. It is necessary to have an account registered in the server to obtain the credentials file. To enable telemetry submission to the BME server, it is necessary to `register an account in the BME server`_. The user and password should be entered into the gr-satellites ``.ini`` file. The BME server (WebSocket) does not require any registration or additional configuration. To use the Harbin Institute of Technology proxy to submit telemetry, the proxy needs to be run and started in the local computer before running ``gr_satellites``. The command line tool will connect to the correct port where the proxy is listening (this is specified in the SatYAML file of each satellite). All the configuration regarding the station and the operator is done in the proxy itself. When ``gr_satellites`` starts, it will attempt to connect to the proxy, and print a warning if unable (in which case telemetry submission through the proxy is disabled for this run). .. note:: The Harbin Institute of Technology proxy is a Python2 application that uses PyQt4. Users having more modern sytems may find useful the PyQt5 version that can be found in the `pyqt5 branch of gr-lilacsat`_. This requires ``tornado`` version 4.5.3. It will not work with more recent versions of ``tornado``. No special configuration needs to be done to enable submission to custom SIDS servers, since these use the same protocol and configuration as SatNOGS DB. For some telemetry servers, including SatNOGS DB, the frames are submitted together with a timestamp of reception. This timestamp is taken from the computer's clock by ``gr_satellites`` at the moment when it decodes the frame. This means that, in order to use telemetry submission appropriately, the computer's clock should be set accurately and a live signal rather than a recording should be decoded. File and image receiver ^^^^^^^^^^^^^^^^^^^^^^^ Some satellites transmit files (especially image files) by splitting the files into many telemetry packets. The ``gr_satellites`` decoder supports reassembling and storing these files into a directory. Additionally, image files are automatically displayed in real time as they are being received, using `feh`_. Currently the satellites that have decoders supporting file reception are ATL-1 and SMOG-P (they transmit RF spectrum data), and the satellites that have decoders supporting image reception are 1KUNS-PF, BY70-1, D-SAT, LilacSat-1, Lucky-7 and Światowid. For satellites supporting file reception, the ``--file_output_path`` parameter can be used to set the directory that is used to store received files. The filenames of the received files will be automatically created using metadata or a counter (if no metadata is transmitted). By default, received files are stored in ``/tmp/``. The ``--verbose_file_receiver`` parameter can be used to enable additional debugging information about the functionality of the file receiver. Other topics ^^^^^^^^^^^^ This subsection deals with other topics which are relevant to the usage of ``gr_satellites``. .. _Real or IQ input: Real or IQ input """""""""""""""" The ``gr_satellites`` command line tool supports both real (one-channel) input and IQ input (which consists of two channels: in-phase and quadrature). A detailed description of these two ways to represent a signal is out of the scope of this document. This subsection gives some practical advice regarding the difference between real and IQ input. By default ``gr_satellites`` will assume that its input is real. To use IQ input, the ``--iq`` option must be used. When using the audio output of either a conventional radio or an SDR software performing SSB or FM demodulation, ``gr_satellites`` should be used with the real input option. Likewise, recordings produced from this kind of audio output, such as one-channel WAV recordings should also be used with the real input option. However, most SDR softwares will also have an option to save raw samples to a file. These files are almost always IQ, and can be either a two-channel WAV file or a file in raw format. The IQ input option must be used when using ``gr_satellites`` to read these files. Additionally, some SDR software may support streaming IQ data by UDP. This can also be used in ``gr_satellites`` with the IQ input option. .. _FSK demodulation and IQ input: FSK demodulation and IQ input """"""""""""""""""""""""""""" When using an AFSK or FSK demodulator, the usage of the ``--iq`` option has an additional effect. Since (A)FSK is a mode based on frequency modulation, it is common to use either a conventional FM radio or an SDR software performing FM demodulation to receive (A)FSK. Audio recordings obtained in this manner are also common. Therefore, when ``gr_satellites`` is run without the ``--iq`` signal, it will expect that (A)FSK signals have already been FM-demodulated in this way. When the ``--iq`` option is used, ``gr_satellites`` expects an (A)FSK signal that has not been FM-demodulated, and so it will perform FM-demodulation first. This is the kind of procedure that should be employed with inputs such as raw IQ recordings of an SDR, since the (A)FSK signals present in this kind of recordings have not been FM-demodulated. .. note:: The output of the radio or SDR software when running in FM mode to receive an FSK signal is actually an NRZ signal. Therefore, when ``gr_satellites`` is run without the ``--iq`` option, it will expect an NRZ signal instead of an FSK signal. When ``gr_satellites`` is run with the ``--iq`` option, it will expect an FSK signal. Similarly, the output of the radio or SDR software when running in FM mode to receive an AFSK signal is actually an audio-frequency FSK signal. Therefore, when ``gr_satellites`` is run without the ``--iq`` option, it will expect an audio-frequency FSK signal instead of an AFSK signal. When ``gr_satellites`` is run with the ``--iq`` option, it will expect an AFSK signal. Note that this behaviour is what the user wants in most cases, but it also means that it is not possible to run ``gr_satellites`` directly on an (A)FSK signal which is represented in intermediate frequency as a real signal. .. _Frequency offsets for BPSK: Frequency offsets for BPSK """""""""""""""""""""""""" A usual way of receiving a BPSK signal is to use either a conventional radio or an SDR software in SSB mode (USB mode, normally) and tune the BPSK signal in the middle of the audio passband. Audio recordings obtained in this manner are also common. .. note:: The SSB filter of a conventional radio is often approximately 3kHz wide. For this reason, only BPSK signals with a baudrate of 2400 baud or lower can be received with a conventional SSB radio. For BPSK signals with larger baudrate, an SDR receiver should be used. The ``gr_satellites`` command line tool needs to know the frequency at which the BPSK signal is tuned within the audio passband. If necessary, this can be specified with the ``--f_offset`` parameter, followed by the frequency in Hz. There are the following defaults: * For signals with a baudrate of 2400 baud or less, a frequency offset of 1500 Hz is used. This follows the common practice of using a regular 3kHz SSB bandwidth and tuning the signal in the middle of the passband. * For signals with a baudrate larger than 2400, a frequency offset of 12000 Hz is used. The rationale is that, for best results, a passband of 24000 Hz should be used, since this is the largest that fits in a 48kHz audio signal, and the signal should be tuned in the middle of this 24000 Hz passband. This kind of usage is sometimes called "wide SSB mode". These settings only apply for a real input. When ``gr_satellites`` is used with IQ input, the default is to expect the BPSK signal tuned at 0Hz (i.e., at baseband). A different frequency can still be selected with the ``--f_offset`` parameter. FSK signal polarity """"""""""""""""""" A conventional FM radio, or even an SDR software running in FM mode might invert the polarity of the output signal, since the polarity is not relevant for audio signals. However, the polarity is relevant when receiving an FSK signal that does not use differential coding. An input with the inverted polarity will cause decoding to fail. In this case, the input can be inverted again by using the ``--input_gain -1`` parameter, which has the effect of multiplying the input signal by -1 before it is processed, thus restoring the correct polarity. Multiple transmitters """"""""""""""""""""" Some satellites have multiple transmitters (or different types of signals) declared in their :ref:`SatYAML files`. When run for these satellites, the ``gr_satellites`` command line tool will run decoders for all the transmitters or signal types in parallel. Therefore, it is not necessary or possible to specify the transmitter to use. In the case when it is necessary to run only the decoder for a single transmitter, the easiest solution is to make a copy of the SatYAML file for that satellite, edit the copy to leave out only the desired transmitter, and then running ``gr_satellites`` and indicating it to use the modified SatYAML file. Getting correct timestamps with recordings """""""""""""""""""""""""""""""""""""""""" One of the difficulties with working with recordings is obtaining correct timestamps for each of the decoded packets. These timestamps are included in KISS files and telemetry submissions to some servers, such as SatNOGS DB. To produced correct timestamps ``gr_satellites`` will play back the recording at 1x speed and count the clock time elapsed since the beginning of the execution, it will then add that time to a timestamp specified by the user, which should correspond to the start of the recording. To use this functionality it is necessary to use the ``--throttle`` parameter to limit playback speed to 1x and use the ``--start_time`` parameter followed by the timestamp in ISO 8601 format (``YYYY-MM-DDTHH:MM:SS``) to indicate the start time of the recording. Treating unknown args as warning """""""""""""""""""""""""""""""" Using the argument ``--ignore_unknown_args`` will change the behaviour on unknown arguments to a warning instead of exiting with an error. This can be useful when running in automated scripts and some options may not be available on that satellite. For example the ``--f_offset`` and ``--use_agc`` Using sat.cfg for default arguments """"""""""""""""""""""""""""""""""" With ``--satcfg`` the configuration file `~/.gr_satellites/sat.cfg` will be read and arguments added automatically to the command line. Some of these can be overridden with specifying them on the command line again. The format of the file is one row per satellite, first the norad ID then the rest of the row is treated as aguments. Example: .. code-block:: ini 39444 --f_offset 12000 46276 --disable_dc_block --deviation 500 --clk_bw 0.15 35933 --clk_bw 0.3 .. _GQRX: https://gqrx.dk/ .. _gr-frontends: https://github.com/daniestevez/gr-frontends .. _Message Debug: https://wiki.gnuradio.org/index.php/Message_Debug .. _KISS format: http://www.ax25.net/kiss.aspx .. _SatNOGS DB: https://db.satnogs.org/ .. _FUNcube Warehouse: http://warehouse.funcube.org.uk/ .. _PW-Sat2 Groundstation: https://radio.pw-sat.pl/ .. _BME telemetry server: https://gnd.bme.hu:8080/ .. _BME telemetry server (WebSocket): https://gnd.bme.hu/ .. _registering in the warehouse: http://warehouse.funcube.org.uk/registration .. _Your credentials: https://radio.pw-sat.pl/communication/yourcredentials .. _register an account in the BME server: https://gnd.bme.hu:8080/auth/register .. _feh: https://feh.finalrewind.org/ .. _NumPy: https://numpy.org/ .. _Matplotlib: https://matplotlib.org/ .. _Harbin Institute of Technology: http://lilacsat.hit.edu.cn/ .. _gr-lilacsat: https://github.com/bg2bhc/gr-lilacsat .. _gr-dslwp: https://github.com/bg2bhc/gr-dslwp .. _pyqt5 branch of gr-lilacsat: https://github.com/daniestevez/gr-lilacsat/tree/pyqt5 .. _Audio Source: https://wiki.gnuradio.org/index.php/Audio_Source .. _SIDS protocol: https://github.com/janvgils/sids