GNU Radio TensorFlow Blocks

TensorFlow is a powerful python-numpy expression compiler which supports concurrent GPP and GPU offload of large algorithms.  It has been used largely in the machine learning community, but has implications for the rapid and efficient implementation of numerous algorithms in software.   For GNU Radio, it matches up wonderfully with GNU Radio’s python blocks, which pass signal processing data around as numpy ndarrays which can be directly passed to and from TensorFlow compiled functions.   This is very very similar to what I did with gr-theano, but with the caveat that TensorFlow has native complex64 support without any additional patching!  This makes it a great candidate for dropping in highly computationally complex blocks for prototyping and leveraging highly concurrent GPUs when there is gross data parallelism that can easily be leveraged by the compiler.

A quick example of dropping TensorFlow into a python block might look something like this

class add(gr.sync_block):
 x = tensorflow.placeholder("complex64")
 y = tensorflow.placeholder("complex64")
 def __init__(self):
   gr.sync_block.__init__(self,
     name="tf_add",
     in_sig=[numpy.complex64, numpy.complex64],
     out_sig=[numpy.complex64])
   self.sess = tensorflow.Session()
   self.op = tensorflow.add( self.x, self.y)
 def work(self, input_items, output_items):
   rv = self.sess.run([self.op], feed_dict={self.x:input_items[0], self.y:input_items[1]})
   output_items[0][:] = rv[0]
   return len(rv[0])

We simply define self.op as an algorithmic expression we want to compute at run time, and TensorFlow will compile the kernel down to the GPP or GPU depending on available resources, and handle all of the data I/O behind the scenes after we simply pass ndarrays in and out of the work function.

grtfplot

Dropping this block into a new gr-tf out of tree module, we can rapidly plug it into a working GNU Radio flowgraph stream! Clearly there are algorithms which make a lot more sense to offload than “add_cc”.  Things like streaming CAF or MTI computations with lots of concurrent integration come to mind and would be pretty trivial to add.  For now this is just a proof of concept, but it seems like a great way to prototype such things in the future!

The module is available on github @ https://github.com/osh/gr-tf/

Simple Python Bayesian Network Inference with PyOpenPNL

The state of python libraries for performing bayesian graph inference is a bit frustrating.   libpgm is one of the few libraries which seems to exist, but it is quite limited in its abilities.   OpenPNL from Intel is a great c++ implementation of the Matlab Bayes-Net toolbox, but its C++ and Matlab interfaces are both not particularly convenient.   So we set about to properly swig the OpenPNL out to python where it can be used rapidly.   Additionally some of the build infrastructure for OpenPNL was a bit dated and needed some cleaning to work on modern Linux systems.

Our updated modules for both of these can be found at: https://github.com/PyOpenPNL

Not all of OpenPNL has yet been swigged and some of the python interface is still a little bit rough, but it does work.   Here we’ll work through the canonical Bayes-net example from Russell and Norvig, also used in Matlab BNT docs.  The Bayes network of interest is illustrated below.sprinkler

We have a simple graph with four discrete nodes and we would like to instantiate the model, provide evidence and infer marginal probabilities given this evidence.

We focus on the example included in the repo which can be viewed in full here simple_bnet.py

Syntax for defining a DAG’s adjacency matrix and conditional probability distribution types for the Bayes net reads as.

nnodes = 4
# set up the graph
# Dag must be square, with zero diag!
dag = np.zeros([nnodes,nnodes], dtype=np.int32)
dag[0,[1,2]] = 1
dag[2,3] = 1
dag[1,3] = 1
pGraph = openpnl.CGraph.CreateNP(dag)
# set up the node types
types = openpnl.pnlNodeTypeVector()
types.resize(nnodes)
isDiscrete = 1
types[0].SetType( isDiscrete, 2 )
types[1].SetType( isDiscrete, 2 )
types[2].SetType( isDiscrete, 2 )
types[3].SetType( isDiscrete, 2 )
# node associations
nodeAssoc = openpnl.toConstIntVector([0]*nnodes)
# make the bayes net ...
pBNet = openpnl.CBNet.Create( nnodes, types, nodeAssoc, pGraph )

We can verify the DAG structure by plotting with python-networkx, shown below and verifying it matches our goal.

figure_3

In this case we have allocated a Bayes-net with 4 nodes, each with 2 discrete states (T|F).   Next we assign CPDFs to each of the nodes.

