Demodulation and Deframing Options

The demodulation and deframing option groups of gr_satellites come from the demodulator and deframer components that the selected satellite uses. This page lists every one of them with its default, explains what each does inside the signal chain, and documents how the options interact with values set in SatYAML files. Use it when a recording decodes poorly and you need to tune the receiver.

Run gr_satellites <satellite> --help to see which of these options apply to a given satellite.

On this page:

Common to FSK and BPSK

Option Default Meaning
--clk_bw 0.06 Clock recovery loop bandwidth, relative to the baud rate.
--clk_limit 0.004 Maximum deviation of the recovered symbol period, relative to the nominal period.

Both demodulators use GNU Radio's Symbol Sync block with a damping factor of 1. They first decimate the signal so that there are at most 10 samples per symbol (decimation = ceil(samples per symbol / 10)).

  • Raise --clk_bw (for example to 0.1) when the clock slips partway through packets, which is common with recordings whose sample rate is slightly off. The repository's test.sh uses --clk_bw 0.1 for AU02 and S-NET A.
  • Lower it (for example 0.02) for weak signals where the clock loop is too noisy. test.sh uses --clk_bw 0.02 for KS-1Q.
  • Raise --clk_limit when the transmitter's actual baud rate is noticeably off nominal. test.sh uses --clk_limit 0.05 for Astrocast 0.1 at 9k6.

FSK and AFSK Demodulator Options

Used by the FSK, FSK subaudio and AFSK modulations.

Option Default Meaning
--clk_bw 0.06 See above.
--clk_limit 0.004 See above.
--deviation 5000 FSK deviation in Hz. A negative value swaps which tone means 1.
--use_agc off Enable AGC for IQ input. AGC is always on for real input.
--disable_dc_block off Disable the DC blocker before clock recovery.
--fm-deviation 3000 AFSK only: deviation of the FM carrier in Hz, used to size the input filter for IQ input.

How the FSK chain works

  1. IQ input only: a low-pass filter at Carson's bandwidth (|deviation| + baud rate/2), skipped if that is wider than half the sample rate, followed by a quadrature (FM) demodulator scaled by the deviation.
  2. Subaudio only: a low-pass filter at 2/3 of the baud rate, to remove FM voice above subaudio telemetry.
  3. A moving-average filter one symbol long (matched to rectangular pulses), which also decimates.
  4. A DC blocker (unless --disable_dc_block) to remove frequency offsets that appear as DC after FM demodulation.
  5. An RMS AGC with a time constant of about 50 symbols (real input, or IQ with --use_agc).
  6. Gardner clock recovery.
  7. Real input with a negative deviation: the symbols are inverted.

So with real input, the value of --deviation does not matter, only its sign. With IQ input it sets the FM demodulator gain and the Carson filter.

If the baud rate is not lower than the sample rate, the demodulator prints:

Sample rate 9600.0 sps insufficient for 9600 baud FSK demodulation. Demodulator will not work.

AFSK

AFSK (audio-frequency FSK, as in 1200 baud packet radio or the 4800 baud GMSK tones of GOMspace U482C modems) is demodulated by:

  1. For IQ input, a Carson's-rule filter (fm_deviation + af_carrier + |deviation|) and an FM demodulator.
  2. A frequency-translating filter that moves the AF carrier (af_carrier in the SatYAML file) to 0 Hz, with a low-pass at 2×|deviation|.
  3. The FSK demodulator above, in IQ mode, with the DC blocker disabled.

For AFSK the tone deviation always comes from the SatYAML file's deviation field, so --deviation has no effect. For example AU03 uses af_carrier: 3600 and deviation: -1200: tones at 2400 Hz (symbol 1) and 4800 Hz (symbol 0).

SatYAML values override the command line

The SatYAML file can set deviation (FSK and AFSK) and fm_deviation (AFSK). When it does, those values are passed directly to the demodulator and the command line options --deviation and --fm-deviation are ignored for that transmitter. To change them, edit a copy of the SatYAML file.

Note: The AFSK option is spelled with a hyphen, --fm-deviation, unlike every other option. argparse stores it as fm_deviation.

BPSK Demodulator Options

Used by the BPSK, BPSK Manchester, DBPSK and DBPSK Manchester modulations.

Option Default Meaning
--f_offset 1500 / 12000 / 0 Frequency of the signal in Hz. See BPSK frequency offsets.
--rrc_alpha 0.35 Roll-off of the root-raised-cosine matched filter (dimensionless, although the help text says Hz).
--disable_fll off Disable the frequency-locked loop.
--fll_bw 25 FLL bandwidth in Hz.
--clk_bw 0.06 See above.
--clk_limit 0.004 See above.
--costas_bw 50 Costas loop bandwidth in Hz (coherent BPSK only).
--manchester_block_size 32 Manchester clock search block size, in symbols (Manchester modulations only).

How the BPSK chain works

  1. A frequency-translating FIR filter shifts the signal from f_offset to 0 Hz, low-pass filters it (cutoff 2× baud rate) and decimates.
  2. RMS AGC (time constant about 50 symbols).
  3. A band-edge FLL (unless --disable_fll) to remove the residual frequency offset, for example from Doppler.
  4. Clock recovery with a polyphase RRC matched filter (maximum-likelihood timing error detector).
  5. Manchester modulations: the baud rate is doubled for steps 1 to 4, then the phase of the Manchester clock is searched in blocks of --manchester_block_size symbols and wiped off.
  6. Coherent (BPSK, BPSK Manchester): a Costas loop recovers the carrier phase. Differential (DBPSK, DBPSK Manchester): each symbol is multiplied by the conjugate of the previous one (non-coherent), so the Costas loop and --costas_bw are not used.

