KerberosSDR Quickstart Guide

Note: If you have issues or questions please ask in our KerberosSDR forum. We are working on an official tutorial video, but for now SignalsEverywhere has one up here.

Powering and Connecting the Hardware

Your KerberosSDR should already come fully assembled.

As there are four on board RTL-SDRs, KerberosSDR has fairly high power requirements. A single USB 3.0 port on a computer that can handle up to 3A is enough to power the device from one high quality USB cable. Note that only the microUSB port is connected to the computers USB port and that the USB-C port is only for  additional power.

If you only have USB 2.0 hardware, or cannot provide 3A from the USB port (e.g. single board PCs cannot provide this much current), then you'll need to plug a second power source into the USB-C port on the KerberosSDR. USB-C is used for the dedicated power port as it has much less voltage drop, and the cables are generally higher quality. This power source should be an plugged into a wall 5V USB supply or external 5V battery if going portable.

Note that the USB-C port will not activate for high voltage "power delivery" (PD) USB-C power supplies, such as those used with laptops. It will only work on normal 5V power supplies.

KerberosSDR Labelled Ports
KerberosSDR Labelled Ports

Antenna 1 is the port to the left. You can confirm this by looking at the DIP switches. The writing on the DIP switches indicates the antenna order.

Raspberry Pi/Single Board Computer (SBC) Ready to Use Images

Download the appropriate .img file below, unzip it, and burn it to an 8GB or larger SD Card for your SBC using Win32DiskImager or Etcher. 

On your SBCs, it is important to make sure thermal throttling is not occurring (via appropriate heatsinking/fans if needed) otherwise sample loss, and hence sample lock failure may occur.

Raspberry Pi 3 / B+

Download IMG V1.2: https://drive.google.com/open?id=11OJb9EIji8cqjRxMgwzssRAh_yKgunwe

Download IMG V1.1: https://drive.google.com/file/d/1NH95yR94vVpwC8cIBe3-3ig5_T4ot3mF/view?usp=sharing

WiFi Hotspot: KerberosPi
WiFi Password: KerberosPi

VNC Username: pi
VNC Password: raspberry

Default IP address for VNC: 192.168.4.1
Address for Web Control: 192.168.4.1:8080/init
Address for Android App: 192.168.4.1:8081

Tinkerboard

Download IMG V1.2: https://drive.google.com/open?id=1XUY4mUhqwrXRc5CdMlc3d9w2Zg0X3mbI

Download IMG V1.1: https://drive.google.com/open?id=1GJwZpRe3HxhLSLxRrQtxsEUUVCI6VaZJ

WiFi Hotspot: Kerberos_Tinker
Password: kerberos
Linux Password: kerberos

Default IP address for VNC: 192.168.4.1:5900
Address for web control: 192.168.4.1:8080/init
Address for Android App: 192.168.4.1:8081

Note please see our current issues forum thread for currently known issue.

Changelog v1.2: Computation is now significantly faster, and CPU usage has been reduced on the Pi 3 by changing the default BLAS libraries.

Other SBCs

We have decided to release images only for the Pi 3 and Tinkerboard at the moment. Other SBCs like the Odroid XU4 do not have built in WiFi and the Rock Pi 4 appear to have show stopping bugs with the WiFi Hotspot which we use for connections. However, the software does work on the XU4 and Rockpi4, so feel free to manually install it.

SBC Quickstart

  1. Burn SD Card and insert into SBC (or flash eMMC).
  2. Plug KerberosSDR into SBC, and USB C power.
  3. Turn on SBC, and wait a couple of minutes for boot.
  4. Connect to WiFi hotspot on your laptop/phone/tablet.
  5. Enter the address for web control in a browser.
  6. Go through configure and sync steps described further below.

Installing the software on a PC / Other SBC

The KerberosSDR software has been tested on Ubuntu Debian systems.

Install Dependencies via apt:

sudo apt update
sudo apt install python3-pip python3-pyqt4 build-essential gfortran libatlas3-base libatlas-base-dev python3-dev python3-setuptools libffi6 libffi-dev python3-tk pkg-config libfreetype6-dev php-cli wondershaper

Just in case, try to uninstall any previously installed numpy packages as we want to install with pip3 to get optimized BLAS routines.

sudo apt remove python3-numpy

Install Dependencies via pip3:

pip3 install numpy
pip3 install matplotlib
pip3 install scipy
pip3 install cairocffi
pip3 install pyapril
pip3 install pyargus
pip3 install pyqtgraph
pip3 install peakutils 
pip3 install bottle
pip3 install paste

Install RTL-SDR-Kerberos Drivers