pBNet.AllocFactors()
for (node, cpdvals) in [
 (0, [0.5,0.5]),
 (1, [0.8, 0.2, 0.2, 0.8]),
 (2, [0.5, 0.9, 0.5, 0.1]),
 (3, [1, 0.1, 0.1, 0.01, 0, 0.9, 0.9, 0.99]),
 ]:
    parents = pGraph.GetParents(node);
    print "node: ", node, " parents: ", parents
    domain = list(parents) + [node]
    cCPD = openpnl.CTabularCPD.Create( pBNet.GetModelDomain() , openpnl.toConstIntVector(domain) )
    cCPD.AllocMatrix( cpdvals, openpnl.matTable )
    cCPD.NormalizeCPD()
    pBNet.AttachFactor(cCPD)

Assigning these known distributions we now have defined the DAG and the corresponding CPDFs.   We can allocate an inference engine and begin posing problems to it.

We start by assigning evidence that we know Cloudy=False and then seek to measure the marginal of WetGrass resulting.

# Set up the inference engine
infEngine = openpnl.CPearlInfEngine.Create( pBNet );
# Problem 1 P(W|C=0)
evidence = openpnl.mkEvidence( pBNet, [0], [0] )
infEngine.EnterEvidence(evidence)
infEngine.pyMarginalNodes( [3], 0 )
infEngine.GetQueryJPD().Dump()

This provides an output value of [0.788497 0.211503] shown below when plotted.

figure_1

Changing the evidence to Cloudy=True, we can compute this marginal and plot it in comparison.

# Problem 1 P(W|C=1)
evidence = openpnl.mkEvidence( pBNet, [0], [1] )
infEngine.EnterEvidence(evidence)
infEngine.pyMarginalNodes( [3], 0 )
infEngine.GetQueryJPD().Dump()

figure_2

This is an extremely simple BN, but it illustrates the relatively straightforward simplicity with which we can now set up and work with such problems using the PyOpenPNL interface.   Hopefully this project will be of much use to a number of people!   We’ll be largely adding and testing python API support now on an as needed basis.

Installing OpenPNL and PyOpenPNL is now relatively straightforward, I’ve gone through and put together some relatively sane build systems to make these usable, they can be built roughly by following

git clone https://github.com/PyOpenPNL/OpenPNL.git
cd OpenPNL && ./configure && make && sudo make install
git clone https://github.com/PyOpenPNL/PyOpenPNL.git
cd PyOpenPNL && sudo python setup.py build install

This is of course only scratching the surface of BN/PGM style inference.  OpenPNL support DBNs, GMM based continuous distributions, and numerous CPD & Structure learning as well as inference engines under the hood, much more to come soon.

http://inferred.info

Such Samples 2

Recently Tom Rondeau did a bunch of work to add message passing support to GNU Radio’s Qt based plotters.  This is really cool because now there’s not a whole lot of need for the gr-pyqt (pyqwt based) message plotters anymore other than prototyping custom plotting things.   The obvious thing to do was update Such Samples to switch over to the more efficient, portable, stable, feature filled, and well supported plotters from the main GNU Radio distribution.

Building the Graph

Now that the Qt Gui message plotters have complex PDU message port input, we can simply hook them up to the pyqt file message source and everything works as expected!   To make wandering around recordings easier, there is now an open dialog which passes messages into the message source, and a drop down for file type would be nice to add too.  Overall the flowgraph is super simple and all message based, shown below.

ss2_graph

Graphical Interface

Running the graph, the new plotters look quite a bit cleaner and better than the old ones!  The spectrogram/waterfall plot now supports messages as well, so we include that in addition to the time/frequency plots.   Below you can see a wideband look at the 2.4 GHz ISM band which can be easily explored and intuited in each plot dimension.

ss2

This flowgraph is available on github @ such_samples2.grc

 

 

 

Building a Burst FSK Modem in GNU Radio with Message Lambda Blocks and Eventstream

Lots of cheap electronics tend to use burst FSK modems for wireless communications. GNU Radio has long been able to work with these sorts of communications, but typically it has done so by running an FSK demodulator continuously and then correlating the output for a known preamble sequence such as a with the correlate access code block, and then adding some kind of monolithic special purpose block. This article proposes a slightly different approach to building such a burst FSK waveform to inter-operate with many wireless devices of this style and to be a bit more modular, flexible, simple and intuitive to work with.

Building the Transmitter

In most communications systems, the transmitter is computationally less demanding than the receiver, additionally many FSK burst modems are low baud rate and not particularly demanding from a computational complexity standpoint. I use these two facts as motivation to justify an exceedingly lazy modem design which boils a burst FSK transmitter block down to three simple message lambda blocks as shown below.

fsk_tx.grc

Since they aren’t visible in the screenshot above, the block expression used for the three message lambda blocks are:

Map [0,1] bits to symbols [-1.0,+1.0]
 * lambda x: numpy.array(x, dtype=numpy.float32)*2-1
