RTLion Framework

Multipurpose RTL-SDR Framework for RTL2832 based DVB-T receivers.

Lack of a simple FFT visualizer tool for RTL-SDR was the main reason behind the rtl_map project which was released at January 30 and caught attention of RTL-SDR enthusiasts. Another purpose of that project was creating a Frequency Scanner tool that will provide FFT-based power (dB) scanning. So I decided to postpone that feature with a todo and dive into the other RTL-SDR related libraries such as pyrtlsdr for learning new stuff and also for creating that scanning tool.

pyrtlsdr is a wrapper library for librtlsdr that aims turning RTL2832U devices into an Software Defined Radio. librtlsdr itself contains main functions for RTL-SDR and have derived tools as rtl_sdr, rtl_fm etc. (More info can be found at wiki) pyrlsdr is written in Python and wraps most of the functions of librtlsdr successfully in order to provide a more Pythonic API. RTLion project uses pyrtlsdr to communicate with the RTL-SDR device.

RTLion project can be described as a framework due to the implementation of various features other than the frequency scanner. The common structure of the project is appropriate for adding new features too. RTLion Framework has a Flask-SocketIO based Web interface which houses it's features there. Web interface preferred to the command line interface for facilitating the usage and supporting remote operations. Matplotlib used for creating graphs, more specifically pylab psd (Power Spectral Density) method mostly used for converting the complex samples (stored in a numpy array) to FFT graphs.

Main purpose of the RTLion Framework is creating a framework for RTL2832 based DVB-T receivers and supporting various features such as spectral density visualizing and frequency scanning remotely. These features are provided on the Web interface and accessible via the RTLion server or the RTLion Android App for RTL-SDR & IoT applications.

Installation

Dependencies

• pyrtlsdr
  • librtlsdr*
• Flask-SocketIO
• Matplotlib

[*] librtlsdr must be installed for pyrtlsdr to access RTL-SDR device.

Clone the Repository

git clone https://github.com/RTLion-Framework/RTLion

Package Installation

Recommended installation:

pip3.7 install -r requirements.txt

Manual installation:

# [Install flask-socketio with pip]
pip3.7 install flask-socketio
# [Install matplotlib with your package manager]
# [Ubuntu]
sudo apt-get install python-matplotlib
# [Arch]
trizen python-matplotlib

Usage

Command Line Arguments

Command line arguments are not mandatory because it's possible to update settings at the Web interface. But still, RTLion server can be started with the command line arguments.

usage: RTLion.py [-h] [-d DEV] [-s SAMPRATE] [-f FREQ] [-g GAIN] [-n N] [-i I] [host:port]

Positional Arguments

[host:port] -> IP address/hostname and port number for server to listen on (default: 0.0.0.0:8081)

Optional Arguments

[-h, --help]                        -> show help message and exit
[-d DEV, --dev DEV]                 -> device index (default: 0)
[-s SAMPRATE, --samprate SAMPRATE]  -> sample rate (default: 2048000 Hz)
[-f FREQ, --freq FREQ]              -> center frequency (Hz)
[-g GAIN, --gain GAIN]              -> gain (0 for auto) (default: auto)
[-n N, -num N]                      -> number of the reads (default: -1, inf.)
[-i I, -interval I]                 -> interval between reads (default: 500ms)

Starting RTLion Server

Basically, execute the main file RTLion.py using Python3.7. (Command line arguments are optional.)

Power Spectrum

Web interface is accessible with using the RTLion server's host and port information.

After selecting the Power Spectrum (FFT Graph) option, it's possible to update settings and create graph.

Also center frequency can be changed real time via the range input element below the graph.

Frequency Scanner

Frequency scanner aims to find the peaks on a power spectrum for miscellaneous applications with using a sorting method. For doing that it takes 2 important arguments which can be listed as frequency range (min. - max.) and sensitivity.

RTLion computes frequency range and step size values automatically if center frequency parameter is given within the command line. Otherwise, the user should enter the frequency range manually.

Sensitivity value determines the count of the frequencies that will selected from the sorted list and can be changed with the range input element. Increasing the sensitivity causes scanned values to increase so it's important to use this parameter correctly depending on what the main goal is. Also it's easy to sight scanned values since RTLion marks them with a "x" on the graph.

Logs

RTLion Framework provides logging with command line and Web interface.

Android Application

It's possible to use RTLion Framework's features on a Android device via the mobile application. For more info, visit the RTLion-app repository.

RTLion with Docker

Dockerfile provided in the repository for using the RTLion Framework with Docker. Usable with the IoT applications.

Building the Image

Image can be built on the directory after cloning the repository.

docker build -t rtlion .

Running the Container

docker run -d --name rtlionfw -p 8081:8081 --privileged -v /dev/bus/usb:/dev/bus/usb rtlion

docker ps output:

Stopping & Removing the Container

docker stop rtlionfw
docker rm rtlionfw

IoT

At the IoT side of the project, it's possible to run RTLion server (with or without Docker) on a device like Raspberry Pi with the RTL-SDR plugged in and access the RTLion Framework remotely. (This concept can be diversified.)

Version 1.0

Prototype v1 is designed to be portable with Raspberry Pi 3 model B, RTL-SDR (RTL2832U / 820T2) and external power supply. RTL-SDR is half embedded inside the case and other half is outside for the antenna connection.

It's possible to disconnect RTL-SDR with unplugging the USB from Raspberry Pi.

RTL-SDR antenna connection is shown below.

Device can be powered by the power bank below the case. It shows the battery status with the LED indicator.

Inner Design of Version 1.0

The case contains a fan for cooling the Raspberry Pi and a female USB port for outer devices which leads to a USB connector. This USB adapter connection is required for embedding the RTL-SDR circuit inside the case and getting rid of redundant design of connecting RTL-SDR to the Raspberry Pi's USB port.

Of course this prototype design can be improved due to the existence of other Raspberry Pi versions such as Zero.

Accessing the Server

After starting the RTLion server on Raspberry Pi, connection can be made from the Web interface or the mobile application and the RTL-SDR functions can be accessed.

DVB Driver Issue

librtlsdr can't access the RTL-SDR device when the Linux kernel DVB driver is loaded and shows the warning message below.

Kernel driver is active, or device is claimed by second instance of librtlsdr. In the first case, please either detach or blacklist the kernel module (dvb_usb_rtl28xxu), or enable automatic detaching at compile time.

Unloading driver solves the issue temporarily.

sudo rmmod dvb_usb_rtl28xxu rtl2832

Visit blacklist_dvb_usb_rtl28xxu for more info and permanent solution.

TODO(s)

Considerable for future versions.

• Implement modulation and audio support (AM/FM)
• Fix step size calculation for not wide frequency ranges
• Make more responsive web interface
• Minimalize the Dockerfile for a lighter build
• Add new features to graphs (saving as png, txt)
• Improve the IoT side of the project (use rtl-sdr v3)
• Support custom delay between new frequencies when scanning
• Scanning in background

Contribution

RTLion Project is open to contributions.*

License

GNU General Public License (v3)

Copyright

Copyright (c) 2019-2020, orhun