Our Kerberos RTL-SDR driver branch contains code for slightly modified Osmocom RTL-SDR drivers that enable GPIO, disable dithering, and disables zerocopy buffers which seems to cause trouble on some ARM devices.

sudo apt-get install libusb-1.0-0-dev git cmake 

git clone https://github.com/rtlsdrblog/rtl-sdr-kerberos

cd rtl-sdr-kerberos
mkdir build
cd build
cmake ../ -DINSTALL_UDEV_RULES=ON
make
sudo make install
sudo ldconfig

echo 'blacklist dvb_usb_rtl28xxu' | sudo tee --append /etc/modprobe.d/blacklist-dvb_usb_rtl28xxu.conf

Now you may need to reboot, but on most systems you should be able to run rtl_test as described below already.

Test 4x Tuners (Optional)

At this stage we recommend first testing your four tuners with rtl_test. Open four terminal windows, or tabs, and in each window run "rtl_test -d 0", "rtl_test -d 1", "rtl_test -d 2" and "rtl_test -d 3". Ensure that each unit connects and displays no errors.

Install and Run KerberosSDR Demo Software

Clone the demo software from the GitHub:

cd ~
git clone https://github.com/rtlsdrblog/kerberossdr

If you are running on an SBC, you will probably want to first edit the C code Makefile compiler flags to be optimized for your particular architecture. The Makefile is stored in _receiver/C. Otherwise if running on a PC/laptop, simply run the following script to compile the code.

cd kerberossdr
sh setup_init.sh

(Optional if you are using an SBC and/or intend to use the web interface features). Using a text editor like gedit or nano, edit the IP address parameter in run.sh, and set it to your machines IP address. On SBCs you may also wish to enable the lines in run.sh that enable the "performance" CPU mode to reduce the likelihood of CPU throttling. On a Pi 3 or other SBC that shares Ethernet/WiFi and USB bandwidth please also enable the wondershaper lines, to ensure the USB bandwidth is sufficient.

Now you can run the software by typing:

./run.sh

Synchronizing and Calibrating KerberosSDR in the Demo Software

These steps assume that you've connected your KerberosSDR to the PC and power. The steps to the software are summarized as follows:

  1. Set the frequency, sample rate and gain settings.
  2. Calibrate the SDR with the noise source.
  3. Connect antennas.
  4. Use the DOA or Passive Radar tabs.

Step 1: Setting The Frequency and Gain

  1. Click on the Configuration and Spectrum screen
     
  2. Click on start processing. Confirm that an update rate is showing.
     
  3. Under receiver configuration enter the center frequency of your signal of interest, and a sampling rate. For sampling rates we recommend 2.56 MSPS for passive radar, and 1.0 MSPS for direction finding.
     
  4. Set the gains for each receiver as required to optimize the signal SNR. The gains of each receiver must be set at 15.7 or higher in order to successfully sync KerberosSDR. (Note that Passive Radar only needs the first two receivers, but you still need to set the gains on all receivers above 15.7 for sync)

  5. Click on the "Set" button to write the frequency, sampling rate and gain settings to the KerberosSDR.
     
  6. Check DC compensation on for slightly better results (optional).
     
  7. Click the "Enable spectrum display" checkbox if desired to check the spectrum. This will show you the spectrum visually and you can check that your signals are being received.
     
  8. Disable the spectrum display when finished to reduce the CPU load.
Configuration and Spectrum Screen
Configuration and Spectrum Screen

Synchronization and Calibration Process

Initial Step: When synchronizing, we recommend disconnecting your antennas first.

  • Direction Finding: Disconnect antennas and optionally connect the included 4x 50 Ohm terminators. Connecting the terminators is optional, but doing so may give you slightly more accurate results. You must perform both sample and phase calibration.
  • Passive Radar: If you are doing passive radar, you do not need to connect the terminators. Only sample calibration is required. 

Alternatively, you can also synchronize your KerberosSDR with the antennas connected. BUT, if there are signals within the bandwidth being currently received then this can distort the phase calibration. So we recommend checking for signals first in the spectrum graphs.