Interp to Samps per Sym
 * lambda x: numpy.tile(x,[sps,1]).T.reshape([1,len(x)*sps])
FSK Modulate
 * lambda x: numpy.array(numpy.exp(1j*2*numpy.pi*((dev*x*numpy.arange(len(x)))/samp_rate)),dtype="complex64")

We generate random packets of bits, prepend an arbitrary known preamble, map bits to symbols, interpolate to N samples per symbol, and finally modulate our symbols up by a complex sinusoid at plus or minus some FSK deviation frequency. At this point, the modulated bursts can simply be dropped into a transmit sample stream using an eventstream source block whose output is then throttled and run through a simple channel model.

burst_tx_plots

Plotting our FSK burst transmit waveform’s output through the pulse shaping filter, we get a reasonable looking time and frequency profile of the transmitted output signal. This is kind of a fun example to show the power of lamda blocks, in this case we’ve been able to basically write an entire waveform from a couple python expressions all from within GRC with really minimal effort, for a nominal performance penalty, which in this case doesn’t really matter.   If performance was at some point deemed to be important here, blocks could easily be ported one by one to optimized C++ based equivalents.

Building the Receiver

We can take a similar approach to building a burst FSK receiver waveform with stream blocks, message blocks, and event detection. We simply run the received samples through a standard quadrature demodulator block matched roughly to the FSK deviation magnitude. Since this FLL is essentially a random walk when no signal is on the air, and nominally tracking carrier tightly when locked to a burst, we use the variance of the FLL’s output as a detection statistic for bursts, triggering an event when the variance goes below 15 in this case. (or the negative variance rises above -15 in this case).   This can be seen in the graph below.

fsk_rx.grc

In this case at every event we latch in a maximum burst length’s worth of FM demodulated float values containing one burst every time this threshold is reached using the trigger rising edge and eventstream sink blocks. These FM demodulated samples are run through a burst FSK time sync, which performs symbol timing recovery and outputs one soft float value per symbol. Please note this synchronization block is by no means an optimal implementation, and represents only a very quick stab at the problem – but seems to perform well enough in initial test. (I would love to clean this up with more optimal ML synchronization algorithms but haven’t had a chance yet).   The output bits can then be sliced to bits, packed into 8 bit chars, and passed in an output PDU downstream to feed a PDU Socket or TUNTAP interface. A screenshot of the receive waveform is shown below.

burst_rx_plots

Our diagnostic output on the terminal shows that we are indeed recovering the inserted preamble bits correctly (0x036cf is consistently received in our output) Although sometimes with alignment slipping a bit or two in either direction and adjacent noise and data bits flipping randomly – A problem that could be easily taken care of with a MAC header search and framer.

creating event @ time 368183, length = 5000
sps = 8.000000
* MESSAGE DEBUG PRINT PDU VERBOSE *
((tau . 5) (meta . 8) (es::event_length . 5000) (es::event_time . 368183) (es::event_type . edge_event))
pdu_length = 78
contents = 
0000: 40 36 cf 02 c5 d2 b7 48 0c bd 22 44 5c d1 84 c3 
0010: 0b 2e 49 2f 29 7b 96 dd 74 61 88 82 83 47 db 0b 
0020: 2a 40 20 55 81 7d b4 29 36 0e 1d 9e 65 86 4b af 
0030: 3e b9 b1 65 b0 f9 a1 4a be f2 54 1a b2 41 bf 02 
0040: 94 a9 c3 44 3d b2 bb b6 db 6d 2b e4 b4 67 
***********************************
creating event @ time 421379, length = 5000
sps = 8.000000
* MESSAGE DEBUG PRINT PDU VERBOSE *
((tau . 3) (meta . 8) (es::event_length . 5000) (es::event_time . 421379) (es::event_type . edge_event))
pdu_length = 78
contents = 
0000: 00 36 cf 0a 59 29 cb 7b 83 67 5f ac 29 c7 87 d7 
0010: 2e 63 d4 c4 3e ff 68 d2 01 56 cc ba 09 aa 33 16 
0020: 00 7a c7 54 57 12 e3 7b 5a 72 d0 4c 80 aa 44 f1 
0030: cf 77 16 28 65 31 a4 11 f3 12 07 ef e0 42 cc 47 
0040: 57 90 be aa 15 02 89 19 91 f6 c9 83 8a dc 
***********************************

This waveform is available on github for your enjoyment.  Please send pull requests for any improvements you make!

GNU Radio Stream Lambda Blocks and Dynamic Runtime Updates

