Troubleshooting

This page lists common problems with gr-satellites as symptom → cause → fix, including several behaviors found by reading the source code that are easy to trip over. For installation problems, see also Installation.

On this page:

Starting the Tool

ModuleNotFoundError: No module named 'satellites'

Python cannot find the installed package. Set PYTHONPATH to the directory that contains satellites/ (see Installation). With conda, make sure the environment where gr-satellites is installed is active.

gr_satellites --help only prints a usage line

The satellite must be the first argument, because the available options depend on it. Use gr_satellites <satellite> --help. Only --version and --list_satellites work without a satellite.

Satellite XYZ not found

  • Check the spelling with gr_satellites --list_satellites. Matching ignores case, spaces and punctuation, but the name must otherwise match a name or alternative_names entry.
  • Quote names with spaces: gr_satellites "S-NET A" ....
  • A file path must end in .yml; .yaml is treated as a name.

error: unrecognized arguments: ...

The option exists for other satellites but not this one, for example --f_offset for an FSK satellite or --deviation for a BPSK one. Remove it, or add --ignore_unknown_args to turn the error into a warning. The same error appears if sat.cfg contains an option the satellite does not have, or a double space.

Need to specify --samp_rate unless --wavfile or --kiss_in or --sigmf is used

Raw files, soundcard and UDP input have no way to know the sample rate. Add --samp_rate, for example --samp_rate 48e3.

error: one of the arguments --wavfile --rawfile ... is required

Exactly one input source option is required (--wavfile, --rawfile, --rawint16, --audio, --udp, --kiss_in or --sigmf). Giving two of them is also an error.

UDP input fails to start on a system without IPv6

The UDP source opens an IPv6 socket by default. Add --udp_ipv4_only.

Nothing Is Decoded

Work through these in order:

  1. Real vs IQ. Audio from a radio or SDR program is real (default). Raw SDR samples need --iq. With --iq, FSK/AFSK must not be FM-demodulated, and BPSK must be at 0 Hz unless you set --f_offset. See Real or IQ Input.
  2. Sample rate. A wrong --samp_rate shifts every frequency and baud rate. Watch for Sample rate ... insufficient for ... baud ... demodulation warnings: FSK needs a sample rate above the baud rate, BPSK above four times the baud rate (after Manchester doubling).
  3. BPSK tuning. With real input the signal must be near 1500 Hz (≤ 2400 baud) or 12000 Hz (faster). Set --f_offset otherwise.
  4. FSK polarity. Try --input_gain -1.
  5. Timing. Try --clk_bw 0.1, or --clk_limit 0.02 for recordings with an inaccurate sample rate.
  6. See what the deframer sees. Use --verbose_rs, --verbose_fec or --verbose_crc if the framing has them, and --dump_path to plot the symbols (see Dumping Internal Signals).
  7. VOLK. If the AO-73 (FUNcube) decoder or similar Viterbi-based decoders never decode, run volk_profile, and if needed replace avx2 with spiral or generic on the volk_8u_x4_conv_k7_r2_8u line of ~/.volk/volk_config.

KISS input shows nothing for some satellites

--kiss_in sends frames straight to the data sinks, skipping transports, while --kiss_out stores deframer output (before transports). For satellites that use a transport (BY70-1, LilacSat-1, KS-1Q and others with a transports section), a KISS file written by --kiss_out contains frames that the telemetry parser cannot parse directly. Expect Could not parse telemetry beacon messages or no output. Re-decode the recording instead, or use --hexdump with --kiss_in to inspect the frames.

Options That Seem to Have No Effect

--deviation or --fm-deviation is ignored

If the SatYAML transmitter sets deviation or fm_deviation, those values are passed to the demodulator directly and override the command line. For AFSK, deviation is mandatory in SatYAML, so --deviation never affects AFSK. For real-input FSK, only the sign of the deviation matters. Edit a copy of the SatYAML file to change these values.

A setting applies to the wrong transmitter, or the default changed

All transmitters of a satellite share one set of options. When two deframers define --syncword_threshold with different defaults, the one registered last (the last transmitter in the file) provides the default for all. Check --help for the value actually in effect, or run a single-transmitter copy of the SatYAML file (Recipes).

--satcfg or --ignore_unknown_args does nothing

These two must be typed in full. argparse accepts abbreviations of other options, but the tool detects these two by exact string comparison before parsing.

--use_tnc_nx False enables gr-tnc_nx

The option uses type=bool, so any non-empty value is True. Leave it out to use the built-in Mobitex deframer.

--start_time gives odd timestamps

Without --throttle, a recording is processed much faster than real time, so all timestamps fall within a few seconds of --start_time. Use both options together. For SigMF input, a core:datetime in the single capture segment replaces --start_time. PW-Sat2 submissions ignore --start_time.

Output, Files and Images