NOTE: Always calibrate with the FIR filter set to zero, and the decimation set to 1.

  1. Calibration assumes that you have already set the desired frequency, sample rate and gains. Every time you change those settings by clicking on the "Set" button, you will need to re-calibrate.
     
  2. Click on the Sync tab.
     
  3. Enable the Noise source and sync display check boxes. Notice that the Abs X corr graph has three peaks, and that the Sample delay history and phase diff history is non-zero. This indicates that the KerberosSDR is not synced.

    Unsynced KerberosSDR Graphs
    Unsynced KerberosSDR Graphs
      
  4. Click on "Sample Sync". Wait until the sample delay history graph and Abs X Corr graphs become zero'd.
     
  5. If doing direction finding, click on Correct IQ. Wait until the Phase diff history graph is zero'd.
     
  6. At this point KerberosSDR is in sample and phase sync. Please note that you must perform these steps every time you start the application, or every time that you tune to a different frequency or change the gain settings.

    Kerberos SDR Synchronized
    Kerberos SDR Synchronized
     
  7. You can now uncheck the noise source and graph check boxes.

Direction Finding

These steps assume that the synchronization and phase calibration steps have been completed.

  1. Connect your direction finding antenna array (more details on that below), and go back to the Configuration and Spectrum tab.
     
  2. Enable the spectrum display and check that your signal of interest is centered in the spectrum display.
     
    Tuned to a signal of interest
    Tuned to a signal of interest
     
  3. Using the decimation, FIR tap size and filter BW settings, reduce the bandwidth so that only the centered signal of interest is being received. You will want to use these options to filter out other signals, so that only your signal of interest is being received. Increasing FIR filtering will increase computation time, thus decreasing the update rate. Increasing decimation will reduce computation time, making the update rate faster again.
     
    NOTE: The decimation value must be a power of two with a maximum value of 8, for example: 1, 2, 4, 8. A decimation value of 2 will halve the bandwidth, a value of 4 will halve it once again.
     
    The filter bandwidth and FIR tap size settings are related. The Filter BW setting should be set to the bandwidth of the signal of interest. For example for a narrow band signal that might be 15 kHz. The FIR tap size sets how tight the filtering is. Higher values result in tighter filtering which blocks other signals more. But this comes at the expense of higher CPU usage. A typical FIR tap size is 100.
     
    Note that if you need to resync in the future, you must reset the FIR tap size back to zero, and Decimation back to 1 before syncing.

    Decimation set to four. Bandwidth halved twice, this has zoomed in on the signal of interest.
    Decimation set to four. Bandwidth halved twice, this has zoomed in on the signal of interest.
    FIR filter enabled
    FIR filter enabled. Nearby signals removed from bandwidth. Only the signal of interest remains.
     
  4. Disable the spectrum display.
     
  5. Click on the DOA Estimation tab.

  6. Use the Arrangement drop down box to choose whether your antennas are arranged in a uniform linear array (ULA) or uniform circular array (UCA) (see further for details).

  7. Set the spacing factor of your antennas (see further for details).

  8. Check the Enable box, and choose a DOA method. The best method for most applications would be MUSIC.

  9. You will now see a graph that should indicate the incident angle.

    DOA Screen showing incident angle
    DOA Screen showing incident angle (peak indicates angle)

Antenna Spacing

For a linear array, the antennas need to be spaced out from one another ideally at a spacing factor of somewhere between 0.2 - 0.5 times the frequency wavelength. For a circular array, 0.3 - 0.3535 works well.

Larger spacing factors result in high degree resolution (especially at the edges), but require more space. Please experiment with different spacing factors, but we've found that 0.3 tends to work well in most cases.

This means that low frequencies can potentially require very large antenna spacing. Please use an online wavelength calculator to determine the full 1/1 wavelength of the frequency you are interested in. Multiply the full length wavelength by the spacing factor and then by three, to get the full linear antenna array length required.

Antenna inter-element spacing = wavelength * chosen spacing factor

Total Linear Antenna Array Length Required = wavelength * chosen spacing factor * 3

Example

So for example, if the frequency you wanted to find the direction of was 858 MHz:

Frequency = 858 MHz
Wavelength (Lambda) = 0.35 m
Chosen Spacing Factor = 0.3

Antenna Inter-element Spacing = 0.35 m x 0.3 = 0.105 m

Direction Finding Antenna Arrangements

ULA - Uniform Linear Array. 

This is simply a straight line of omnidirectional antennas spaced out at lamdba * s, where lambda is the frequency wavelength, and s is some spacing factor. Ideally the best spacing factor for ULA is somewhere between 0.3 to 0.5.

We recommend starting your direction finding experiments with a uniform linear array as this is the easiest antenna arrangement to get good non ambiguous, multipath resistant results with. The circular array could produce more false results due to the greater risk of multipath.

If going hand held, it can be a good idea to place the antennas on a stick that can be rotated. The most accurate results come from when the antennas are at 0 degrees (facing the signal). So one technique is to rotate the stick until the KerberosSDR software reads 0 degrees. A compass can be placed in the middle of the stick, and the direction perpendicular to the antennas is the direction of the transmitter.