Since adding message based lambda blocks the other day, it seemed an obvious pairing to include a stream equivalent block as well for really rapid prototyping needs. The interface is a bit less simple because we can have N input ports and M output ports, I settled on defining a lambda function which takes a list of input vectors (the same input_items list of numpy arrays normal python blocks get, and an integer output port index). To implement a simplish stream block now that consumes N input streams and produces M output streams, this function prototype simply needs to be implemented. This won’t let you do everything, for instance output streams still need to produce the same number of items, and they are assumed to consume at this same rate. Extending this to a sync decimate or interpolater should be straight forward, but the function prototype would need to become a bit more complex for a “general work” kind of interface which allows producing/consuming each port at different rates, so I chose not to address that for now.

Example Stream Lambda Block  Flowgraph

A simple example graph which demonstrates the use of these blocks is shown below, this graph takes a simple Gaussian noise source in, throttles it to a fixed throughput rate, and then feeds it through a 2-in 2-out stream lambda block. In this case, we provide the following lambda function for the block,

lambda input_items, output_index: (input_items[output_index][::2]**2)*[0.1,0.2][output_index] + [-1,1][output_index]

That is to say:

output_items[0] = input_items[0][::2]**2*0.1 – 1

output_items[1] = input_items[1][::2]**2*0.2 + 1

Here, each stream is independent of the other output, and they could have been implemented as two seperate blocks, but this is just provided as an illustration.

The second block then is a 2-in 1-out stream lambda block which merges the two streams into one output stream, this mapping is given by:

lambda input_items, output_index: (input_items[0][:] * numpy.conj(input_items[1][:]))

This one is a bit simpler, as we will simply have a single evaluation:

output_items[0] = input_items[0]*conj(input_items[1])

The resulting output signal is then shown in the output plot.

stream_lambda_blocks

Dynamic Runtime Updates

What’s really fun is these lambda functions can be updated at runtime to change the block’s functionality. I’ve added a variable_text_input block to gr-pyqt which allows for runtime input of new lambda functions to each block which are passed to the GRC setter callback for each stream lambda block. By running this graph, you can now fiddle with the block’s algorithms at run time and immediately see the output effect on the stream signal. Just don’t type any invalid python at run-time or you’ll crash the block’s thread context.

The dynamic update version of the stream lambda block demo is shown below.

stream_lambda_variable_text

These dynamic function updates should work with the message lambda block as well, but that is not shown here.

The GRC graph for this example can be found @ https://github.com/osh/gr-pyqt/blob/master/apps/test_stream_lambda.grc

GNU Radio Message Lambda Blocks

It occurred randomly tonight that both python blocks and passing around lambda functions are awesome. The clear conclusion of this was that we should add python lambda blocks to GNU Radio. Since ~15 lines of python and all the installing, importing and xml wrapping is a bit lengthy for writing new python blocks, it occurred to me that in many of these blocks, the only thing that is changing is really the mapping from input vector to output vector of a PDU.

Therefore I introduce to you the new Python PDU Lambda message block. Now from GRC you can make up a completely new message block by simply writing a lambda function in a block parameter field which defines the mapping from input vector to output vector. Since pmt’s to_python and to_pmt methods handle typing for you, this works for any PMT vector type and you can generally use any python or numpy calls within your lambda argument to the block to quickly add completely new functionality from GRC with really minimal effort.

grc-plot

Testing with Such Samples

Dropping a lambda block into the such samples waveform, we make a new block which simply computes a log-power over time signal of a decimated input signal. Dropping this into a standard plotting block, we immediately have promising looking results. Any desired transform of the input data set that can be represented as a lambda function using numpy/etc can now be used to plot random segments of data from our input file now!

window

Also note that the gr-pyqt plots now support adding markers with “shift + left-click” as well as bring up a context menu (which allows you to clear markers) with “middle-click”.

This pdu_lambda block is now readily available in the gr-pyqt out-of-tree module.  The potential damage of new monolithic Balint-style GRC graphs using this block is frightening.

Such Samples: A GNU Radio Tool for Rapid Sample Data File Visualization with Message Passing

GNU Radio has always been a great stream processing system for building signal processing systems. Less noticed perhaps is that GNU Radio’s QTGui component matured, it came along with a handful of useful little tools such as gr_time_plot_c which allowed for inspection of sample data files in the time and frequency domain using the same plot widgets we typically use for streaming data. Since this makes use of a handful of GNU Radio stream blocks to perform file reading, sample dropping and alignment, and vector sources to stream data into the stream sink, and we have recently done quite a bit of work with message based plotting, I wondered if it was time to start trying to re-think these a bit. Aside from that, recently I was trying to look at some really large simulated data sets using this tool and getting frustrated with the slugish nature of the tool every time I wanted to move around in time.

So using message passing in GNU Radio I tried to re-think what a sample data analysis tool might look like, and how it might behave responsively to a use interface, accessing only the data of interest and not wasting time reading and trimming large streams using the traditional GNU Radio stream operations on the fixed data file.

