SDR (Software Defined Radio) » gr-osmosdr

{{>toc}}

h1. osmocom Gnu Radio Blocks

While primarily being developed for the [[OsmoSDR]] hardware, this block as well supports:

* "FunCube Dongle":http://tetra.osmocom.org/trac/wiki/Funcube_Dongle through libgnuradio-fcd

* "FUNcube Dongle Pro+":http://www.funcubedongle.com/?page_id=1073 through "gr-fcdproplus":https://github.com/dl1ksv/gr-fcdproplus

* "sysmocom [[OsmoSDR]]":http://sdr.osmocom.org/trac/ Devices through "libosmosdr":http://cgit.osmocom.org/osmo-sdr/

* "Nuand LLC bladeRF":http://nuand.com/ through "libbladeRF library":https://github.com/Nuand/bladeRF

* "Great Scott Gadgets [[HackRF]]":http://greatscottgadgets.com/hackrf/ through "libhackrf":https://github.com/mossmann/hackrf

* "Ettus USRP":http://www.ettus.com/product Devices through "Ettus UHD library":http://files.ettus.com/manual/page_identification.html

* "Fairwaves [[UmTRX]]":http://umtrx.org through "Fairwaves' fork of Ettus' UHD library":https://github.com/fairwaves/UHD-Fairwaves

* RFSPACE "SDR-IQ":http://www.rfspace.com/RFSPACE/SDR-IQ.html, "SDR-IP":http://www.rfspace.com/RFSPACE/SDR-IP.html, "NetSDR":http://rfspace.com/RFSPACE/NetSDR.html "(incl. X2 option)":http://www.rfspace.com/RFSPACE/NetSDR-X2.html

* RTL2832U based DVB-T dongles through "librtlsdr":http://sdr.osmocom.org/trac/wiki/rtl-sdr

* RTL-TCP spectrum server (see librtlsdr project)

* MSi2500 based DVB-T dongles through "libmirisdr":http://cgit.osmocom.org/libmirisdr/

* "SDRplay RSP":http://www.sdrplay.com through "SDRplay API library":http://www.sdrplay.com/api_drivers.html

* "AirSpy R820t":http://www.airspy.com/ dongles through "libairspy":https://github.com/airspy/host

* gnuradio .cfile input through libgnuradio-blocks

By using the [[OsmoSDR]] block you can take advantage of a common software api in your application(s) independent of the underlying radio hardware.

h2. Build process

*The Gnu Radio block requires a recent gnuradio (>= v3.7 if building master branch or 3.6.5 when building gr3.6 branch) to be installed.*

Before building the block you have to make sure that all the dependencies (see list of supported devices above) you are intend to work with are properly installed. The build system of gr-osmosdr will recognize them and enable specific source/sink components thereafter.

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:

<pre>

git clone git://git.osmocom.org/gr-osmosdr

cd gr-osmosdr/

</pre>

If you are building for gnuradio 3.6 series, you have to switch to the gr3.6 branch as follows

<pre>

git checkout gr3.6

</pre>

then continue with

<pre>

mkdir build

cd build/

cmake ../

</pre>

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.

<pre>

-- ######################################################

-- # gr-osmosdr enabled components                         

-- ######################################################

--   * Python support

--   * Osmocom IQ Imbalance Correction

--   * sysmocom [[OsmoSDR]]

--   * FUNcube Dongle

--   * FUNcube Dongle Pro+

--   * IQ File Source

--   * Osmocom RTLSDR

--   * RTLSDR TCP Client

--   * Ettus USRP Devices

--   * Osmocom [[MiriSDR]]

--   * [[HackRF]] Jawbreaker

--   * nuand bladeRF

--   * RFSPACE Receivers

-- 

-- ######################################################

-- # gr-osmosdr disabled components                        

-- ######################################################

-- 

-- Building for version: v0.1.0-4-g37aba331 / 0.1.1git

-- Using install prefix: /usr/local

</pre>

Now build & install

<pre>

make

sudo make install

sudo ldconfig

</pre>

NOTE: The osmocom source/sink blocks will appear under 'Sources' and 'Sinks' categories in GRC menu.

To build the API documentation:

<pre>

cd build/

cmake ../ -DENABLE_DOXYGEN=1

make -C docs

</pre>

h2. Automated installation

Marcus D. Leech has kindly integrated the forementioned build steps into his gnuradio installation script at "This is the most user-friendly option so far.

h2. Device specification