Uniform Linear Antenna Array
Uniform Linear Antenna Array

UCA - Uniform Circular Array

This has the antennas arranged in a circle. The maximum radius without ambiguities is lambda/(2*sqrt(2)) which is approximately lambda * 0.3535.

With a circular array there are a lot more ambiguities and chances for multipath so it can be a lot more difficult to get good results.

Uniform Circular Antenna Array
Uniform Circular Antenna Array

Physical Limitations of Direction Finding and Things to Know

With direction finding it's important to understand the limitations imposed by physics and the nature of RF.

Ambiguities: With direction finding there can be ambiguities in certain configurations. That means that at some specific incidence angles, it is possible that the algorithms will converge to the wrong detected angle, or will detect two angles.

Multipath: Multipath is when signals bounce of walls and other objects. This can cause a signal to appear to be coming from another direction. If you're using a linear antenna array, you can enable Forward-Backward averaging which can help, but could also make things worse. A directional linear antenna array (like an array of patch antennas) could work even better to reduce the effect of multipath. To get around multi-path issues, we recommend using a vehicle and driving around with our Android app (see below). By moving around you can get multiple readings and ignore false multipath readings.

Other Direction Finding Tips

Watch out for signal reflections from the KerberosSDR enclosure itself, your laptop, and any nearby objects. These can skew the results. If possible have these objects underneath the antenna array.

We recommend using short high quality shielded coax cables on all your antennas. If signals enter through the coax cable, this can distort the direction finding system.

DOA Algorithms

In the demo software there is a choice from the Bartlett, Capon, MEM and MUSIC direction finding algorithms. Generally we find that Capon and MUSIC are the most reliable.

When using a linear array you can activate FB Averaging (Forward-Backward), which averages signals coming in from behind and in front of the antenna array. This reduces the effect of multipath reflections, but can also cause the angle to become skewed. Do not turn it on when using a circular array.

Direction Finding Android App and Web Compass Display

App Download: https://play.google.com/store/apps/details?id=com.kevin.realtimebearing

To use the app you must connect your phone to the machines WiFi hotspot. If you are running on a laptop you will need to set this up yourself. If you're running on a single board PC with one of our images the hotspot is already set up. Before using the app or web compass ensure that you have correctly set your machines IP address in the run.sh file.

Compass Display

The compass display runs via a webpage. Browse to http://IP_ADDR:8081/compass.html

Android App Usage

  1. Set the KerberosSDR software on your PC/laptop/SBC to direction finding, and enable a direction finding algorithm. 
     
  2. Open the app on your phone.
     
  3. If you intend to use the app while connected to a the WiFi hotspot of a single board computer or laptop, then we recommend first downloading the offline maps of the area you are going to be in during the direction finding mission.
     
    To do this zoom out on the map so that your view covers the area that you will be searching. In the top right of the app, click on the downwards facing arrow. Enter the region name and click on Download. This will save the offline map to your device.
     
  4. After downloading offline maps, connect your phone to the hotspot or same network of the machine running KerberosSDR.
     
  5. Next using the menu hamburger (three dots on the top right) open the settings.
     
  6. Change the server address to IP_ADDR:8081, where IP_ADDR should be replaced with the IP address of the machine running KerberosSDR.
     
  7. Set your desired update interval (generally 1s is desired).
     
  8. Choose whether or not you are using a linear or circular antenna array under the "Radio Search Mode"->"Search Mode" options. If using a linear array, we suggest setting the "Linear Search Direction" setting to both. This will show you both possible direction solutions (back and forward) for a linear array.

  9. Choose the bearing mode that you are using. If you're walking or driving around in a car, GPS mode will be the most accurate. If you are stationary and have calibrated your phones compass, you can try the compass mode, although phone compasses are quite inaccurate. Otherwise if you are stationary you can use the manual mode.
     
  10. If you will be logging data, enable logging.

  11. Go back to the map by using the back arrow.
     
  12. Press the red timer icon on the bottom right to begin direction finding. Once pressed you should see lines indicating the user bearing, and the RF bearing.

  13. If you are logging, you can now walk/drive around with your KerberosSDR.

  14. Once done, press on the red timer icon again to stop direction finding, and stop logging.
     
  15. You can now show your log file by pressing on the Show/Hide Log in the top right menu. NOTE: If your log file is large (been driving around for many minutes) we suggest setting the "plotting step" setting to 10 or higher, to skip every 10th point. Otherwise the app may struggle to plot all logged points.