Tool Composition

The tool, which I call “Such samples” is actually quite simple when built using GNU Radio Companion. It really only represents two new blocks aside from using the existing gr-pyqt based PDU message plotters, these blocks are:

1. A message based file source, which takes in a tuple message of (start item, item length) and reads out a PDU containing the requested item range after performing a low level fseek to align correctly (never reading in items outside that range).  Reading data is then conducted transparently through numpy’s from_file and pmt’s to_pmt methods which are quite fast and able to handle large chunks.

2. A message based range tool, which allows for a user to manipulate the location and sample range to view within the file. This really just sends out the (start item, item length) tuples to the message file source and doesn’t do much else.

Both of these are initially implemented as pretty concise simple python blocks, but connecting them up in GNU Radio Companion we see that it’s created a pretty simple but nicely performing tool for looking at data files.

The flowgraph is shown below, and could be easily tailored to include all kinds of message operations and plots that one might want to add or include in such a tool.

fg

Tool Operation

The tools is pretty primitive right now, but operation is simple – a command line parameter, or GNU Radio Companion variable default specified which sample data file to open, and by default the sample range [0,4096] is displayed in a time and frequency plot. Moving a slider around allows you to move the start sample throughout the file, and changing the “sample length” field allows you to change the number of complex samples plotted at a time down below. When the file is opened, it tells the range widget the start and end sample within the file so that the bar correctly spans the range of the file.

A screenshot of the tool in operation can be seen below.

plots

Still to do…

There is still lots of clean up remaining, the file source is hard wired for complx64 type samples right now, the gr-pyqt plots still have relatively meaningless labels, no nice context menus, and generally things look a little bit sloppy, but the basic architecture is in place and feels solid and responsive to me. If anyone wants to help with these other items please send pull requests on github!

I would love to switch to using the normal gr-qtgui plotters, once they support message based inputs, but for now these PyQWT based plotters aren’t too bad when passing numpy vectors around in python by reference.

The tool can be found within the gr-pyqt repo’s app’s directory on github @ https://github.com/osh/gr-pyqt/tree/master/apps

A0W2Er7

Burst PSK Modem with LDPC Coding in GNU Radio using Message Passing and Eventstream

Bursty wireless communications are widely used as a multi-user channel access sharing technique in the real world.   This has long been a frustration in GNU Radio as it has traditionally focused heavily on continuous stream processing blocks and applications.   More recently the message passing additions to GNU Radio and gr-eventstream’s burst schedulers have made building burst radio transmission and reception much simpler and more logical to implement than was possible before.   In this post we detail a demonstration of a burst QPSK modem with LDPC coding and a minimal packet header which is implemented in C++ and Python blocks, and can be put together and run easily in the GNU Radio Companion tool (GRC).

Transmit Waveform

The transmitter waveform is comprised of two processing domains which are joined by a an eventstream source block.   The first is a message passing framework which uses PDUs to pass around discrete “bursts” in various forms, and the second which is a traditional GNU Radio stream processing graph.   The eventstream source block provides the insertion of a discrete length “burst” of samples into the continuous, unbounded, stream of samples.

Transmit Waveform: Message Domain

In the message domain we start off with a “Message Strobe” block, this generates a PDU periodically ever 1000ms which triggers the creation of a random data PDU corresponding to each of these.   These random data PDUs are simply a vector of bits with random length and an empty dictionary which could hold information about the burst.

In reality an applicaiton might implement a higher layer MAC here, or simply use a TUNTAP or SOCKET block to allow real data PDUs to flow into the graph, but this is a convenient model for testing.

We pass these random bits into the framer block which adds a length field, a header checksum, and a payload checksum – which will allow us to verify correct reception and determine packet length upon receipt of the burst at the downstream receiver.

After this framer we pass the PDU through a “burst padder” block which simply adds zero bits to the end of the frame until the length reaches an integer multiple of the uncoded forward error correction (FEC) block size.   Since we must encode entire FEC blocks at a time this is a required step, when operating without FEC this could be easily removed.   At this point we go through a randomizer which XORs a random sequence onto the data to whiten the payload bits and pass it through the forward error correction encoder.

We then insert a known binary preamble sequence onto the front of each burst, and pass the burst bits through a QPSK bit to symbol mapper which converts the uint8_t bit vector into a complex float32 sample vector ready to be inserted into our transmission stream.

The image below shows the total transmit flow-graph as described above.

psk_burst_ldpc_tx.grc

Transmit Waveform: Bridging Domains