Images are not shown

  • feh is not installed: the tool prints Unable to open feh image viewer but keeps saving the image. Install feh.
  • --hexdump disables receivers fed through a transport (LilacSat-1, BY70-1 images).
  • feh starts only after 640 bytes of an image have arrived.

Received images are corrupted or mixed with old ones

Existing files are opened for update, not truncated, and image files are usually named 0.jpg, 1.jpg, ... from a counter that restarts with each run. A new image written over an older, longer one keeps the old tail. Use an empty --file_output_path directory per session.

Received files are not in /tmp

The default --file_output_path is the current directory, not /tmp/ as the upstream documentation says.

--dump_path files are missing or garbled

The directory must exist before running. For satellites with several transmitters, all demodulators write the same file names into it; use a single-transmitter SatYAML copy.

Packets from TM KISS satellites look duplicated or truncated

The TM KISS and TM short KISS transports (used by ASRTU-1 among the bundled files) keep appending to the list of a packet they have already emitted when a frame contains more than one KISS frame delimiter, because the loop's local list is not reset after emitting. As written in python/components/transports/tm_kiss_transport.py, later packets within the same TM frame are emitted with the earlier packet's bytes still in front, extra delimiters re-emit it, and bytes after the last delimiter of such a frame are discarded. Use --hexdump to inspect the raw TM frames if the parsed output looks wrong.

Telemetry Submission

Nothing shows up in SatNOGS DB

  • submit_tlm must be yes in ~/.gr_satellites/config.ini, and GR_SATELLITES_SUBMIT_TLM must not be set to a false value.
  • callsign must not be empty, and latitude/longitude must not both be 0. Otherwise submission is silently disabled.
  • Watch standard output for Error while submitting telemetry: or Server error while submitting telemetry.

KeyError mentioning the value of GR_SATELLITES_SUBMIT_TLM

Only lower-case 1, yes, true, on, 0, no, false, off are accepted. True, YES or an empty value crash the tool.

KeyError when using the BME server

The BME submitter only knows NORAD 44830, 44832 and 47964. Using BME in another satellite's SatYAML file, or a Telemetry Submit block with another NORAD ID, fails.

Could not connect to telemetry proxy

The HIT proxy must be running on the same machine, listening on the port in the SatYAML file, before gr_satellites starts. Submission to it is disabled for that run.

Configuration Files

ValueError: invalid literal for int() at startup with --satcfg

sat.cfg has a line whose first field is not a NORAD ID, typically a comment. Comments are not supported; remove the line.

Config changes are not picked up

The template config.ini is only written when the file does not exist. Section names are case-sensitive. Delete the file to regenerate it.

Custom SatYAML Files

Symptom Cause
KeyError: 'BPSK ' (or another modulation/framing) Unknown or misspelled modulation/framing; names are exact and case-sensitive.
KeyError naming a transport A transmitter lists a transport that is not defined; the checker misses this case.
TypeError: ... got an unexpected keyword argument 'frame_size' A deframer field (frame size, scrambler, ...) used with a framing that does not accept it.
--list_satellites crashes with a TypeError A frequency written as 437e6 or 437.3e6, which YAML reads as a string; use 437.3e+6.
file: data entry prints hex instead of saving files The key is files:.

Run check_yaml() on the file to catch most problems (see Validation).

GNU Radio Companion

A GRC flowgraph decodes fewer frames than gr_satellites

Deframer blocks default their Syncword threshold to 0 (exact match), while the command line uses larger defaults. The BPSK Demodulator block defaults Frequency offset to 0 Hz, whereas the command line picks 1500 or 12000 Hz for real input. Set these parameters explicitly. The Satellite decoder block is not affected: it uses the same defaults as the command line.

TM KISS Transport block fails with TypeError

Its GRC definition calls kiss_transport() with virtual_channels and short_tm, which that class does not accept. Use a Python block or a custom script with satellites.components.transports.tm_kiss_transport.

Options in a block's Command line options are ignored

A block parameter always wins: deframer blocks pass Syncword threshold, the BPSK block passes Frequency offset, the AFSK block passes Deviation. The Telemetry Parser block does not parse its options string at all.

--kiss_out (or another output option) is rejected by the Satellite decoder block

The block only accepts demodulation, deframing and data sink options. Use the KISS File Sink and similar blocks instead.

Utilities

Symptom Cause and fix
gr_satellites_ssdv crashes with KeyError: None --satellite is missing. Pass --satellite JY1SAT, ERMINAZ or DSLWP.
gr_satellites_ssdv prints nothing and exits No SSDV packets were found in the KISS file for that satellite.
smog_p_spectrum crashes with AttributeError The input file was renamed; the name must match spectrum_start_<n>_step_<n>_rbw_<n>_measid_<n>.

Getting Help

Support is provided through GitHub issues (bugs) and GitHub discussions (questions), not by email. Include the exact command line, the gr_satellites --version output, and if possible a short recording.