1.3 Raspberry Pi 'Headless' RTLSDR RX Guide - projecthorus/horusbinary GitHub Wiki

This guide is intended to assist setting up a demodulator for a Horus Binary signal on a single-board computer like a Raspberry Pi, that may or may-not have a screen attached (and hence is 'headless'). Reception is performed using a RTLSDR - I recommend the RTLSDR v3 dongles.

I use this headless approach as the primary telemetry reception system in my HAB chase car.

1. Hardware Requirements

  • Ideally, a standalone single-board computer (Raspberry Pi 3, ODroid, etc...) to run the software. Other Linux machines will also work.

  • A RTLSDR receiver.

    • A receiver with a TCXO is highly recommended, and you must make sure the PPM offset value is set correctly (discussed later). The warm-up drift of the non-TCXO RTLSDRs can be significant enough that the wanted signal doesn't stay within the receiver passband. I've had great success with the RTL-SDR.com 'v3' dongles. The NooElec SMArt dongles (with the TCXO option) are also good. You can determine the ppm offset via a number of methods, such as kalibrate-rtl (if you have GSM signals nearby) or using LTE-Cell-Scanner, if you only have LTE around (i.e. Australia).

  • An antenna suitable for receiving on 434 MHz (a basic 1/4 wave monopole is usually good enough, or any other amateur 70cm antenna.

  • For optimal receive performance, a preamplifier and a band-pass filter, like this one. You can still achieve pretty good results without one.

2. Setup & Configuration

This section is intended to assist with setup under a fresh Raspbian installation. The instructions should be usable on other Debian-based systems.

For a good guide on setting up a 'headless' (no display) Raspberry Pi 2/3/Zero/ZeroW, look here.

2.1. Software Dependencies

We may require a few dependencies to be able to compile and use the new modem and uploader scripts. Under Ubuntu/Debian/Raspbian, you can install the required packages using:

$ sudo apt-get install subversion cmake build-essential libfftw3-dev libspeexdsp-dev libsamplerate0-dev libusb-1.0-0-dev git python-crcmod python-requests python-pip sox bc rtl-sdr

Under OSX, Macports or Homebrew should be able to provide the above packages, though they may be named slightly differently.

If the python-crcmod and python-requests packages are not available via your package manager, you can try installing them via pip using sudo pip install crcmod requests.

2.2 RTL-SDR from source

As we may we wish to use the bias-tee option in the newer v3 RTLSDRs, we need a fairly recent version of the rtl-sdr software. Recent ubuntu distributions provide this support in the rtl-sdr package (package version 0.5.3-12 or newer), however at the time of writing (2019-05-17), Raspbian still does not (come on guys...).

If your package manager's version of rtl-sdr does not provide bias-tee support (no -T option), then you will need to compile from source:

$ git clone https://github.com/osmocom/rtl-sdr.git
$ cd rtl-sdr
$ mkdir build
$ cd build
$ cmake -DINSTALL_UDEV_RULES=ON -DDETACH_KERNEL_DRIVER=ON ../
$ sudo make install
$ sudo ldconfig

IMPORTANT NOTE: Make sure to remove any installations of rtl-sdr already on your system before compiling/installing from source. (i.e. sudo apt-get remove rtl-sdr librtlsdr0 librtlsdr-dev

2.2.1 RTL-DVB Kernel Module Blacklisting

Because the kernel rtl_dvb driver (yes, these SDRs can be used to watch TV after all) will inhibit our intended use, we need to blacklist a few kernel modules.

If you installed rtl-sdr from source as above, then a blacklist file should have already been installed, otherwise create a new module blacklist file using:

$ sudo nano /etc/modprobe.d/rtlsdr-blacklist.conf

and add the lines:

blacklist dvb_usb_rtl28xxu
blacklist rtl2832
blacklist rtl2830
blacklist dvb_usb_rtl2832u
blacklist dvb_usb_v2
blacklist dvb_core

Save the file (Ctrl+x, y), and reboot the Raspberry Pi.

2.2.2 - Check your RTLSDRs are working!

At this point it is worth checking that you can communicate with your RTLSDR, which can be achieved by running:

$ rtl_test

Found 1 device(s):
  0:  Realtek, RTL2838UHIDIR, SN: 00000002

Using device 0: Generic RTL2832U OEM
Found Rafael Micro R820T tuner
Supported gain values (29): 0.0 0.9 1.4 2.7 3.7 7.7 8.7 12.5 14.4 15.7 16.6 19.7 20.7 22.9 25.4 28.0 29.7 32.8 33.8 36.4 37.2 38.6 40.2 42.1 43.4 43.9 44.5 48.0 49.6
[R82XX] PLL not locked!
Sampling at 2048000 S/s.

Info: This tool will continuously read from the device, and report if
samples get lost. If you observe no further output, everything is fine.

Reading samples in async mode...

Hit Ctrl+C to kill rtl_test. If you see lots of warnings such as lost at least <X> bytes, this indicates USB bandwidth issues, or some other issue with the RTLSDR. One or two lines are usually OK...

2.3. Downloading this Repository

You can either clone this repository using git:

$ git clone https://github.com/projecthorus/horusbinary.git

or download a zip file of the repository from here.

2.4. Compiling Horus-Demod

We need to compile the horus_demod binary (taken from the codec2 repository). This can be accomplished by performing (within this directory):

$ cd src
$ make
$ cd ../

3. Configuration File Changes

Copy the example configuration file user.cfg.example to user.cfg, i.e.:

$ cp user.cfg.example user.cfg

The file user.cfg should then be modified to reflect the callsign you wish to use when uploading data to Habitat. Simply change the following section as appropriate:

[user]
# Your callsign -  used when uploading to the HabHub Tracker.
callsign = YOUR_CALL_HERE

# Your station latitude/longitude, which will show up on tracker.habhub.org.
# These values must be in Decimal Degree format.
# Leave the lat/lon at 0.0 if you do not wish your station plotted on the map,
# or if you are uploading your position via other means (i.e. using chasemapper)
station_lat = 0.0
station_lon = 0.0
# Radio/Antenna descriptions.
# An optional short description of your radio/antenna setup.
radio_comment = Your Radio Description Here
antenna_comment = Your Antenna Description Here

4. Startup Script Modification

There are two receiver startup scripts available:

  • start_rtlfm.sh - Receives a single Horus Binary signal.
  • start_dual_rx.sh - Receives a closely spaced (~10 kHz) Horus Binary and RTTY payload simultaneously.

You will likely need to edit these scripts to change settings such as receive frequency, PPM offset, or Chasemapper output settings. The scripts are fairly well commented, and should be reasonably self-explanatory.

Once modified, you can simply start reception by running:

$ ./start_rtlfm.sh

This will produce output similar to the following:

$ ./start_rtlfm.sh
Found horus_demod.
Found bc.
Using SDR Centre Frequency: 434654000 Hz.
Using FSK estimation range: 1000 - 11000 Hz
Using AGC.
Found 1 device(s):
  0:  Realtek, RTL2838UHIDIR, SN: 00000003

Using device 0: Generic RTL2832U OEM
2020-02-09 17:12:30,456 INFO: Attempting to download latest payload ID list from GitHub...
Found Rafael Micro R820T tuner
2020-02-09 17:12:30,566 INFO: Payload ID list updated successfully.
2020-02-09 17:12:30,567 INFO: Known Payload IDs:
2020-02-09 17:12:30,567 INFO: 	0 - 4FSKTEST
2020-02-09 17:12:30,567 INFO: 	1 - HORUSBINARY
2020-02-09 17:12:30,567 INFO: 	2 - VK5BRL
2020-02-09 17:12:30,568 INFO: 	3 - STRATOS
2020-02-09 17:12:30,568 INFO: 	4 - HORUSBINARY2
2020-02-09 17:12:30,568 INFO: 	5 - HORUSBINARY3
2020-02-09 17:12:30,568 INFO: 	6 - PE2BZ-4FSK
2020-02-09 17:12:30,568 INFO: 	7 - SP8NCG-4FSK
2020-02-09 17:12:30,569 INFO: 	8 - PY2UEP-4FSK
2020-02-09 17:12:30,569 INFO: 	9 - PC4L-4FSK
2020-02-09 17:12:30,569 INFO: 	10 - HAPPYSAT-4FSK
2020-02-09 17:12:30,570 INFO: 	11 - PH1M-4FSK
2020-02-09 17:12:30,570 INFO: 	12 - DK0WT-4FSK
2020-02-09 17:12:30,570 INFO: 	13 - PE1ANS-4FSK
2020-02-09 17:12:30,570 INFO: 	23 - MAGNU
2020-02-09 17:12:30,570 INFO: Using User Callsign: VK5QI-9
2020-02-09 17:12:30,570 INFO: No user position supplied, not uploading position to Habitat.
2020-02-09 17:12:30,571 INFO: Started Habitat Uploader Thread.
2020-02-09 17:12:30,571 INFO: Waiting for data on stdin.
2020-02-09 17:12:30,571 INFO: Started Horus Binary Uploader. Hit CTRL-C to exit.
Tuner gain set to automatic.
Tuned to 435038000 Hz.
Oversampling input by: 32x.
Oversampling output by: 1x.
Buffer size: 5.33ms
Sampling at 1536000 S/s.
Output at 48000 Hz.
2020-02-09 17:12:33,910 INFO: Hexadecimal Sentence: 000100000000000000000000000000000000269FB1F6
2020-02-09 17:12:33,912 INFO: Decoded Binary Telemetry as: $$4FSKTEST,1,00:00:00,0.00000,0.00000,0,0,0,38,3.12*8BB7
2020-02-09 17:12:33,916 ERROR: Could not parse ASCII Sentence - Zero Lat/Long.
2020-02-09 17:12:33,916 ERROR: Horus UDP - Zero Latitude/Longitude, not sending.
2020-02-09 17:12:35,063 INFO: Habitat - Uploaded sentence to Habitat successfully

Note that output from rtl_fm and the horus binary uploader are interleaved, which can be a bit confusing at first.

5. Startup on Boot.

There are a number of ways of starting up a script when a Linux machine starts up. One of the simplest is to add the script to be run to /etc/rc.local

For example, you could add the following line to the end of your /etc/rc.local file:

/home/pi/horusbinary/start_rtlfm.sh &

Note the &, which places the process into the background and lets the system continue to boot.

** TODO: Systemd unit file **