The last message block is the burst scheduler which decides when in time to schedule the burst.   It is simply a slotted aloha type of scheduler in this case which drops the burst in as soon as it can along some fixed slot boundary.   It sends bursts annotated with a sample-time to schedule them into the stream on to the eventstream source block, and receives asynchronous feedback from the same eventstream source block letting it know where in the stream it is “now”.   Out of this eventstream source block, we get a sample of complex zero samples with events copped into the correct offsets specified by their event time.

Transmit Waveform: Stream Domain

The stream domain then for this transmitter is quite simple, we go through a throttle block to limit the speed of the outgoing sample stream, go through an interpolating RRC filter to convert from 1 sample per symbol up to 2 samples per symbol for transmission, go through a standard channel model block, and finally stream the resulting continuous sample stream containing bursty transmissions out into a file sink and some QtGui plotters.

The graphical display below shows the plot of a single burst’s samples on the left side, and the mixed burst and off states with noise added in the standard stream plotters on the top and right side.   The bottom text area shows the contents of the PDU dictionary as it travels from the burst scheduler to the eventstream source, in this case the only key value pair is the event_time to schedule the burst at.

tx_waveform

Receive Waveform

The receive waveform similarly spans a message and a stream domain, bridged by using an eventstream sink block to extract discrete events from the continuous sample stream at appropriate times.

Receive Waveform: Stream Domain

The receive waveform begins with a sample stream, either from a radio or out of a stored sample file in this case.   To simulate real time operation, we throttle the data stream at the intended sample rate and then run through a matched filter for the presence of a preamble.   The output of this filter is then further filtered through a local comparison to a moving average, in the correlator filter block, and then the resulting detection metric is run into the eventstream trigger rising edge block.

This block detects whenever the detection metric rises over a certain threshold at the beginning of a burst and sends an asynchronous message to the eventstream sink block to extract a burst event beginning at that time in the sample stream.

Receive Waveform: Bridging Domains

 

The eventstream sink block, when triggered by the threshold detector, schedules a stream event which fires off the PDU handler.   This is kind of a dummy handler which simply converts the extracted samples into a standard PDU format message to be handled by any message passing blocks downstream.

Below you can see the flowgraph for the receive waveform as described.

psk_burst_ldpc_rx.grc

Receive Waveform: Message Domain

In the message domain, we start off with a chunk of samples extracted from the continuous stream containing the burst somewhere in it.   We have not done a fine synchronization and we do not yet know the length of the burst, so for now we pull out some upper bound on the length of all bursts worth of samples.    This is immediately plotted as power over time, and then run through a length detector block which attempts to trim some of the noise off the end of the burst based on its power envelope fall off / trailing edge.

At this point we have hopefully minimized the number of samples to run through our synchronization algorithm, which is of non trivial compute complexity.   We plot the constellation three places, before synchronization, after CFO correction, and after equalization and timing correction.   Since the synchronization block is operating on a whole burst atomically we are no longer restricted to using tracking loops which take time to converge at the beginning of a burst.   Instead we can produce an ML estimate for the CFO over the length of the burst, compute optimal timing and equalizer taps over the length of the burst, and then apply them atomically to the entire burst worth of samples.    The lower left hand plot below shows the correlation peak obtained during timing synchronization within this block,  with a clearly observable peak at the preamble.

Coming out of the synchronization block we have the burst’s symbols lined up in the correct rotation based on the preamble, at this point we can go through a soft demapper block, which translates all complex float symbols in the burst into a series of floating point soft bits in a PDU.   We can then use a “burst frame align” block which first strips the preamble bits off the front of the burst, and ensures that we trim all the remaining bits to a multiple of the coded FEC block size (in this case 271 bits).   We pass these soft bit vectors through an FEC decoder block to perform LDPC decoding and output hard bits, and then finally through a burst randomizer to remove the XORed whitening sequence.     The bottom middle plot shows the soft bits of a single frame before this decoding process, we can see that there is a bi-modal distribution representing clusters centered around the soft values for 0 and 1 bits for the useful portion of the frame, which is what we would hope to see.

At this point we can pass the decoded, derandomized hard bits through a deframer which provides a header CRC check, a payload length field to ensure we throw away bits past the end of the frame, and a payload CRC check which ensures none of the bits in the payload were corrupted.

Lastly we send the resulting PDU to a “meta text output” GUI widget, which allows us to look at the PDU’s dictionary values for each burst in a nice clean and easy way.    This is shown in the top right of the GUI below and contains a handful of dictionary entries which have been appended through event scheduling, synchronization, decoding, and deframing.   These include event time, center frequency offset, number of FEC iterations to decode, number of frames passed and failed, and header and payload pass rates, among other things.

rx_waveform

Future Use