If the baud rate (after Manchester doubling) is not lower than a quarter of the sample rate, the demodulator prints Sample rate ... insufficient for ... baud BPSK demodulation. Demodulator will not work.

Useful adjustments:

  • Signal not where expected: set --f_offset. If you listen in USB and the signal sits at 1800 Hz, use --f_offset 1800.
  • Large Doppler or drift: increase --fll_bw.
  • FLL misbehaves on a strong carrier or interference: try --disable_fll.
  • Phase noise or fast fading: increase --costas_bw.

Deframer Options

Option Deframers Default Meaning
--syncword_threshold Most (see table below) depends Number of bit errors allowed when detecting the syncword.
--ra_syncword_threshold SMOG-P RA, SMOG-1 RA, MRC-100 RA -1 Syncword bit errors; a negative value selects the variant's default (SMOG-P 0, SMOG-1 6, MRC-100 4).
--signalling_syncword_threshold SMOG-P Signalling, SMOG-1 Signalling 8 Syncword bit errors for the signalling frames.
--verbose_rs CCSDS (RS, Concatenated, Uncoded), AAUSAT-4, OPS-SAT, 3CAT-1, TT-64, Swiatowid off Print Reed-Solomon decoder messages.
--verbose_fec AX100 (both modes), FORESAIL-1, U482C, S-NET, SALSAT off Print FEC decoder messages.
--verbose_crc Astrocast FX.25, AX5043, IDEASSat off Print CRC check messages.
--callsign_threshold Mobitex, Mobitex-NX, BEESAT-1, BEESAT-9 2 if no callsign is known, 12 if the SatYAML file gives a callsign Bit errors allowed in the callsign and its CRC.
--use_tnc_nx Mobitex family False Use the external gr-tnc_nx module instead of the built-in Mobitex deframer.

A higher syncword threshold finds more frames in noise, at the cost of more false detections (which the FEC or CRC then rejects, using CPU). A lower threshold reduces false detections. A threshold of 0 requires an exact syncword match.

Warning: --use_tnc_nx is declared with type=bool, which converts any non-empty string to True. --use_tnc_nx False therefore enables gr-tnc_nx. Omit the option to keep the built-in deframer. The external deframer does not support BEESAT-1.

The verbose options are mainly useful to confirm that the deframer sees frames that then fail FEC or CRC, which points at a demodulation problem rather than a sync problem.

Syncword Thresholds by Framing

Framing Default --syncword_threshold
AX.25, AX.25 G3RUH, UA01, YUSAT, IDEASSat, AX5043, OPS-SAT no option (HDLC flags or no syncword option)
AX100 ASM+Golay, AX100 Reed Solomon, FORESAIL-1, U482C 4
CCSDS Reed-Solomon, CCSDS Concatenated, CCSDS Uncoded 4
AO-40 FEC (all variants), AAUSAT-4, Astrocast FX.25 NRZ-I/NRZ, Grizu-263A 8
AO-40 uncoded, Mobitex family 3
Lucky-7, TT-64 1
USP 13
AALTO-1, AISTECHSAT-2, GEOSCAN, HSU-SAT1, LilacSat-1, NGHam (both), OpenLST, QUBIK, Reaktor Hello World, Light-1, 3CAT-1, S-NET, SALSAT 4
BINAR-1, BINAR-2, DIY-1, Endurosat, ESEO, FOSSASAT, HADES-D, HADES-R, K2SAT, NuSat, SanoSat, SPINO, Swiatowid 0

In the Satellite decoder and component blocks in GNU Radio Companion the threshold is a block parameter with its own default; see Deframer Blocks.

How Options Are Shared Between Transmitters

A satellite can have several transmitters, each with its own demodulator and deframer, but there is only one set of command line options. Two consequences:

  • One value for all. --clk_bw 0.1 applies to every demodulator of the satellite, and --syncword_threshold 2 to every deframer that reads it.
  • The last default wins. When two deframers of the same satellite both define --syncword_threshold with different defaults, the parser is built with conflict_handler='resolve', so the definition registered last (the deframer of the last transmitter in the SatYAML file) replaces the earlier one. Its default is then used by all deframers. The same applies to demodulator options. --help shows the default that is actually in effect.

If one transmitter needs different settings, run it separately with a single-transmitter SatYAML copy (see Recipes).

Tuning Workflow

  1. Confirm the basics: real vs IQ (--iq), sample rate, BPSK --f_offset, FSK polarity (--input_gain -1).
  2. Run with the relevant verbose option (--verbose_rs, --verbose_fec, --verbose_crc) to see whether frames are detected.
  3. Dump the internal signals with --dump_path and plot clock_recovery_out (see Dumping Internal Signals).
  4. Adjust --clk_bw and --clk_limit for timing problems; --fll_bw and --costas_bw for carrier problems in BPSK.
  5. Adjust --syncword_threshold last.
  6. Save the settings that work in ~/.gr_satellites/sat.cfg and use --satcfg (see Configuration).

See Also