You can specify the source or sink device using a comma separated string of argument=value pairs. The always-up-to-date block documentation with examples is available [http://cgit.osmocom.org/gr-osmosdr/tree/grc/gen_osmosdr_blocks.py#n100 right here":http://www.sbrac.org/files/build-gnuradio]..

h3. FCD Source

||Argument||Notes||

||fcd=<device-index>|| 0-based device identifier, optional||

||device=hw:2|| overrides the audio device||

||type=2|| selects the dongle type, 1 for Classic, 2 for Pro+||

The "device" argument overrides the audio device used by the underlying driver to access the dongle's IQ sample stream.

The "type" argument selects the dongle type, 1 for Classic, 2 for Pro+.

h3. IQ File Source

||Argument||Notes||

||file=<path-to-file-name>||||

||freq=<frequency>|| Center frequency in Hz, accepts scientific notation||

||rate=<sampling-rate>|| Mandatory, in samples/s, accepts scientific notation||

||repeat=true|false|| Default is true||

||throttle=true|false|| Throttle flow of samples, default is true||

h3. [[OsmoSDR]] Source

||Argument||Notes||

||osmosdr=<device-index>|| 0-based device identifier||

||buffers=<number-of-buffers>|| Default is 32||

||buflen=<length-of-buffer>|| Default is 256kB, must be multiple of 512||

h3. RTL-SDR Source

||Argument||Notes||

||rtl=<device-index>|| 0-based device identifier OR serial number||

||rtl_xtal=<frequency>|| Frequency (Hz) used for the RTL chip, accepts scientific notation||

||tuner_xtal=<frequency>|| Frequency (Hz) used for the tuner chip, accepts scientific notation||

||buffers=<number-of-buffers>|| Default is 32||

||buflen=<length-of-buffer>|| Default is 256kB, must be multiple of 512||

||direct_samp=0|1|2|| Enable direct sampling mode on the RTL chip. 0: Disable, 1: use I channel, 2: use Q channel||

||offset_tune=0|1|| Enable offset tune mode for E4000 tuners||

NOTE: use rtl_eeprom -s to program your own serial number to the device

NOTE: if you don't specify rtl_xtal/tuner_xtal, the underlying driver will use 28.0MHz

h3. RTL-SDR TCP Source

||Argument||Notes||

||rtl_tcp=<hostname>:<port>|| hostname defaults to "localhost", port to "1234"||

||psize=<payload-size>|| Default is 16384 bytes||

||direct_samp=0|1|2|| Enable direct sampling mode on the RTL chip 0=Off, 1=I-ADC input enabled, 2=Q-ADC input enabled||

||offset_tune=0|1|| Enable offset tune mode for E4000 tuners||

h3. Miri Source

||Argument||Notes||

||miri=<device-index>|| 0-based device identifier||

||buffers=<number-of-buffers>|| Default is 32||

h3. SDRplay Source

The sdrplay source uses a precompiled (closed source) library available from http://www.sdrplay.com/api_drivers.html to interface with the hardware. To enable this nonfree driver you have to call cmake with the additional parameter -DENABLE_NONFREE=TRUE

||sdrplay|| Use this argument without a value||

h3. UHD Source / Sink

||Argument||Notes||

||uhd|| Use this argument without a value||

||nchan=<channel-count>|| For multichannel USRP configurations use the subdev parameter to specify stream mapping||

||subdev=<subdev-spec>|| Examples: "A:0", "B:0", "A:0 B:0" when nchan=2. Refer original ettus documentation on this||

||lo_offset=<frequency>|| Offset frequency in Hz, must be within daughterboard bandwidth. Accepts scientific notation||

Additional argument/value pairs will be passed to the underlying driver, for more information see

"specifying the subdevice":http://files.ettus.com/uhd_docs/manual/html/general.html#specifying-the-subdevice-to-use and 

"common device identifiers":http://files.ettus.com/uhd_docs/manual/html/identification.html#common-device-identifiers in the Ettus documentation.

h3. bladeRF Source / Sink

Arguments that affect both the source & sink (i.e., the underlying device), when applied to either are marked *bold*.

||Argument||Notes||

||bladerf[=instance|serial]||Selects the specified bladeRF device by a 0-indexed "device instance" count or by the device's serial number. 3 or more characters from the serial number are required. If 'instance' or 'serial' are not specified, the first available device is used. ||

||*fpga*=<'/path/to/the/bitstream.rbf'>||Load the FPGA bitstream from the specified file. This is required only once after powering the bladeRF on. If the FPGA is already loaded, this argument is ignored, unless 'fpga-reload=1' is specified.||

||*fpga-reload*=1||Force the FPGA to be reloaded. Requires fpga=<bitrstream> to be provided to have any effect.||

||buffers=<count>||Number of sample buffers to use. Increasing this value may alleviate transient timeouts, with the trade-off of added latency. This must be greater than the 'transfers' parameter. Default=32||

||buflen=<count>||Length of a sample buffer, in *samples* (not bytes). This must be a multiple of 1024. Default=4096||

||transfers=<count>||Number of in-flight sample buffer transfers. Defaults to one half of the 'buffers' count.||

||stream_timeout_ms=<timeout>||Specifies the timeout for the underlying sample stream. Default=3000.||

||*loopback*=<mode>||Configure the device for the specified loopback mode (disabled, baseband, or RF). See the libbladeRF documentation for descriptions of these available options: none, bb_txlpf_rxvga2, bb_txlpf_rxlpf, bb_txvga1_rxvga2, bb_txvga1_rxlpf, rf_lna1, rf_lna2, rf_lna3. The default mode is 'none'.

||*verbosity*=<level>||Controls the verbosity of output written to stderr from libbladeRF. The available options, from least to most verbose are: silent, critical, error, warning, info, debug, verbose. The default level is determined by libbladeRF.||

||*xb200*[=filter]||Automatic filter selection will be enabled if no value is given to the xb200 parameter. Otherwise, a specific filter may be selected per the list presented below.||

<pre>

The following values are valid for the xb200 parameter:

"custom"  : custom band

"50M"     :  50MHz band

"144M"    : 144MHz band

"222M"    : 222MHz band

"auto3db" : Select fiterbank based on -3dB filter points

"auto"    : Select filerbank based on -1dB filter points (default)

gr-osmosdr <-> bladeRF gain mappings

Sink:

BB Gain: TX VGA1 [-35, -4]

IF Gain: N/A

RF Gain: TX VGA2 [0, 25]

Source:

RF Gain: LNA Gain {0, 3, 6}

IF Gain: N/A

BB Gain: : RX VGA1 + RX VGA2 [5, 60]

</pre>

h3. [[HackRF]] Source / Sink

||Argument||Notes||

||hackrf=<device-index>|| 0-based device identifier OR serial number||

||bias=0|1|| Disable or enable antenna bias voltage in receive mode (source)||

||bias_tx=0|1|| Disable or enable antenna bias voltage in transmit mode (sink)||

||buffers=<number-of-buffers>|| Default is 32||

You can specify either hackrf=0 and hackrf=1 to select by a device index, or the serial number (or an unique suffix of a serial number), hackrf=f00d and hackrf=1234abba. hackrf_info lists multiple devices and their serial numbers. Device selection by serial number tail ("hackrf=beeff00d") requires updated hackrf firmware. The firmware changes have been in the hackrf git master, but there's no official firmware binary published yet (02.06.2015).

Beware of a little catch, there are some examples floating on the net with "hackrf=1" as the device argument. Device index numbers are 0-based (like with rtlsdr and other drivers), so you'll have to use hackrf=0 if you only have a single device attached, hackrf=1 would be the second device. Before this patch the hackrf gr-osmosdr driver did not care about the parameter at all.

Transmit support has been verified by using the "crc-mmbTools DAB sdr transmitter":http://sdr.osmocom.org/trac/attachment/wiki/GrOsmoSDR/hackrf-dab.jpg.

h3. RFSPACE Source

||Argument||Notes||

||sdr-iq[=<serial-port>]|| Optional parameter, serial-port defaults to the serial port (like /dev/ttyUSB0) used by first detected SDR-IQ||

||sdr-ip[=<hostname>][:<port>]|| Optional parameters, hostname defaults to "localhost", port to "50000" or the first detected SDR-IP||

||netsdr[=<hostname>][:<port>]|| Optional parameters, hostname defaults to "localhost", port to "50000" or the first detected [[NetSDR]]||

||nchan=<channel-count>|| Optional parameter for [[NetSDR]], must be 1 or 2||

The SDR-IP/NetSDR discovery protocol (UDP broadcast) is implemented, thus specifying the ip & port should not be neccessary. Note: for the receiver to operate properly it is required that the UDP packets (port 50000) carrying the sample data can reach your PC, therefore configure your firewall/router/etc. accordingly...

The ftdi_sio driver is being used for SDR-IQ. It creates a character device of the form:

crw-rw---- 1 root dialout 188, 0 Dec 19 22:14 /dev/ttyUSB0

To be able to open the device without root permissions add yourself to the "dialout" group or do a "chmod 666 /dev/ttyUSB0" after pluggin in.

h3. [[AirSpy]] Source

||airspy|| Use this argument without a value||

||bias=1|0|| Enable or disable DC bias at the antenna input||

h2. Included Apps

h3. Spectrum Browser

{{thumbnail(fft-lte.png)}}

RTSA-like spectrum visualization is available through "fosphor":https://sdr.osmocom.org/trac/wiki/fosphor component. Call osmocom_fft with -F switch to enable it (a graphics card supporting [[OpenCL]]/OpenGL interop is a requirement).

{{thumbnail(fosphor.png)}}

{{thumbnail(fosphor2.png)}}

usage examples:

<pre>

osmocom_fft -a rtl=0 -v -f 100e6 -s 2.4e6 -g 15

osmocom_fft -a rfspace -v

osmocom_fft -a bladerf -v

osmocom_fft -a hackrf -v

osmocom_fft -a uhd -v

osmocom_fft -a airspy -v

</pre>

DC offset and IQ imbalance correction controls may be enabled using --dc-offset-mode=0 and --iq-balance-mode=0 command line switches respectively.

h3. Signal generator

{{thumbnail(siggen-gsm.png)}}  {{thumbnail(gsm-hackrf-8M.png, size=500)}}

usage examples:

<pre>

osmocom_siggen -a hackrf -f 100e6 --sine

osmocom_siggen -a hackrf -f 100e6 --sweep -x 2M -y 1 -c34

osmocom_siggen_nogui -a hackrf -f 100e6 --sweep -x 2e6 -y 10 -v

osmocom_siggen_nogui -a uhd,subdev=A:0 -f 100e6 --sweep -x 2e6 -y 10 -s 4e6 -v

osmocom_siggen -a bladerf -f 1G --sweep -x 4M -y 1 -s 4M

</pre>

h3. Spectrum sensing

TODO: document

h2. Known Apps

The following 3rd party applications are successfully using gr-osmosdr:

||*Name*||*Type*||*Author*||*URL*||

||gr-pocsag||GRC Flowgraph||Marcus Leech||"||multimode RX||GRC Flowgraph||Marcus Leech||[https://www.cgran.org/browser/projects/multimode/trunk":https://www.cgran.org/browser/projects/gr-pocsag/trunk]||||

||simple_fm_rvc||GRC Flowgraph||Marcus Leech||"||Wireless Temp. Sensor RX||Gnuradio App||Kevin Mehall||[https://github.com/kevinmehall/rtlsdr-433m-sensor":https://www.cgran.org/browser/projects/simple_fm_rcv/trunk]||||

||gqrx||SDR GUI||Alexandru Csete||"||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":https://github.com/csete/gqrx]|| and the "HOWTO":http://tetra.osmocom.org/trac/wiki/osmo-tetra#Quickexample ||

||airprobe||GSM sniffer||osmocom team et al||"||gr-smartnet (WIP)||Trunking RX||Nick Foster||[http://www.reddit.com/r/RTLSDR/comments/us3yo/rtlsdr_smartnet/":http://git.gnumonks.org/cgi-bin/gitweb.cgi?p=airprobe.git]||[[br]]"Notes from the author":http://www.reddit.com/r/RTLSDR/comments/vbxl0/attention_grsmartnet_users_or_attempted_users/||

||gr-air-modes||ADS-B RX||Nick Foster||"call with --rtlsdr option||

||gr-ais (fork)||AIS RX||Nick Foster[[br":https://www.cgran.org/wiki/gr-air-modes]]Antoine Sirinelli[[br]]Christian Gagneraud||"||GNSS-SDR ||GPS RX (Realtime!)||Centre Tecnològic de[[br":https://github.com/chgans/gr-ais]||]Telecomunicacions de Catalunya||"Documentation":http://www.gnss-sdr.org/documentation/gnss-sdr-operation-realtek-rtl2832u-usb-dongle-dvb-t-receiver and "||gr-scan ||Scanner||techmeology||[http://www.techmeology.co.uk/gr-scan/":http://www.gnss-sdr.org]||||

||pocsag-mrt||Multichannel Realtime[[br]]Decoder||iZsh||"||osmo-gmr-rtl||GMR1 RX||Dimitri Stolnikov||[http://gmr.osmocom.org/trac/wiki/GettingStarted#RTLSDRdongles":https://github.com/iZsh/pocsag-mrt]||||

||simple_ra||Radio Astronomy App||Marcus Leech||"||FS20_decode||FS20 Decoder||Thomas Frisch||[https://github.com/eT0M/rtl_sdr_FS20_decoder":https://cgran.org/wiki/simple_ra]||||

||OpenLTE *(NEW)*||LTE Toolkit||Ben Wojtowicz||"||sdrangelove *(NEW)*||SDR GUI||Christian Daniel||[http://sdrangelove.org":http://sourceforge.net/p/openlte/home/Home/]||||

||gr-dvbt *(NEW)*||DVB-T Transmitter & Receiver||Bogdan Diaconescu||"[http://yo3iiu.ro/blog/?p=1191 Blog Post":https://github.com/BogdanDIA/gr-dvbt] "bladeRF transmit flowgraph":http://nuand.com/forums/viewtopic.php?f=8&t=3499#p5124||

h2. Credits

gr-osmosdr is developed by Dimitri Stolnikov with contributions from Hoernchen, Steve Markgraf, Sylvain Munaut and Nuand LLC folks.