The hope of this modem is largely that the message based components allow for very simple implementation of atomic burst operations, without needing to worry about book-keeping complex bursty state information within stream processing blocks.   A lot of effort has been put into trying to develop components which are NOT tightly coupled in any way, and have general applicability to many configurations with the same modem architecture.   I’m quite excited about having this available as a baseline because I think it will be a great starting point for building many projects in the future which seek to tailor various bits of the modem stack for specific situations without having to reinvent anything monolithic.   For the moment this does not represent an “adaptive” modem, but many of the components are already ready for that.   The demapper block can switch per burst based on a “modulation” dictionary entry, and a header deframer could easily schedule the extraction of an additional payload burst region back into the eventstream sink block if this were necessary, so I believe the architecture is already very well set up to handle these sorts of challenges which we are likely to throw at in the near future.

Waveform Information

This waveform both with and without LDPC can be put together using the GRC graphs in the gr-psk-burst repository which can be installed via pybombs.   This is available on github at https://github.com/osh/gr-psk-burst.   It leverages a number of tools from gr-vt as well as gr-pyqt to provide transmission, reception, and plotting.

I should also acknowledge the LDPC encoder and decoder was the work of Manu TS, originally in an out of tree module (https://github.com/manuts/gr-ldpc) developed as part of Google Summer of Code.   This work has now been integrated into GNU Radio’s gr-fec API and has been moved in-tree.   Additionally much of the underlying  work on burst syncrhonization and other burst modem blocks has been made available from Virginia Tech in the gr-vt repo, https://github.com/gr-vt, and represents the work of a handful of very talented people there.

Visualizing Radio Propagation in GNU Radio with gr-uhdgps, gr-eventstream and Google Earth

Radio propagation is a complex process in the real world, elaborate models are often used to predict expected propagation effects over known terrain, but in many cases there is no substitute for measuring ground truth.  This can now be accomplished quite easily, quickly, and cheaply using GNU Radio for a wide range of protocols.   Using gr-uhdgps (https://github.com/osh/gr-uhdgps), gr-eventstream (https://github.com/osh/gr-eventstream) and Google Earth, we demonstrate a tool to measure broadcast VHF FM Radio received signal strength over a metropolitan area. In this case we use WAMU 88.5 MHz, the local NPR radio station in Washington D.C., to demonstrate the tool and plot the results in Google Earth.

Building the GNU Radio Flowgraph

Looking at the WAMU FM Broadcast channel in a QtGui frequency and time sink plot is a good first sanity check.  Since FM broadcast is typically allocated a 200khz channel, we set up a USRP B210 to tune to 88.5 MHz with a complex sample rate of 200 ksamp/s shown below, the expected time and frequency spectrum behavior of the FM audio signal can be seen below.

      FM_WAMU_Plot   uhdgps_rssi_log.grc

In this flow graph we extract and event of 512 samples exactly every 1 second’s worth of samples from the incoming complex sample stream off the UHD source block.  Since we are throwing away the rest of the samples not extracted, this should be a low duty cycle, low CPU load process to run for the most part.   The trigger sample timer event allows us to trigger events at this sample-periodicity of a fixed length and pass them downstream to the “Handler PDU” block, this block simply converts the eventstream events into normal complex float PDUs which can be handled by any message passing block.

At this point we introduce a simple python message block called “CPDU Average Power” which computes the average sample power within the event’s samples, tags a “power” key and value to the PDU’s metadata structue and passes it downstream.    The functionality of this python block is contained within this simple python/numpy handler function which computes the power, adds the tag, and sends the output message — for now we are throwing away the PDU data field and sending PMT_NIL in its place since we don’t do anything with it downstream.

def handler(self, pdu):
    data = pmt.to_python(pmt.cdr(pdu))
    meta = pmt.car(pdu)
    data = data - numpy.mean(data) # remove DC
    mag_sq = numpy.mean(numpy.real(data*numpy.conj(data))) #compute average Mag Sq
    p = self.k + 10*numpy.log10(mag_sq)
    meta = pmt.dict_add(meta, pmt.intern("power"), pmt.from_float( p ) )
    self.message_port_pub( pmt.intern("cpdus"), pmt.cons( meta, pmt.PMT_NIL ) );

At this point we remove the “event_buffer” item from each PDU’s metadata structure using the “PDU Remove” block since it is also large and we don’t really want to keep it around downstream for any reason — trying to serialize this into our JSON storage would waste a lot of space and makes the message debug print outs massive.

Since the B210 is set up with an internal GPSDO board, we have both a GPS disciplined clock and oscillator as well as GPS NMEA fix data available from the UHD host driver.  By using the uhdgps gps probe block, we can poll the USRP source block for the NMEA fix data every time we need to store an updated signal strength record as shown in the flow graph above.  Passing our CPDUS through this GPS Probe block appends the NMEA data and a bunch of current USRP state information from the device which we can look at later.

Finally, we store a sequence of the JSON’ized PDUs to two files, one which has been filtered for records where “gps_locked” is “true” and one which simply stores all records regardless of GPS lock state.

Record Format

Each JSON’ized record corresponding to a single PDU from the flowgraph and a single eventstream extracted sample event, now looks like this in our output files.

We see that this structure now contains gps state information pulled from the GPS probe block, the stream tags which were added to the event/PDU by eventstream, and our power value computed by the python CPDU power block.

{
 "es::event_length": 512,
 "es::event_time": 20201024,
 "es::event_type": "sample_timer_event",
 "gain": 30.0,
 "gps_gpgga": "$GPGGA,003340.00,3852.6453,N,07707.3960,W,0,10,1.2,85.4,M,-34.7,M,,*6E",
 "gps_gprmc": "$GPRMC,003340.00,V,3852.6453,N,07707.3960,W,0.0,0.0,290315,,*3D",
 "gps_locked": "true",
 "gps_present": true,
 "gps_servo": "15-03-29 307 47943 -469.10 -3.21E-09 15 13 2 0x20",
 "gps_time": "1427589220",
 "power": -119.32362365722656,
 "ref_locked": "true",
 "rx_freq": [
 0,
 88499999.9999999
 ],
 "rx_rate": [
 0,
 199999.99937668347
 ],
 "rx_time": [
 0,
 [
 892243202,
 0.5858168473168757
 ]
 ]
}

Drive Testing

To test this graph I securely fasten a macbook into the passenger seat, wedge a B210 between the center console and passenger seat of the Subaru test vehicle, and plunk a GPS antenna and a poorly band matched magnetic duck antenna onto the trunk of the car and go for a drive.   After launching the application, it takes a while for the GPSDO to obtain GPS lock since it is not network assisted like many devices these days.  After a few minutes of waiting and impatiently moving the GPS antenna to the roof of the car, I obtained lock and pretty much kept it for the entirety of my drive.

seat-scaled  antenna-scaled

Inspecting Results

After driving a thorough route around town and past the broadcast tower, I dump JSON file through uhggps’s json_to_kml.py tool to convert the rss measurements into a Google Earth friendly KML file with vertical lines of height proportional to the RSS at each event location. This provides a nice intuitive visual way to look at and understand received signal strength effects over various terrain changes, obstacles, urban canyons and other such phenomena.   An overview of the route can be seen here.

plot_overview

A few notable spots around the route are shown below.

Driving through Rosslyn, VA we can see massive variation in received signal strength at each sample point likely due to massive amounts of urban multi-path fading resulting in large amounts of constructive and destructive interference.

rosslyn_variance

Driving from the George Washington Parkway North onto the US 1 memorial bridge on the far side of the river, we can see that going from a lower elevation shadowed by a small hill and a handful of trees up onto the elevated and unobstructed bridge resulted in a significant sustained climb in signal strength level.

memorial_bridge

Driving north on Connecticut Avenue, taking the tunnel underneath Dupont Circle, we briefly lose GPS lock, but upon reacquiring show a very low received signal strength down in the lowered, partially covered, and heavily shadowed roadway coming out of the tunnel.   To deal with this kind of GPS loss of lock we may need to implement some kind of host based interpolation of fixes occurring on either side of the positioning outage, but for now the samples are discarded.

dupont_tunnel

There are numerous other effects that can be observed in the KML plot from the drive which is linked below.

KML Issues

One issue that I’m still considering is how exactly to map RSSI to amplitude, there are two modes which KML supports and each has their own issue.   These plots are using “aboveGroundLevel” which maps “0” elevation to the ground elevation at a specific LAT/LON, this is good because we can just use 0 for our base height and not worry about putting a line underground somewhere, however its annoying in that the line elevation tracks with the ground contours distorting your perception of RSSI a bit.   Absolute doesnt have this problem, since 0 is (I think) locked at sea level, however in places farther from the coast this is annoying because low elevations wind up underground.  Ultimately it might be neccisary to do some kind of aboveAverageGroundLevel for a local area, but this is as far as I know not supported in Google Earth / KML.

References

The resulting KML file can be opened in Google Earth from https://github.com/osh/kml/blob/master/WAMU_RSS.locked_1427589112.17.json.kml.   Countless hours of fun can be had zooming around inspecting fades that occur passing various obstacles along the way and signal strength variation going up and down hills in various areas.

This flow graph is available at https://github.com/osh/gr-uhdgps/blob/master/examples/uhdgps_rssi_log.grc   To use it make sure you have gr-eventstream, gr-uhdgps, and relevent python modules installed.