Using Decoder

This tutorial describes how to use Decoder with GQRX, GNUradio or rtl_fm. The tutorial makes the following assumptions:

• You have installed GNUradio/GQRX or rtl_fm
• You are familiar with the UNIX command line
• You have built decoder

Theory of Operation

Decoder expects the input sample stream to be a stream of 16-bit signed PCM samples. Once you get the sample stream to this state, Decoder has the ability to resample the input stream to be the required 48kHz sample rate needed for AIS, the 16kHz sample rate needed for FLEX decoding, or the 38.4kHz needed for POCSAG decoding.

The resampler in Decoder is a polyphase rational resampler. This means that the target sample rate must be described as a multiplication by an integer factor by the input sample rate, and a division by another integer factor, i.e.:

         Interpolate * F_in
F_out =  ------------------
              Decimate

For example, if your input sample rate is 48kHz, and the desired output sample rate is 16kHz, the interpolation factor will be 16, while the decimation factor will be 48, since 16 * 48000/48 = 16000.

When you are configuring Decoder, you need to specify the interpolation factor (-I) and your decimation factor (-D) on the command line, so it knows what to expect.

A worked POCSAG example

POCSAG has 3 baud rates it supports: 512bps, 1200bps and 2400bps. In order to support the eye detection and blind decimation used by Decoder, you need to select a PCM sample rate that is evenly divisible by all 3 of those values. Deocoder expects, all said and done, that the sample rate the PCM module will see is 38.4kHz.

Assuming you're using multifm, you might want your output sample stream to be arriving at 48kHz. An easy way to do this, when using RTL-SDR, is to set your input sample rate to 1.2MHz in multifm, then decimate each channel by 25x, to get to 48kHz. Then, for Decoder you'd want to interpolate by a factor of 28 and then downsample by a factor of 35. This gives 48kHz * (28/35) = 38.4 kHz.

The Filter

In order to decimate without your signal of interest being impacted by aliasing, you must provide a resampling filter kernel. This filter must be a low pass filter, whose stop band is at most min(F_in, F_out), as to avoid aliasing and images.

A sample filter kernel is included for resampling from 25kHz to 16kHz (etc/resampler_filter.json). A script, scripts/design_interpolation_filter.py can help design additional filters. This script uses GNUradio to actually design the filter. The resulting filter definition is dumped to the console, and can be piped to a file for use with Decoder. Run scripts/design_interpolation_filter.py for a list of arguments.

Decoder Filter File

Decoder expects a filter specified using the following parameters:

• decimate (integer): The decimation factor. This is used for reference purposes only.
• interpolate (integer): The interpolation factor. For reference purposes only.
• fractionalBw (float): The fractional bandwidth. For reference purposes only.
• lpfCoeffs (array of floats): The coefficients for the low-pass filter for resampling.

This JSON file is loaded and used to parameterize the built-in rational resampler.

Configuring Decoder

Decoder expects information about the input sample stream, the center frequency of the data stream (this is for reference only), and the source for the raw input samples. For most users, the basic arguments will be:

• -m [receive mode] - specify the protocol to receive. This is one of AIS, FLEX or POCSAG, depending on the message type you want to receive.
• -D [decimation] The decimation factor
• -I [interpolation] The interpolation factor
• -F [filter file] The filter definition, which can be generated using scripts/design_interpolation_filter.py.
• -S [input sample rate] The input sample rate of the provided sample source
• -f [center frequency] The actual center frequency of the pager channel (for housekeeping only)
• -i Invert input samples. This works around rtl_fm and other tools that don't correct the phase of the downsampled signal.

The final argument is always the source of the samples. This could be a file or a FIFO.

Sourcing Demodulated Samples from GQRX

GQRX has the ability to export filtered PCM samples over UDP. If you were doing this just from localhost, you can use netcat to grab the samples and pump them out to stdout. Assuming that you've configured GQRX to output its demodulated audio stream as a 48kHz sample stream, and that the samples are to be sent to UDP port 7355, you could invoke decoder as follows:

nc -l -u localhost 7355 | decoder -m FLEX -D 48 -I 16 -F etc/resampler_filter.json -S 48000 -f 931937500 /dev/stdin

When you select 'UDP' as the output target for GQRX, you should start seeing messages being decoded. Make sure you have set a 25kHz wide filter with NFM demodulation for this to work correctly.

Sourcing Demodulated Samples from rtl_fm

Using Decoder with RTL_FM is similar to working with GQRX. However, instead of invoking netcat, you can invoke RTL_FM directly:

rtl_fm -f 929.8375M -s 25000 -p -19 | decoder -m FLEX -i -D 25 -I 16 -F etc/resampler_filter.json -S 25000 -f 929837500 /dev/stdin

Note the additional -i flag passed to decoder. This is used to work around how rtl_fm handles phase information.

The details of using RTL_FM are beyond the scope of this guide, but have a look at the rtl_fm guide for more information.

Limitations

• Decoder probably doesn't support non-roman character sets correctly
• Decoder probably has bugs with some types of long FLEX CAPCODES
• Decoder doesn't have the ability (yet) to bypass the polyphase rational resampler
• Decoder doesn't provide a machine-readable way to get error metrics, yet.