NOTE: The current version 1.0 of the app has a bug in that the antennas are calculated in reverse from the antenna image shown above. To get around this, go into settings and turn on "Reverse Antenna". An upcoming release will change this behavior back to normal.

Passive Radar

Normal radar systems work by transmitting a pulse of RF energy, and listening to the reflections from objects like planes, cars and ships. Passive radar works by using already existing transmitters such as those for FM/TV and listening for reflections that bounce of objects.

With a simple passive radar system you need two directional antennas and two coherent receivers. One antenna points at the transmitting 'reference' tower, and the other at the 'surveillance' area where you want to listen for reflections. It's important to try and keep as much of the reference signal out of the surveillance antenna as possible, which is why directional antennas like Yagi's are used.

The result is a doppler vs time delay graph, where the reflection of aircraft, cars, ships and other objects can be seen. The doppler gives you the speed of the object relative to your antenna and the transmitting tower, and the time delay gives you the distance relative to your antenna and the transmitter tower.

Passive radar is quite dependent on the geometry of your location, so may not work everywhere.

To set up a passive radar you'll first need to determine where in your area a strong FM, DAB or DVB-T signal originates from. You'll also need to determine what you want to track, whether it be ships, cars or aircraft. Ideally the objects and the transmitting tower will be located 180 degrees out from one another, but smaller angles can be tolerated. We've found that about ~70 degrees seems to be the limit. The idea is to prevent the direct signal from the transmit tower coming in through the surveillance antenna.

Passive Radar Setup
Passive Radar Setup

Tips: 

  • To reduce the number of direct signal entering the surveillance antenna use a high directivity antenna like a Yagi
  • Use your house or car to shield your surveillance antenna from the direct signal.

Passive Radar Software Setup

Notes on the settings:

Reference: This is the channel that the antenna pointing towards the transmitter is connected to. (With 0 being the first channel, and 3 being the last channel).

Surveillance: This is the channel that the antenna pointing towards the objects of interest is connected to.

Sample Size: The number of samples to use. Higher may result in cleaner results, but slower updates.

Time Domain Clutter Suppression: Suppresses signals reflections from static objects (clutter). Will most likely need to be always on, otherwise the clutter can cause the actual objects to be lost in the noise.

Method: Clutter Suppression method, currently only Wiener - SSMI is available.

Filter Dimension:  How far on the PR radar display do you want clutter suppression to be active. Increasing this value enables clutter suppression to be active at further distances. Typically set equal to the max range, but could be reduced to reduce CPU usage.

Max Range: Must be a power of 2 (e.g. 64, 128, 256, 512). Up to what range of the radar graph do you want to display.

Max Doppler: The max speed on the radar graph that you want to display.

Windowing: The windowing function used in the algorithm. Minor effect, but experiment with this.

Dynamic: Essentially the contrast of the passive radar display. Adjust this so that actual detected objects are displayed strongly on your graph.

We have set up the settings so that the defaults should be fine for most people. Simply enable time domain clutter cancelling, and passive radar processing to start. You can then try tweaking the settings.

Web Interface

If you have set your IP address in the run.sh file, the KerberosSDR demo software will host a web interface which can be used to control it on a headless system. This is useful for when running on a single board PC, without a monitor as you won't have access to the actual GUI. As an alternative to the web interface, you could also VNC into the machine.

To access the web interface ensure that both devices are connected to the same network, and then browse to (replacing ID_ADDR with the server IP Adress):

http://IP_ADDR:8080/init

On the Pi 3 and Tinkerboard you can connect to the WiFi hotpost and connect to the default IP address of 192.168.4.1.

On these pages you can set all the settings as in the GUI, and view the graphs. Settings will only be updated once you click on the "Update" or "Start" buttons.

[URIS id=29207]

KeberosSDR Other Notes

Heat Management

In hot environments with stale air, KerberosSDR may lose sample sync if the device gets too hot. In this case keep the device cool with a small amount of airflow. The bottom side of the box acts as a heatsink, so another tip is to place the box upside down or on its side, so that heat can dissipate better.

Block/Buffer Size (Advanced)

The block size is set by default to 256. A lower block size results in faster update rates, but less processing gain. This is most apparent with passive radar, where a lower block size results in less resolution.

To change the block size edit the run.sh file with a text editor. Change the BUFF_SIZE parameter to either 128, 256 (default) or 512. You will also need to edit the #define BUFF_LEN and BUFFER_SIZE values in rtl_daq.c, sync.c and gate.c (if changing block size to 128, halve them, if changing to 512, double them). run "make clean", and then "make" to recompile. Only faster computers will be able to handle the higher block size of 512. Using a block size of 128 will make the update rate much faster at the expense of processing gain.