Difference between revisions of "Gr-baz"

Revision as of 09:39, 30 March 2012

General

gr-baz is a GNU Radio project that adds new functionality (blocks, GRC definitions, apps, etc). It uses the standard GNU Radio block source tree layout and build process (i.e. ./configure, make and sudo make install).

NOTE: A few components will not work (e.g. BorIP client) without applying certain patches to your GNU Radio source. Please see below.

The module name is baz, so in Python one would write:

baz.<block>(args)

To import a file (e.g. borip):

from baz import <file>

If you make any improvements on this code, please get in touch!

Source code

You can get the master copy here with SVN, or browse with HTTP:

• http://svn.spench.net/main/gr-baz/

The code is also available on github if you prefer git (and perhaps want to fork it there):

• https://github.com/balint256/gr-baz

NOTE: You must have libusb-1.0 header+lib available! This is often easily installed using your favourite package manager. (I haven't yet had the time to fix the Automake configure script to check for it.)

Components

patch

Before using various blocks in gr-baz, you must apply at least some of the patches contained in this directory to your GNU Radio source tree. For example: you must update gr_udp_source if you wish to use it as a BorIP client.

lib (C++)

rtl_source_c

You can see a demo video of this block running from GRC here: http://youtu.be/FUQd9HOVTk8

This is a straight-forward block for receiving samples directly from a USB DVB-T stick that uses the Realtek RTL2832 demodulator, and either of the Elonics E4000 or Fitipower FC0013 tuners (I don't have a device with the FC0013, so that part of the code is untested! If you have one, get in touch.). It also supports LNA gain control (the gain range depends on the tuner), and for the E4000 optional automatic tuner mode control (enabled via auto_tuner_mode, this is activated when changing the gain and will calculate whether to use the nominal/sensitive/linear tuner mode).

A call to action: There are many more tuners out there! If you have an unsupported tuner, please consider getting the source code and implementing it. It's actually not much work: all the tuners' interface code has already been written for the Linux 3.0 DVB-T/V4L RTL2832 kernel driver. It's just a matter of moving and fixing the appropriate files, and calling a couple of functions! (I happened to get the code from https://github.com/mbarbon/rtl2832.git for 2.6 support.)

The demodulator samples at 8-bit I/Q, and the block re-processes this to output complex values (gr-complex). The sample rate can be any value up to a maximum of 3.2 MHz.

Internally the source block is multithreaded to ensure smooth buffering of samples from the device, and delivery to GNU Radio's runtime.

The source code itself is based on my USRP Interfaces plugin for Winrad/HDSDR/WRplus, which is in turn based on Osmocom's rtl-sdr. Please see the Osmocom page for more information on where to get an adapter, the original source code, etc.

The block is (hopefully completely) thread-safe, so any of the get/set functions can be called at any time from any thread. Also, if the USB device is disconnected at runtime, the block detects this and signals EOF to the runtime.

NOTE: I have modified the operation of the E4000 tuner to yield (in my opinion) better receiver performance. Specifically I have fixed it to manual gain control and also disabled the DC offset loop as on my device it was the cause of annoying interference just to the right of 0 Hz (the LO).

Also, please note I added support for the device to my original plugin yesterday, and hacked this up today by more-or-less doing a port (you can see the re-used structure of the plugin). Therefore the code doesn't look terribly beautiful, but you should still be able to navigate around if you choose to inspect/modify it.

Finally, this block requires libusb-1.0 to compile. Please have the development files installed.

GR_SWIG_BLOCK_MAGIC(baz,rtl_source_c);

baz_rtl_source_c_sptr baz_make_rtl_source_c (bool auto_tuner_mode = false);

class baz_rtl_source_c : public gr_sync_block
{
private:
  baz_rtl_source_c (bool auto_tuner_mode = false);
public:
  bool set_sample_rate(int sample_rate);
  bool set_frequency(float freq);
  bool set_gain(float gain);
public:
  int sample_rate();
  float frequency();
  float gain();
};

Example of the GRC Source block in a flowgraph

The above flowgraph running

delay

Unlike the original gr_delay block that has a fixed delay, this allows for a variable delay that can be changed at runtime. The delay can be positive or negative. If any padding is required, it uses the value of the last sample.

This block is particularly useful for investigating periodic repetitions within signals (e.g. adjusting cyclostationary lag when performing blind analysis on an OFDM signal).

GR_SWIG_BLOCK_MAGIC(baz,delay)

baz_delay_sptr baz_make_delay (size_t itemsize, int delay);

class baz_delay : public gr_sync_block
{
 private:
  baz_delay (size_t itemsize, int delay);

 public:
  int  delay() const;
  void set_delay (int delay);
};

Using the Variable Delay block to adjust the delay of samples into Complex Conjugate/Multiply blocks in order to find the cyclostationarity of the input signal (i.e. perform cyclostationary analysis to determine the periodicity of the signal to find the symbol or baud rate of the raw modulated data - helpful for blind signal anaylsis).

pow_cc

Raise incoming signal to a power (exponent), and optionally divide resulting signal by 10^div_exp to ensure it doesn't go too high and result in NaNs/Infinity in subsequent floating-point calculations.

GR_SWIG_BLOCK_MAGIC(baz,pow_cc);

baz_pow_cc_sptr
baz_make_pow_cc (float exponent, float div_exp = 0.0);

class baz_pow_cc : public gr_sync_block
{
  baz_pow_cc (float exponent, float div_exp = 0.0);
public:
  void set_exponent(float exponent);
  void set_division_exponent(float div_exp);
  float exponent() const;
  float division_exponent() const;
};

Using the Power block to determine the order of a PSK signal (i.e. determine the n of a phase-shift keyed signal, e.g. BPSK, QPSK, 8PSK).

print_char

Print bytes to the console/stdout (or optionally a file). The hexadecimal values of the bytes are printed, rather than the raw character interpretation of the value.

This block accepts a byte-stream input (containing the data to print), and an optional float-stream (a variable length signal to be used as the trigger for printing). The threshold can be set to only print bytes when the values in the float-stream exceed the specified threshold. To prevent too much data being printed, set limit to the total number of characters to be printed. This is reset each time the float-stream drops below the trigger threshold (i.e. it can be used to print the first limit demodulated bytes when the receiver becomes unsquelched, e.g. VDL Mode 2).

GR_SWIG_BLOCK_MAGIC(baz,print_char);

baz_print_char_sptr baz_make_print_char (float threshold = 0.0, int limit = -1, const char* file = NULL);

class baz_print_char : public gr_sync_block
{
private:
  baz_print_char (float threshold, int limit, const char* file);
};

puncture_bb/depuncture_ff

Puncture a stream of bytes after Forward Error Correction to reduce the code rate from that of the mother code.

Also, depuncture a stream of floats (symbols) to restore the rate of the received code to that of the mother code prior to detecting the code for errors. Missing symbol slots are marked by erasures (the value 0 is inserted into the outgoing float symbol stream).

The matrix parameter can be set at design and runtime. Here are some examples taken from autofec (see below):

_puncture_matrices = [ # Format is ('name', matrix, rate ratio)
  ('1/2', [1,1], (1, 2)),
  ('2/3', [1,1,0,1], (2, 3)),
  ('3/4', [1,1,0,1,1,0], (3, 4)),
  ('5/6', [1,1,0,1,1,0,0,1,1,0], (5, 6)),
  ('7/8', [1,1,0,1,0,1,0,1,1,0,0,1,1,0], (7, 8)),
  ('2/3*', [1,1,1,0], (2, 3)),
  ('3/4*', [1,1,1,0,0,1], (3, 4)),
  ('5/6*', [1,1,1,0,0,1,1,0,0,1], (5, 6)),
  ('7/8*', [1,1,1,0,1,0,1,0,0,1,1,0,0,1], (7, 8))

GR_SWIG_BLOCK_MAGIC(baz,puncture_bb)

baz_puncture_bb_sptr baz_make_puncture_bb (const std::vector<int>& matrix);

class baz_puncture_bb : public gr_block
{
 private:
  baz_puncture_bb (const std::vector<int>& matrix);

 public:
  void set_matrix (const std::vector<int>& matrix);
};

GR_SWIG_BLOCK_MAGIC(baz,depuncture_ff)

baz_depuncture_ff_sptr baz_make_depuncture_ff (const std::vector<int>& matrix);

class baz_depuncture_ff : public gr_block
{
 private:
  baz_depuncture_ff (const std::vector<int>& matrix);

 public:
  void set_matrix (const std::vector<int>& matrix);
};

swap_ff

Swap pairs of incoming float samples (if disabled, acts in pass-through mode).

GR_SWIG_BLOCK_MAGIC(baz,swap_ff)

baz_swap_ff_sptr baz_make_swap_ff (bool bSwap);

class baz_swap_ff : public gr_sync_block
{
 private:
  baz_swap_ff (bool bSwap);

 public:
  void set_swap (bool bSwap);
};

test_counter_cc

Used to check a simulated complex stream. The I and Q values are not a real signal; they are values that should count upward together. If values are dropped, or go out of sync, this block will report problems to stderr.

A source of such a test stream is the ExtIO_USRP plugin. To enable 'test mode', add the following DWORD to the registry:

HKEY_CURRENT_USER\<Winrad/HDSDR/WRplus/etc>\ExtIO_USRP\Settings\m_bTestMode = 1

GR_SWIG_BLOCK_MAGIC(baz,test_counter_cc);

baz_test_counter_cc_sptr baz_make_test_counter_cc ();

class baz_test_counter_cc : public gr_sync_block
{
  baz_test_counter_cc ();
};

unpacked_to_packed_bb

This is the missing combination of operations of those blocks included in the GNU Radio source tree. This one here will take bits_per_chunk from the incoming byte stream and reassemble outgoing bytes to contain bits_into_output bits from the original stream. For example: in VDL Mode 2 the D8PSK demodulator outputs an unpacked byte stream (which is really the equivalent of a bit stream). This block can be used to reassemble the individual 8PSK symbols into individual bytes (i.e. 3 bits in a byte, so output value ranges from 0 to 7).

GR_SWIG_BLOCK_MAGIC(baz,unpacked_to_packed_bb);

baz_unpacked_to_packed_bb_sptr
baz_make_unpacked_to_packed_bb (unsigned int bits_per_chunk, unsigned int bits_into_output, /*gr_endianness_t*/int endianness = GR_MSB_FIRST);

class baz_unpacked_to_packed_bb : public gr_block
{
  baz_unpacked_to_packed_bb (unsigned int bits_per_chunk, unsigned int bits_into_output, /*gr_endianness_t*/int endianness);
};

agc_cc

Experimental and unfinished.

python

borip

NOTE: You must apply the appropriate patch to enable BorIP support in gr_udp_source first!

Enables BorIP client support in GNU Radio. Either access this class directly in hand-written Python code, via the GRC block (see below), or enable seamless connection to a remote USRP exposed to your LAN with BorIP server.

BorIP has some neat features for using a USRP 1 over a network (more details in the BorIP specification):

• Data packets contain a header (optional, enabled by default) that enables the receiver to keep track of capture overruns on the server, and packets lost on the network.
• Transparent operation (see below)
• Automatically handle connection interruption without affecting the flowgraph's operation: if contact is lost with the BorIP server (e.g. network is unplugged, server power lost, etc), the UDP data stream would stop, and eventually the server would stop sending data and disconnect after the TCP control connection closes. The BorIP client can be configured to automatically reconnect to the server in the background and start streaming data again as if nothing had happened.

The UDP receiving code will process BorIP packets and output losses (bO) and incorrect payload sizes (b!) to stderr. uO is also output when the remote server experiences a capture overrun.

Operational modes

• Traditional UDP Source that handles BorIP data packets
  • NOTE: There is no TCP control channel established (unlike the proper BorIP Source block), so control commands cannot be sent to a server. This mode is suited for use with the UDP Relay option in the ExtIO_USRP+FUNcube Dongle plugin.

The original UDP Source block with added BorIP support (also features the Test Counter block)

• Proper BorIP Source that also establishes a control channel to communicate radio configuration to the server
  • This block operates more like a traditional USRP Source block in that one can configure parameters such as sample rate, frequency, gain and antenna:

To enable seamless support, add the following to gr-usrp/src/__init__.py:

import sys
if not sys.modules.has_key('baz.borip'):
    from baz import borip

This tells Python to import borip whenever the Python-bindings for the USRP are requested. BorIP automatically patches into usrp_source_c and will attempt to connect to a BorIP server if no local device is present. The default server address is specified in ~/.gnuradio/config.conf:

[borip]
server=<server address>

The other settings are:

reconnect_attempts=<# of reconnection attempts before signalling EOF to the flowgraph, -1 to try forever, default is 0>
reconnect_interval=<seconds between connection attempts, default 5 seconds>
keepalive_interval=<seconds between sending PING keepalive, default is 5 seconds>
verbose={True,False} Verbose mode prints commands sent between client and server
default_port=<TCP and UDP port to use, default is 28888>

If you use the BorIP Source GRC block, the generated code will NOT honour the reconnect_attempts specified in the above config file. Instead it will always take it from the parameter set for the GRC block instance.

auto_fec

Automatically try every combination of FEC parameters until the correct ones are found (determined by monitoring BER output by Viterbi decoder).

This uses the NASA Voyager (k=7) convolutional code.

Leave 'sample rate' parameter at 0 to have it interpret duration/periods as number of samples (this should work fine in all cases anyway). If you specify the sample rate, you can optionally engage the internal Throttle if playing back from a file.

eye

This draws upon the Data Scope originally by Max (KA1RBI) from OP25. The block allows for changing certain sampling/graphical parameters at runtime (see GRC block definition below).

Eye diagram showing 2-level signal

facsink

Please see Fast Auto-correlation.

Fast Auto-correlation block at bottom-right

grc

GRC XML block definitions for:

• rtl_source_c: RTL2832 Source
• agc: AGC (Baz) - this is unfinished
• auto_fec: Auto FEC
• borip_source: BorIP Source
• delay: Variable Delay
• puncture_bb/depuncture_ff: Puncture/Depuncture
• pow_cc: Power
• swap_ff: Swap
• test_counter_cc: Test Counter
• eye: Eye Diagram
• facsink: Fast AutoCorrelation Sink
• gr_mpsk_receiver_debug_cc: MPSK Receiver (Debug)
  • Requires appropriate patch to gr_mpsk_receiver_debug.cc

Also, this contains patches for GRC to enable 'any' block support. This enables you to use raw GNU Radio blocks by typing in the necessary Python function to create the block (without a dedicated GRC XML block definition). For example: I use it with baz.print_char

• baz_any_source: Any Block Source (for source blocks)
• baz_any_sink: Any Block Sink (for sink blocks)
• baz_any: Any Block (for blocks with I/O)

You can either apply the following two patches, OR apply one from the patch page:

• Block.py.diff
• Port.py.diff

Examples of GRC Any Blocks

apps

am_fft

The AM Scope has the same functionality as usrp_fft.py, however the AM (magnitude) signal is shown instead of the original complex one.

Also allows for changing receive antenna in the GUI.

Mode S transmission in AM

usrp_fac

Stand-alone app for using the Fast Auto-correlation Sink.

W-CDMA mobile signal (this is actually a GRC-generated GUI, but the stand-alone app look similar and can be configured with command-line arguments)