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_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.
[*] librtlsdr must be installed for pyrtlsdr to access RTL-SDR device.
Clone the Repository
git clone https://github.com/RTLion-Framework/RTLion
pip3.7 install -r requirements.txt
# [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
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]
[host:port] -> IP address/hostname and port number for server to listen on (default: 0.0.0.0:8081)
[-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
Python3.7. (Command line arguments are optional.)
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 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
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.
RTLion Framework provides logging with command line and Web interface.
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
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.)
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
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.
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
RTLion Project is open to contributions.*
GNU General Public License (v3)
Copyright (c) 2019-2020, orhun