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!

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.

Burst Transmission in GNU Radio Sample Streams with Eventstream

There are a handful of ways to transmit bursts of information using GNU Radio.   Perhaps most widely known is when using Ettus UHD based devices, burst transmit mode may be used to schedule bursts of samples within a properly tagged stream.   This results in accurately timed bursts and low latency transmission, but it also relies upon specific Ettus hardware and makes software only loopback simulation impossible.

This alternative method of burst transmission using the eventstream (http://github.com/osh/gr-eventstream) source block to interleave bursts into a sample stream is hardware independent, and allows precise timing of bursts in the sample stream in a hardware independent way which works well in loopback software simulation.   The performance cost is a slightly higher latency penalty than the UHD burst mode due to reliance on back-pressure within the GNU Radio transmit stream.  But it does have the nice side effect of resolving the ugly “flushing the end of a burst” nastiness which may be present when sending the end of a tagged stream burst through GR blocks and/or transfer to a UHD device.

Signal Source

Our burst signal source in this case is the random pdu generator block.   The message strobe block sends it a message every 500ms telling it to generate a new burst of between 50 and 2000 bits in length.   We ensure that each byte contains a single bit by anding a mask of 0x01 in this generator block.   Finally we go through a PDU PSK burst mapper block to map the random bits into a complex constellation points in our new complex float PDU.

These bursts are plotted using the gr-pyqt burst plotters for reference before continuing down the chain.   They are burst only and and no “off” time exists at this point in the graph.

Eventstream Source / Burst Scheduling

The eventstream source block, void of any events, simply produces zero valued samples at a rate limited by downstream back-pressure.   A variety of transmit handlers may be used to produce output into this sample stream at precise times and lengths.   One convenience handler which is provided is the PDU Handler, which is internal to the eventstream source block, and allows you to simply pass a PDU of samples into the block to be sequenced into the output stream without worrying about the more complex trigger/handler paradigm.

Once we pass a complex float PDU into the schedule_event port, the block checks for an “event_time” tag on the event to tell it what precies sample index time to schedule the burst at.   When this value is not provided, a time of 0 is assumed, which is the case in this example.   The source block defines and “Early Behavior” which defines what should happen if an event arrives with a time which is too early for the current stream nitems_written(0) value (number of samples which have been produced).   The options here are to DISCARD, throw away events which are too early, BALK, or throw an exeption and stop running when such event arrive (useful for debugging), or ASAP, to simply schedule them at the earliest possible time available.   In this case we use ASAP to schedule the events as soon as possible.

flowgraph_es_tx

Plotting

Coming out of the eventstream source block, we throttle the stream to limit production rate to our desired sample rate, add some gaussian noise to make plots more interesting, and then plot the power of the resulting sample stream with roughly time periodic bursts in it.   We can see that plotting a burst tirggered roughly every 500ms does result in a burst being scheduled into the stream roughly every 500ms.   If we wanted this to be exactly 500ms in samples, we could set the “event_time” tag on the event to the proper sample index desired, but this exercise will be left to a future example.

plots

Simple GNU Radio Eventstream Based Burst Extraction and Plotting

Both gr-eventstream and gr-pyqt have been around and available now for a while on my github page, but not enough good documentation material exists for either.   This article aims to address that and show a simple example of how they can both be used to plot synchronous windowed burst events occurring within a standard sample stream.   In order to run this example you will need to install both gr-eventstream (https://github.com/osh/gr-eventstream) and gr-pyqt (https://github.com/osh/gr-pyqt) for plotting.

Signal Source

The signal source for this example is a simple complex sinusoid with amplitude 1 added to complex Gaussian noise with mean amplitude 0.01.   This gives us a nice well understood signal to play with, but adds a bit of noise so plots aren’t identical each burst or sine period.

Detecting Bursts

Using eventstream, finite time-windowed events or bursts are scheduled by blocks known as “trigger” blocks.   There are many ways to do this such as a matched filter correlators, cyclostationary detectors, or otherwise; in this example we will use a generic “Rising edge trigger” block which simply picks up on a float stream rising over a constant threshold value.   Instead of implementing a new custom trigger block for you application, you may be able to use stream operators to produce a detector of interest and then simply pass the derived metric into the trigger block to perform detection.   In the case of this example, we use the real component of the complex sinusoid as our detection metric since it should be quite intuitive as to what is going on here to most readers.   This trigger block allows you to specify a threshold value, an event length (the number of samples contained in each event), a “lookback” length (how many samples before the actual rising edge should the event start), and a minimum trigger distance (a debouncing parameter to allow you to disallow subsequent events for N samples, incase of a noisy rising edge).   These can be seen in the flowgraph image below; upon meeting the threshold criteria, an event description is sent to the eventstream sink block.

Extracting Events

The Eventstream Sink block performs a seemingly simple, but tedious function.   It takes in “event” descriptions (event type, event time, event length) extracts the samples from a stream corresponding with the event time and length specified, and then sends the populated event to all “handlers” downstream which are associated with this type of event to operate.

Handling Bursts

Eventstream burst handlers are blocks which implement a special c++ GR Block interface which implements a handler( pmt_t msg, gr_vector_void_star buf ) method.  Since you probably don’t want to write a custom c++ handler function/class, the easiest thing to do in many applications is to use a “Handler to PDU” block.   This block takes the incoming event parameters and sample buffer from the event and converts it to a standard GNU Radio PDU formatted PMT asynchronous message to send downstream.  Standard GNU Radio asynchronous message blocks which operate on PDUs may then be used to operate on it.  That is the method we will use in this example.

Handling PDUS

Now that we have a standard PDU with complex floats contained in its data vector, we can send it downstream to two message blocks using fan-out of standard GNU Radio message ports.  The first connection is to a simple message debug block, this simply prints the message contents to the console for the user’s viewing pleasure.   The second is to a gr-pyqwt complex time plot, which plots the event as a single atomic plot every time a new message comes in.   These plotters were implemented to allow plotting of an entire event at once regardless of its sample length, as opposed to the existing gr-qtgui plots which are as of this writing, intended for stream plotting and by default plot 1024 samples every time, not variable as these are to the event buffer’s length.  This can be very useful for diagnosing the behavior of various burst waveforms.

Connecting Everything Up

Connecting everything up, we connect our raw sample stream input into the pass-through port on the trigger rising edge block, and we connect our detection metric (the complex to real float stream output) into the thresh_input port.

We then connect our trigger block’s passthrough_out port to the es.sink input block (We keep the sink downstream simply to ensure that the sink does not consume anything that the trigger has not yet, otherwise there would be no need to go through the trigger block), and the trigger’s “which stream” message port to the sink’s “schedule_event” port, this tells the trigger where to schedule the burst extraction when a trigger has been fired.

Finally, we connect the “edge_event” port on the trigger to the “handle_event” port on the “handler”.   This is perhaps the most confusing connection, it specifies that events of the type “rising edge” shall be handled by the “to pdu” handler, however it is a logical connection and does not represent the actual data path at runtime!  At runtime, the event goes to the eventstream sink, is populated with samples, and then passed to the handler to be converted to a PDU.   However, this direct connection is used to provide a more intuitive GRC connection line to show logically which events go to which handlers.   In reality when start() is called in the flowgraph, trigger blocks indicate their connections downstream to their corresponding es.sink blocks which which event types correspond to which handlers so that they then known at runtime which handler blocks to forward populated events to.

The final completed flowgraph can be seen below.

flowgraph

Plotting the results

When we run this flowgraph, we now expect to trigger every time the signal’s real component rises past a value of zero.   Since we have a bunch of added noise, we will actually also see a noisy “rise” past zero when we pass zero both on the way up and down, as you will see when you run the flowgraph.   You will see on the X axis below that each event is 1000 samples in length, which was specified in our trigger block’s “event length”.  In this case it is a constant size, but a trigger can specify a different event length for each burst if desired.  By playing with the lookback value to 500, you could center the zero crossing in the event if desired here.  Lastly since we have a debounce window of 300 samples. we only get one event per crossing even though the noise on top of the signal causes several local crossings in the area for each of these in reality.

Our event shown below, shows the real (green) and imaginary (red) portions of our complex sinusoid with the exact sample of the trigger occurrence being the first (leftmost) sample in the plot.

burst_plot

Example Source

The GRC source file for this example can be downloaded at: https://github.com/osh/gr-eventstream/blob/master/examples/demo_01_burst_rx.grc