[[PageOutline]]
= rtl-sdr =
DVB-T dongles based on the Realtek RTL2832U can be used as a cheap SDR, since the chip allows transferring the raw I/Q samples to the host, which is officially used for DAB/DAB+/FM demodulation. The possibility of this has been discovered by Eric Fry ([http://rtlsdr.org/#history_and_discovery_of_rtlsdr History and Discovery of RTLSDR]). Antti Palosaari has not been involved in development of rtl-sdr.
== Specifications ==
The RTL2832U outputs 8-bit I/Q-samples, and the highest theoretically possible sample-rate is 3.2 MS/s, however, the highest sample-rate without lost samples that has been tested so far is 2.56 MS/s. The frequency range is highly dependent of the used tuner, '''dongles that use the Elonics E4000 offer the widest possible range (see table below)'''.
||'''Tuner'''||'''Frequency range'''||
||Elonics E4000||52 - 2200 MHz with a gap from 1100 MHz to 1250 MHz (varies)||
||Rafael Micro R820T||24 - 1766 MHz||
||Rafael Micro R828D||24 - 1766 MHz||
||Fitipower FC0013||22 - 1100 MHz (FC0013B/C, FC0013G has a separate L-band input, which is unconnected on most sticks)||
||Fitipower FC0012||22 - 948.6 MHz||
||FCI FC2580||146 - 308 MHz and 438 - 924 MHz (gap in between)||
== Supported Hardware ==
'''Note:''' Many devices with EEPROM have 0x2838 as PID and RTL2838 as product name, but in fact all of them have an RTL2832U inside.[[br]]
Realtek never released a chip marked as RTL2838 so far.[[br]][[br]]
The following devices are known to work fine with RTLSDR software:
||'''VID'''||'''PID'''||'''tuner'''||'''device name'''||
||0x0bda||0x2832||all of them||Generic RTL2832U (e.g. hama nano)||
||0x0bda||0x2838||E4000||ezcap USB 2.0 DVB-T/DAB/FM dongle||
||0x0ccd||0x00a9||FC0012||Terratec Cinergy T Stick Black (rev 1)||
||0x0ccd||0x00b3||FC0013||Terratec NOXON DAB/DAB+ USB dongle (rev 1)||
||0x0ccd||0x00d3||E4000||Terratec Cinergy T Stick RC (Rev.3)||
||0x0ccd||0x00e0||E4000||Terratec NOXON DAB/DAB+ USB dongle (rev 2)||
||0x185b||0x0620||E4000||Compro Videomate U620F||
||0x185b||0x0650||E4000||Compro Videomate U650F||
||0x1f4d||0xb803||FC0012||GTek T803||
||0x1f4d||0xc803||FC0012||Lifeview LV5TDeluxe||
||0x1b80||0xd3a4||FC0013||Twintech UT-40||
||0x1d19||0x1101||FC2580||Dexatek DK DVB-T Dongle (Logilink VG0002A)||
||0x1d19||0x1102||?||Dexatek DK DVB-T Dongle (MSI DigiVox mini II V3.0)||
||0x1d19||0x1103||FC2580||Dexatek Technology Ltd. DK 5217 DVB-T Dongle||
||0x0458||0x707f||?||Genius TVGo DVB-T03 USB dongle (Ver. B)||
||0x1b80||0xd393||FC0012||GIGABYTE GT-U7300||
||0x1b80||0xd394||?||DIKOM USB-DVBT HD||
||0x1b80||0xd395||FC0012||Peak 102569AGPK||
||0x1b80||0xd39d||FC0012||SVEON STV20 DVB-T USB & FM||
People over at reddit [http://www.reddit.com/r/RTLSDR/comments/s6ddo/rtlsdr_compatibility_list_v2_work_in_progress/ are collecting a list (v2)] of other devices that are compatible.
If you find a device that is not yet in the device list but should be supported, please send the VID/PID and additional info (used tuner, device name) to our mailing list.
This is the PCB of the ezcap-stick:[[br]][[br]]
[[Image(ezcap_top.jpg,50%)]][[br]]
More pictures can be found [http://www.steve-m.de/pictures/rtl-sdr/ here].
== Software ==
Much software is available for the RTL2832. Most of the user-level packages rely on the librtlsdr library which comes as part of the rtl-sdr codebase. This codebase contains both the library itself and also a number of command line tools such as rtl_test, rtl_sdr, rtl_tcp, and rtl_fm. These command line tools use the library to test for the existence of RTL2832 devices and to perform basic data transfer functions to and from the device.
Because most of the RTL2832 devices are connected using USB, the librtlsdr library depends on the libusb library to communicate with the device.
At the user level, there are several options for interacting with the hardware. The rtl-sdr codebase contains a basic FM receiver program that operates from the command line. The rtl_fm program is a command line tool that can initialize the RTL2832, tune to a given frequency, and output the received audio to a file or pipe the output to command line audio players such as the alsa aplay or the sox play commands. There is also the rtl_sdr program that will output the raw I-Q data to a file for more basic analysis.
For example, the following command will do reception of commercial wide-band FM signals:
{{{
rtl_fm -f 96.3e6 -M wbfm -s 200000 -r 48000 - | aplay -r 48k -f S16_LE
}}}
On a Mac, a similar command that works is as follows. This assumes that the sox package is installed, 'port install sox':
{{{
rtl_fm -f 90100000 -M wbfm -s 200000 -r 48000 - | play -r 48000 -t s16 -L -c 1 -
}}}
If you want to do more advanced experiments, the GNU Radio collection of tools can be used to build custom radio devices. GNU Radio can be used both from a GUI perspective in which you can drag-and-drop radio components to build a radio and also programmatically where software programs written in C or Python are created that directly reference the internal GNU Radio functions.
The use of GNU Radio is attractive because of the large number of pre-built functions that can easily be connected together. However, be aware that this is a large body of software with dependencies on many libraries. Thankfully there is a simple script that will perform the installation but still, the time required can be on the order of hours. When starting out, it might be good to try the command line programs that come with the rtl-sdr package first and then install the GNU Radio system later.
The rtl-sdr code can be checked out with:
{{{
git clone git://git.osmocom.org/rtl-sdr.git
}}}
It can also be browsed via [http://cgit.osmocom.org/cgit/rtl-sdr/ cgit], and there's an official [https://github.com/steve-m/librtlsdr mirror on github] that also provides [https://github.com/steve-m/librtlsdr/releases packaged releases].
If you are going to "fork it on github" and enhance it, please contribute back and submit your patches to: osmocom-sdr at lists.osmocom.org
A [wiki:GrOsmoSDR GNU Radio source block] for [wiki:WikiStart OsmoSDR] '''and rtlsdr''' is available. '''Please install a recent gnuradio (>= v3.6.4) in order to be able to use it.'''
=== Mailing List ===
We discuss both OsmoSDR as well as rtl-sdr on the following mailing list: [mailto:osmocom-sdr@lists.osmocom.org].
You can subscribe and/or unsubscribe via the following link: [http://lists.osmocom.org/mailman/listinfo/osmocom-sdr]
=== Building the software ===
==== rtlsdr library & capture tool ====
'''You have to install development packages for libusb1.0''' and can either use cmake or autotools to build the software.
Please note: prior pulling a new version from git and compiling it, please do a "make uninstall" first to properly remove the previous version.
Building with cmake:
{{{
cd rtl-sdr/
mkdir build
cd build
cmake ../
make
sudo make install
sudo ldconfig
}}}
In order to be able to use the dongle as a non-root user, you may install the appropriate udev rules file by calling cmake with -DINSTALL_UDEV_RULES=ON argument in the above build steps.
{{{
cmake ../ -DINSTALL_UDEV_RULES=ON
}}}
Building with autotools:
{{{
cd rtl-sdr/
autoreconf -i
./configure
make
sudo make install
sudo ldconfig
}}}
The built executables (rtl_sdr, rtl_tcp and rtl_test) can be found in rtl-sdr/src/.
In order to be able to use the dongle as a non-root user, you may install the appropriate udev rules file by calling
{{{
sudo make install-udev-rules
}}}
[attachment:RelWithDebInfo.zip pre-built Windows version]
==== Gnuradio Source ====
'''The Gnu Radio source requires a recent gnuradio (>= v3.7 if building master branch or 3.6.5 when building gr3.6 branch) to be installed.'''
The source supports direct device operation as well as a tcp client mode when using the rtl_tcp utility as a spectrum server.
Please note: prior pulling a new version from git and compiling it, please do a "make uninstall" first to properly remove the previous version.
Please note: you always should build & '''install the latest version of the dependencies (librtlsdr in this case)''' before trying to build the gr source. The build system of gr-osmosdr will recognize them and enable specific source/sink components thereafter.
Building with cmake (as described in the [wiki:GrOsmoSDR gr-osmosdr wiki page]):
{{{
git clone git://git.osmocom.org/gr-osmosdr
cd gr-osmosdr/
}}}
If you are building for gnuradio 3.6 series, you have to switch to the gr3.6 branch as follows
{{{
git checkout gr3.6
}}}
then continue with
{{{
mkdir build
cd build/
cmake ../
}}}
Now cmake should print out a summary of enabled/disabled components. You may disable certain components by following guidelines shown by cmake. Make sure the device of your interest is listed here. Check your dependencies and retry otherwise.
{{{
-- ######################################################
-- # gr-osmosdr enabled components
-- ######################################################
-- * Python support
-- * Osmocom IQ Imbalance Correction
-- * sysmocom OsmoSDR
-- * FunCube Dongle
-- * IQ File Source
-- * Osmocom RTLSDR
-- * RTLSDR TCP Client
-- * Ettus USRP Devices
-- * Osmocom MiriSDR
-- * HackRF Jawbreaker
--
-- ######################################################
-- # gr-osmosdr disabled components
-- ######################################################
--
-- Building for version: 4c101ea4 / 0.0.1git
-- Using install prefix: /usr/local
}}}
Now build & install
{{{
make
sudo make install
sudo ldconfig
}}}
NOTE: The osmocom source block (osmocom/RTL-SDR Source) will appear under 'Sources' category in GRC menu.
For initial tests we recommend the multimode receiver gnuradio companion flowgraph (see "Known Apps" table below).
You may find more detailed installation instructions in this recent [http://blog.opensecurityresearch.com/2012/06/getting-started-with-gnu-radio-and-rtl.html tutorial].
==== Automated installation ====
Marcus D. Leech has kindly integrated the forementioned build steps into his gnuradio installation script at [http://www.sbrac.org/files/build-gnuradio]. This is the most user-friendly option so far.
=== Usage ===
==== rtl_sdr ====
Example: To tune to 392.0 MHz, and set the sample-rate to 1.8 MS/s, use:
{{{
./rtl_sdr /tmp/capture.bin -s 1.8e6 -f 392e6
}}}
to record samples to a file or to forward the data to a fifo.
If the device can't be opened, make sure you have the appropriate rights to access the device (install udev-rules from the repository, or run it as root).
==== rtl_tcp ====
Example:
{{{
rtl_tcp -a 10.0.0.2 [-p listen port (default: 1234)]
Found 1 device(s).
Found Elonics E4000 tuner
Using Generic RTL2832U (e.g. hama nano)
Tuned to 100000000 Hz.
listening...
Use the device argument 'rtl_tcp=10.0.0.2:1234' in OsmoSDR (gr-osmosdr) source
to receive samples in GRC and control rtl_tcp parameters (frequency, gain, ...).
}}}
use the rtl_tcp=... device argument in gr-osmosdr source to receive the samples in GRC and control the rtl settings remotely.
This application has been successfully crosscompiled for ARM and MIPS devices and is providing IQ data in a networked ADS-B setup at a rate of 2.4MSps. The gr-osmosdr source is being used together with an optimized gr-air-modes version (see Known Apps below).
It is also available as a package in OpenWRT.
A use case is described [https://sites.google.com/site/embrtlsdr/ here].
==== rtl_test ====
To check the possible tuning range (may heavily vary by some MHz depending on device and temperature), call
{{{
rtl_test -t
}}}
To check the maximum samplerate possible on your machine, type (change the rate down until no sample loss occurs):
{{{
rtl_test -s 3.2e6
}}}
A samplerate of 2.4e6 is known to work even over tcp connections (see rtl_tcp above). A sample rate of 2.88e6 may work without lost samples but this may depend on your PC/Laptop's host interface.
== Using the data ==
To convert the data to a standard cfile, following GNU Radio Block can be used:[[br]]
[[br]][[Image(rtl2832-cfile.png)]][[br]][[br]]
The GNU Radio Companion flowgraph (rtl2832-cfile.grc) is attached to this page. It is based on the FM demodulation flowgraph posted by Alistair Buxton [http://thread.gmane.org/gmane.linux.drivers.video-input-infrastructure/44461/focus=44525 on this thread].
Please note: for realtime operation you may use fifos (mkfifo) to forward the iq data from the capture utility to the GRC flowgraph.
You may use any of the the following gnuradio sources (they are equivalent):
[[br]][[br]][[Image(osmosource.png)]][[br]]
What has been successfully tested so far is the reception of [https://www.cgran.org/browser/projects/multimode/trunk Broadcast FM and air traffic AM] radio, [http://tetra.osmocom.org/ TETRA], [http://gmr.osmocom.org/ GMR], [http://svn.berlin.ccc.de/projects/airprobe/ GSM], [https://www.cgran.org/wiki/gr-air-modes ADS-B] and [https://github.com/smunaut/osmo-pocsag POCSAG].
Tell us your success story with other wireless protocols in ##rtlsdr channel on freenode IRC network.
== Known Apps ==
The following 3rd party applications and libraries are successfully using either librtlsdr directly or the corresponding gnuradio source (gr-osmosdr):
||'''Name'''||'''Type'''||'''Author'''||'''URL'''||
||gr-pocsag||GRC Flowgraph||Marcus Leech||[https://www.cgran.org/browser/projects/gr-pocsag/trunk]||
||multimode RX (try first!)||GRC Flowgraph||Marcus Leech||[https://www.cgran.org/browser/projects/multimode/trunk]||
||simple_fm_rvc||GRC Flowgraph||Marcus Leech||[https://www.cgran.org/browser/projects/simple_fm_rcv/trunk]||
||python-librtlsdr||Python Wrapper||David Basden||[https://github.com/dbasden/python-librtlsdr]||
||pyrtlsdr||Python Wrapper||Roger||[https://github.com/roger-/pyrtlsdr]||
||rtlsdr-waterfall||Python FFT GUI||Kyle Keen||[https://github.com/keenerd/rtlsdr-waterfall]||
||Wireless Temp. Sensor RX||Gnuradio App||Kevin Mehall||[https://github.com/kevinmehall/rtlsdr-433m-sensor]||
||!QtRadio||SDR GUI||Andrea Montefusco et al.||[http://napan.ca/ghpsdr3/index.php/RTL-SDR]||
||gqrx||SDR GUI||Alexandru Csete||[https://github.com/csete/gqrx]||
||rtl_fm||SDR CLI||Kyle Keen||merged in librtlsdr master||
||SDR#||SDR GUI||Youssef Touil||[http://sdrsharp.com/] and [http://rtlsdr.org/softwarewindows Windows Guide] or [http://rtlsdr.org/softwarelinux Linux Guide]||
||tetra_demod_fft||Trunking RX||osmocom team||[http://cgit.osmocom.org/cgit/osmo-tetra/tree/src/demod/python/osmosdr-tetra_demod_fft.py osmosdr-tetra_demod_fft.py] and the [http://tetra.osmocom.org/trac/wiki/osmo-tetra#Quickexample HOWTO] ||
||airprobe||GSM sniffer||osmocom team et al||[http://git.gnumonks.org/cgi-bin/gitweb.cgi?p=airprobe.git]||
||gr-smartnet (WIP)||Trunking RX||Nick Foster||[http://www.reddit.com/r/RTLSDR/comments/us3yo/rtlsdr_smartnet/][[br]][http://www.reddit.com/r/RTLSDR/comments/vbxl0/attention_grsmartnet_users_or_attempted_users/ Notes from the author]||
||gr-air-modes||ADS-B RX||Nick Foster||[https://www.cgran.org/wiki/gr-air-modes] call with --rtlsdr option||
||Linrad||SDR GUI||Leif Asbrink (SM5BSZ)||[http://www.nitehawk.com/sm5bsz/linuxdsp/hware/rtlsdr/rtlsdr.htm][[br]]DAGC changes were applied to librtlsdr master||
||gr-ais (fork)||AIS RX||Nick Foster[[br]]Antoine Sirinelli[[br]]Christian Gagneraud||[https://github.com/chgans/gr-ais]||
||GNSS-SDR ||GPS RX (Realtime!)||Centre Tecnològic de[[br]]Telecomunicacions de Catalunya||[http://www.gnss-sdr.org/documentation/gnss-sdr-operation-realtek-rtl2832u-usb-dongle-dvb-t-receiver Documentation] and [http://www.gnss-sdr.org]||
||LTE-Cell-Scanner ||LTE Scanner / Tracker||James Peroulas[[br]]Evrytania LLC||[http://www.evrytania.com/lte-tools][[br]][https://github.com/Evrytania/LTE-Cell-Scanner]||
||LTE-Cell-Scanner[[br]]OpenCL accelerated '''(new)'''||LTE Scanner / Tracker||Jiao Xianjun||https://github.com/JiaoXianjun/LTE-Cell-Scanner
||Simulink-RTL-SDR ||MATLAB/Simulink[[br]]wrapper||Michael Schwall[[br]]Sebastian Koslowski[[br]]Communication Engineering Lab (CEL)[[br]]Karlsruhe Institute of Technology (KIT)||[http://www.cel.kit.edu/simulink_rtl_sdr.php]||
||gr-scan ||Scanner||techmeology||[http://www.techmeology.co.uk/gr-scan/]||
||kalibrate-rtl||calibration tool||Joshua Lackey[[br]]Alexander Chemeris[[br]]Steve Markgraf||[https://github.com/steve-m/kalibrate-rtl], [http://rtlsdr.org/files/kalibrate-win-release.zip Windows build]||
||pocsag-mrt||Multichannel Realtime[[br]]Decoder||iZsh||[https://github.com/iZsh/pocsag-mrt]||
||adsb# ||ADS-B RX||Youssef Touil[[br]]Ian Gilmour||[http://sdrsharp.com/index.php/a-simple-and-cheap-ads-b-receiver-using-rtl-sdr]||
||osmo-gmr-rtl||GMR1 RX||Dimitri Stolnikov||[http://gmr.osmocom.org/trac/wiki/GettingStarted#RTLSDRdongles]||
||rtl_adsb||ADS-B RX||Kyle Keen||comes with the library||
||dump1090||ADS-B RX||Salvatore Sanfilippo||[https://github.com/antirez/dump1090]||
||rtl_433||Temperature Sensor[[br]]Receiver||Benjamin Larsson||[https://github.com/merbanan/rtl_433]||
||randio||Random number generator||Michel Pelletier||[https://github.com/michelp/randio]||
||gr-wmbus||m-bus (EN 13757-4) RX||oWCTejLVlFyNztcBnOoh||[https://github.com/oWCTejLVlFyNztcBnOoh/gr-wmbus]||
||ec3k||EnergyCount 3000 RX||Tomaž Šolc||[https://github.com/avian2/ec3k]||
||RTLSDR-Scanner||Radio Scanner||EarToEarOak||[https://github.com/EarToEarOak/RTLSDR-Scanner]||
||simple_ra||Radio Astronomy App||Marcus Leech||[https://cgran.org/wiki/simple_ra]||
||rtlizer||Spectrum analyzer||Alexandru Csete||[https://github.com/csete/rtlizer]||
||FS20_decode||FS20 Decoder||Thomas Frisch||[https://github.com/eT0M/rtl_sdr_FS20_decoder]||
||OpenLTE||LTE Toolkit||Ben Wojtowicz||[http://sourceforge.net/p/openlte/home/Home/]||
||rtltcpaccess||DAB compatibility layer||Steve Markgraf||[https://github.com/steve-m/rtltcpaccess]||
||SDR-J||"Analog" SDR & DAB||Jan van Katwijk||[http://www.sdr-j.tk]||
||RTLTcpSource||source for redhawk[[br]]SDR framework||Michael Ihde||[http://redhawksdr.github.io/Documentation/ redhawk Docs page] [https://github.com/Axios-Engineering/acquisition-components RTLTcpSource]||
||gortlsdr||Golang wrapper||Joseph Poirier||[https://github.com/jpoirier/gortlsdr]||
||gr-rds (fork)||RDS + WBFM receiver||Dimitrios Symeonidis et al||[https://github.com/bastibl/gr-rds]||
||NRF24-BTLE-Decoder||Decoder for 2.4 GHz NRF24 & Bluetooh LE||Omri Iluz||[https://github.com/omriiluz/NRF24-BTLE-Decoder Code] [http://blog.cyberexplorer.me/2014/01/sniffing-and-decoding-nrf24l01-and.html Blog post]
||acarsdec||ACARS decoder||Thierry Leconte||[http://sourceforge.net/projects/acarsdec/]||
[[br]]
Also take a look at the applications which use rtl-sdr [wiki:GrOsmoSDR#KnownApps through gr-osmosdr].
[[br]][[br]]
Using our lib? Tell us! Don't? Tell us why! :)
[[br]][[br]][[br]]
[[Image(rtl-sdr-gmr.png)]][[br]]
Multiple GMR-carriers can be seen in a spectrum view with the full 3.2 MHz bandwidth (at 3.2 MS/s).
== Credits ==
rtl-sdr is developed by Steve Markgraf, Dimitri Stolnikov, and Hoernchen, with contributions by Kyle Keen, Christian Vogel and Harald Welte.