Using Arduino and Python to Monitor #TheButton

Like other Reddit users, I have been keeping an eye on the “action” over at r/TheButton during the past month. I write action in quotation marks since the webpage only involves watching a clock count down from 60 seconds to 0.

To summarize the concept, on April 1st (April Fools’ Day) the admins of Reddit created a page featuring a clock counting down from 60 seconds with no indication of what would happen when it reached zero. Next to the clock was a button (The Button) which, when pressed, would reset the counter back to 60 seconds. The catch is each user account (and only those created before April 1st) can only press The Button once.

On April 1st, there were approximately 3.5 million user accounts, which could theoretically keep The Button going for 3.5 million minutes (6 years). Of course, only a fraction of those accounts are active, and as of this post, the counter has not hit 1 second without being reset. There have been several predictions on when The Button will hit zero, and even an extensive collection of statistical data on the button pushes that have happened so far.

Reddit records the time when each user pushes The Button and assigns each user a certain color of flair to display next to their username. A certain number of Reddit users, looking for bragging rights on having the lowest recorded number, are waiting for The Button to almost hit zero before they press. The only downside is this requires constant monitoring of r/TheButton to see when the counter is getting close to zero. Unfortunately, this makes being productive in other things rather difficult, so there have been several solutions to monitor The Button’s status including several users modifying LED lights controlled by Wifi or Bluetooth.

The Bluetooth light project, created by Reddit and Github user ALP_Squid uses the WebSocket client module for Python to get the current value of the countdown timer from r/TheButton. It then updates the color of a Playbulb Candle using Bluetooth. As a result, the light displays the current color of flair you would get if you pressed The Button at that moment.

I loved the idea of this project, but I didn’t have a Playbulb to use. However, I did have an Arduino and a bunch of assorted LEDs from building my Xbox 360 Halloween Costume. I made a simple circuit and Ardunio script to display the current status of The Button with one LED for each color flair.

arduino_leds

Each LED was connected through a current limiting resistor to an Arduino GPIO pin staring with 2 for purple and ending with 7 for red. The Arduino script is very simple. A byte of data containing a number (2 through 7) is sent to the Arduino over the serial port. The byte is read, converted into an integer, and the digital pin corresponding to that integer is set HIGH lighting the LED.

To handle communication with the Arduino on the PC side I use the Python library pySerial. I modified the original button script to return an integer value (2 through 7) rather than a hexadecimal color to indicate the current color of the button. The top level python file simply converts that value to a string and passes it to the Ardunio over the serial port. The result is a simple LED bar that changes colors according to the current time allowing you monitor The Button without the need to continuously stare at a screen!

All code is available on GitHub.

Decoding Your Keyless Entry Remote with Software-Defined Radio

In a previous post I talked about the process of using both MATLAB and GNU Radio to process data in real time. I recently used this process to put together a demonstration on how you could use an RTL-SDR to sense and decode the information your Keyless Entry remote sends to your car. This is a pretty popular demonstration of software-defined radio, Adam Laurie and Balint Seeber have put together similar demos.

Eventually I want to get the entire thing working with just GNU Radio but the hybrid approach is working well for now. It also shows how such a hybrid approach might be useful for other software-defined radio applications.

The Background

Keyless remote entry systems have been around for a while and likely aren’t going away any time soon. Your remote can send commands to your car wirelessly using a small radio transmitter to tell your car to unlock, lock, etc.

These remotes vary between auto manufacturers but for the most part they transmit at 315MHz and use On-Off Keying (OOK), a very simple form of digital modulation. OOK sends an RF signal of a certain length to represent a ‘1’ and stays silent to represent a ‘0’.

For security reasons the remote doesn’t send the same signal each time. The remote encrypts its commands using a rolling key so the bits representing each command are different each time. Your car and remote share the same private key which makes it so only your car can decode the encrypted transmission.

This begs the question, what happens when I press a button when I’m out of range of my car? Doesn’t that get the two rolling keys out of sync? Your car actually calculates the rolling key for the next transmission it expects as well as the next 256 transmissions (that number may vary between manufacturers). If any of the 256 match the received signal from your remote, the car will unlock and resynchronize. Of course, if you use your remote more than 256 times while out of range of your car the two will get out of sync. In that case there is usually a procedure in the owner’s manual to get them synced up again.

The Setup

To receive the signal I’ll use an RTL-SDR dongle tuned to 315MHz and running at the default sample rate of 2Msps. In GNU Radio I’ll decimate and lowpass filter the received signal. Since the modulation is OOK, I will just take the magnitude of the received signals.

Keyless Flowgraph

That data will be written into a FIFO as previously discussed. I will continue the rest of the processing in MATLAB.

Getting The Bits 

In MATLAB I will begin by opening and reading samples from the FIFO. As per the previous post, I’ll make sure that I start the flow graph running before trying to read samples from the FIFO, or MATLAB will lock up.

fi = fopen('data/keyless_mag_fifo','rb');
raw = fread(fi, buffer_len, 'float');

This will give a chunk of floating point samples of length buffer_len (in this case 50,000) containing transmissions and silence. I’ll use a simple energy detection to figure out the start of the frame.

Raw Samples

50,000 samples captured from the RTL-SDR, showing two transmissions.

eng_mat = vec2mat(raw,10);
x_mag = abs(eng_mat).^2;
x_sum = sum(x_mag,2);

b = x_sum(2:end);
a = x_sum(1:end-1);

x_diff = b./a;
x_norm = x_diff./max(x_diff);

The stream is broken up into chunks of ten samples. The energy of each chunk is calculated by taking the sum of the magnitude squared. Two vectors containing the calculated energies are created with the vector a lagging one chunk behind the vector b. If I divide b by a the resulting vector x_diff will contain peaks when the transmissions begin.

Energy Detection

Result of energy detection run on the 50,000 samples.

x_ind = find(x_norm>threshold);
if (isempty(x_ind))
    x_ind = 1;
end

start_ind = x_ind(1)*window_len;

If I then normalize the vector x_diff so that the tallest peak has a value of 1, I can set a threshold (0.2 in this case) that I’ll consider the start of the peak. If I find a peak I can calculate the sample with which to start the packet.

Detection With Threshold

Normalized energy detection with threshold. I’ll detect the two packets, but process one at a time 

I’ll then count out a number of samples after the start index (in this case 6,000) and save that as the packet. I’ll do a quick check that I have at least 6,000 samples left in the vector raw. If not, I’ll check if there are more samples available in the buffer and grab those. I’ll then remove those samples from the vector raw.

Raw Packet

The first packet in raw, containing 6,000 samples

if (start_ind+pkt_len)>length(raw)
    in_buff = fread(fi, buffer_len, 'float');
    if (isempty(in_buff))
        %display('Buffer Empty')
        continue
    end
    raw = cat(1,raw,in_buff);
end

x_pkt = raw(start_ind:start_ind+pkt_len);
raw = raw(start_ind+pkt_len+1:end);

After processing these samples I’ll return to read 6,000 more samples from raw until the vector is empty at which point I’ll grab 50,000 more samples from the buffer and store it in raw.

At this point I can take a closer look at the packet extracted from raw. Looking at the first 250 samples I can see the on-off keying more clearly.

First 250 Samples of Raw Packet

Raw packet, zoomed in on the first 250 samples

I’ll then filter the signal with an integrator to smooth out the plateaus and silences that comprise the OOK signal.

x_filt = filter(ones(1,n)/n,1,x_pkt);
Filtered Packet

Filtered packet, zoomed in on the first 250 samples

Then I’ll use a threshold to filter the further so each sample is either a one or a zero.

x_dec = x_filt;
x_dec(x_dec>0.3) = 1;
x_dec(x_dec~=1) = 0;

In this case the threshold used is 0.3. I’ll then cut the beginning of the packet so that the first sample is the start of the first plateau.

x_ind = find(x_dec);
if (isempty(x_ind))
    continue;
end

start_ind = x_ind(1);
x_dec = x_dec(start_ind:end);
Data after threshold, zoomed in on the first 250 samples

Data after threshold, zoomed in on the first 250 samples

Next I need to convert the OOK pulses into bits. For this I’ll count the duration of the plateaus and silences.

counter =0;
bit_ind = 1;
for ii=2:length(x_dec)-1
    if (x_dec(ii)~=x_dec(ii-1)) % Transition
        counter = 0;
    else
        counter=counter+1;
        if (counter>16)
            counter=0;
            bit(bit_ind) = x_dec(ii);
            bit_ind=bit_ind+1;
        end
    end
end

After a high-low or low-high transition we’ll start a counter. If the counter reaches a value (16 in this case) without another transition occurring I’ll store the bit.

The first 250 samples yield the first 12 bits of the data

The first 250 samples yield the first 12 bits of the data

The bits can then be converted to bytes using MATLAB’s bi2de function.

bit_group = vec2mat(bit,8);
byte = bi2de(bit_group)';

Decoding The Signal

The last part is to make sense of all the bytes that are being transmitted. In addition to the encryption mentioned above, the format of the packet is almost entirely different for each car manufacturer. The structure below pertains to my Saturn, but your car may be different.

I found the packet starts off with thirteen bytes of value 85 (alternating ones and zeros in binary) to synchronize the transmission. I start by finding these bytes and keeping everything after them as the payload.

known_sync = 85*ones(1,13);
if (length(byte)<14)
    continue
end
sync = byte(1:13);
payload = byte(14:end);

If the sync is found I flag the packet as good and go on to display the results. If the sync wasn’t correctly found I skip this packet and go back to the start of the loop to grab more data.

pkt_good = false;
if (isequal(sync,known_sync))
    display('Received Pkt')
    pkt_good=true;
end
if (~pkt_good)
    continue
end

Unfortunately due to the encryption this is where the decoding stops. What I have next is a sequence of approximately 20 bytes that correspond to a command transmitted to my car. However, due to the encryption I cannot tell what command is being sent. Instead I just display the sync code and the data along with a message that the signal was received. The data stays around for a few seconds and then fades.

Keyless Demo Display

Next Steps

While this project shows a good example of using both MATLAB and GNU Radio, for this particular application it would probably be best to use one or the other. I would like to eventually transition all the signal processing over to GNU Radio. My other option would be to interface directly with the RTL-SDR in MATLAB using the Communication Systems Toolbox to control the RTL-SDR. Processing the data using MATLAB’s object-oriented programming features would also improve the efficiency, but that might just have to be a project for another day.

Until then, the code for this project can be found on GitHub.

Best Images on Reddit As Your Desktop Background – Automatically

I’m on Reddit more than I would care to admit. One of my favorite parts of the website is the subreddit EarthPorn. Despite having the word “porn” in its title there is nothing obscene. It is simply a collection of high resolution photographs of some of the coolest places on Earth. I found myself occasionally setting a particularly awesome image from the website as my desktop background for a while.

Photo from EarthPorn

 Example of one of the awesome images on EarthPorn. Credit to /u/xeno_sapien.

 Even though OS X makes this pretty easy easy, I figured I could do better. What I ended up writing was a short Python script that will automatically pull down the top rated images from EarthPorn and place them in a folder. I have my Desktop settings change the desktop background to an image in that folder and switch every hour. The script runs at startup so new images are pulled down each day. When everything in place this gives me a completely new desktop background every hour!

The Script

The script itself is pretty simple, less than 100 lines. It uses urllib, a default library for Python that helps fetch data from the web.

The first thing in the script is a delay (2 minutes) to give the computer time to establish an internet connection. I don’t check if there is an active connection before proceeding, but I probably should. The next thing I do is delete the old images from the images folder so the folder will just contain the most recent images about to be pulled down.

time.sleep(120)

for the_file in os.listdir(folder):
file_path = os.path.join(folder, the_file)
try:
if os.path.isfile(file_path):
os.unlink(file_path)
except Exception, e:
print e

Note: I’m having a bit of trouble formatting the whitespace in these code snippets. Of course, this code would have to be properly spaced in order to run in Python.

Python connects to a page in Reddit’s EarthPorn that displays the top 50 images of the day. Then urllib scans the page looking for image links. Currently I only look for JPG images hosted on the image sharing website Imgur. This does leave out some images like those hosted on Flickr or formatted in PNG or the like, but it gets most of the images.

urlString = "http://www.reddit.com/r/EarthPorn/top/?sort=top&t=day"
htmlSource = urllib.urlopen(urlString).read().decode("iso-8859-1")
urlList = re.findall("http://i.imgur.com/\w+.jpg", htmlSource)

Interestingly enough, findall will return two links to each image. I think this is just the way the Reddit page is set up. When I go to grab images, I simply use every other link in urlList. Each image is saved with the date and an index starting with 0.


for index in range(0,numUrls,2):
url = urlList[index]
fileName = "img/" + time.strftime("%m") + "_" + time.strftime("%d") +           "_" + "%d.jpg" %imgName
imgName += 1

image=urllib.URLopener()
image.retrieve(imgUrl,fileName)

The Automation

There are many ways to get the script to run automatically at startup but since I am using OS X I decided to use Automator, a utility to automate workflows. I created a new workflow that simply runs the Python script. I then exported the workflow as an application. Under System Preferences -> Users & Groups -> My Account ->Login Items I added the new application. Now every time I login the workflow runs and grabs new images.

I went into my Desktop & Screensaver settings and added the folder that Python pulls the images into. I then set up the desktop background to change every hour to keep the images it displays fresh and new!

There are a lot of ways that I can improve this script. If there is no internet connection the script will just delete all your images and fail to pull new ones. Sometimes (though not usually) the images posted to EarthPorn are not of desktop quality. I would like to be able to check the resolution of the images and delete the ones that will look bad when set as my background. I could either use Python Imaging Library to do this. Alternatively, EarthPorn requires that the resolution of each image is posted so I could get more creative with the website parsing and filter the results by resolution as well.

Look for a new update on this script with a bit more functionality soon! The current version is available on GitHub.

 

 

 

 

GNU Radio: Online Processing with MATLAB

Previously I talked about using MATLAB as a tool to read and process data from GNU Radio to help debug a flow-graph offline. If we can do some signal processing in MATLAB after GNU Radio has run, would it be possible to do so while GNU Radio is running? The answer is yes, we can move our processing from GNU Radio to MATLAB at almost any part of a flow-graph.

We’ll use a special file type called a FIFO which is able to be accessed by multiple programs to read and write data. GNU Radio will push data to the FIFO and MATLAB will read that data. In this example I will use my RTL-SDR software-defined radio to receive data, lowpass filter, take the magnitude, and pass the samples to MATLAB for further processing.

RTL-SDR Flow Graph

To direct data to the FIFO in GNU Radio we use a regular file sink and enter the path to where my FIFO will be located.I’m using my Keyless Entry Decoder (more detail on this to come in another post) as an example so I’ll call the file keyless_mag_fifo.

Then we hit the Generate button in GRC, but not the Execute button. This will generate a Python file. By default it will be named top_block.py but we can change that by editing the ID field in the Options block in the flow graph. I’ll name my flow graph keyless_live.

Then we’ll create a shell script, in this example run_keyless_demo.sh. This script will create the FIFO and run the flow graph to start streaming samples to it. The script consists of just a few lines.

clear
sudo rm keyless_mag_fifo
mkfifo keyless_mag_fifo
python keyless_live.py

The script will need root privileges to create the FIFO so we will run the script with

sudo sh run_keyless_demo.sh

Now we just need to pull the data to MATLAB. I’ll use similar code to that which was discussed in previous posts. First we open the FIFO. This is done once

fi = fopen('keyless_mag_fifo','rb');

Then we will write a loop of some sort to pull a certain number of samples out of the FIFO and process them. This line sits inside a while(1) loop

raw = fread(fi,buffer_len,'float');

I’ll need to correctly handle the data type of the samples inside the buffer. In this case they are floats. My buffer length is adjustable. I’ll also check that the function filled the vector raw with the number of samples I asked for.

The most important caveat concerning this process is that the shell script must be running before the above commands are executed in MATLAB. For some reason reading from a buffer that samples aren’t being streamed to will make MATLAB lock up quite unforgivingly. Make sure that you run the shell script then the MATLAB script to ensure all the code plays nice with each other.

In a future post I’ll use this style of processing to decode an On-Off Keying modulated signal from my car’s Keyless Entry remote.

 

An Arduino-Powered Xbox 360 Costume

I recently picked up an Arduino Uno from Sparkfun with my last order. For years I’ve been using the MSP430 Launchpad as my microcontroller of choice mostly because they’re incredibly cheap and low power to boot. The Arduino and it’s user-friendly libraries make it easy to throw together a project very quickly.

That is exactly what I needed when I found myself the night before Halloween with no costume ready for the next day. Luckily I had almost all the materials I needed to build my Arduino-Powered Xbox 360 costume. With a little programming the “power button” lights up and flashes to mimic the Xbox 360 power up sequence. This project exemplifies the phrase “quick and dirty” but I think produced a good result!

The Finished Product

The Finished Product

 

The Supplies

I already had most of the components used in this build, the rest were easy to find at my local Radio Shack. Everything should also be readily available online.

Electronics

  • Green LEDs (x10)
  • 150 Ohm – 200 Ohm Resistors (x5), anywhere in that range works
  • NPN Transistors (x5) in TO-92 package such as 2N2222 or 2N3904
  • Arduino Uno
  • Protoshield for Arduino Uno, essentially just a big piece of perfboard with headers that plug into the Uno
  • SPST switch. I found this cool one at RadioShack.
  • 9V Battery Connector
  • 9V Battery
  • Assorted hook-up wire

Materials

  • Pizza Box. Dominos should give you one for free if you ask nicely.
  • Nylon Cord (what I used) or any type of thin rope.
  • Wax Paper, to diffuse the LEDs
  • White Paint
  • Plain White T-shirt

The Circuit

There are five segments to the power button. The center with the power logo and four quarter circle sections. Each is controlled separately by the Arduino. Each segment has two LEDs, though adding more LEDs is definitely a possibility.

The power supply for the circuit is a 9V battery. Each LED has a voltage drop of about 3V. I bought my LEDs in bulk on eBay, so I don’t have any exact specifications on the maximum current rating, but I would guess it’s in the neighborhood of 20mA. That means there must be a 150 Ohm current limiting resistor in line with the LEDs. I only had a few 150 Ohm resistors so I used 200 Ohm for a few of the LED segments, better to allow too little current than too much.

Furthermore the LEDs need to be switched on and off using the 5V I/O pins of the Arduino. For that an NPN transistor operating in saturation mode is used as a voltage-controlled switch. There will be five copies of this circuit, all tied into different pins of the Arduino.

LED Circuit

LED Circuit

The last part of the circuit needed is a power switch. This will be tied in series with the battery to turn the Arduino on and off. The other end of the switch is soldered to the VIN port of the Arduino which can handle a supply voltage in the range of 6V-20V.

Battery Circuit

 Switch Circuit

The Build

I started with a medium-sized pizza box for the housing.

Blank Pizza Box

I then cut out the center and four sides

Stenciled Pizza Box Cut Out Pizza Box

In order to wear the box I added a length of Nylon cord tied in a loop. I threaded this between two holes cut on the top of the box. I also threaded another length of cord through the back so I could tie the box to my waist and prevent it from flopping around. Lastly I painted the box with some white paint.

With String

The circuit was put together on an Arduino protoshield, I picked up one made by Seeed Studios but there are quite a few out there. The shield comes with pin headers that fit the Arduino Uno.

Uno with Shield

I assembled the transistors and resistors on the protoshield. The base of each transistor is connected to a pin on the Arduino through a piece of jumper wire. A resistor is connected between each emitter and a point on the board where wire leading to the LEDs will be attached.

Transistors Soldered In

Not The World’s Cleanest Layout, But It Works

I then wired in the battery snap connector and push button switch. The button turns the Arduino on/off by connecting/disconnecting power to the VIN pin. I gave the switch about two feet of wire so I could feed it out the side of the box and tuck it away in my pocket.

Board with Switch

I then needed pairs of two LEDs that could be positioned inside the box to light up each segment. I ended up cutting a few rectangles of cardboard, poking two holes through each, and taping two LEDs in place. The LEDs were connected to the board with some spare wire and heat shrink.

LED in Cardboard

I wanted each section to be lit up as smoothly as possible. The LEDs I got do a good job of lighting up the area directly in front of them but don’t allow much light out their sides. I wanted to light up each section as smoothly as possible so I took an extra step to help the light diffusion. I used some fine grain sandpaper (about 400 grit) to rough up the plastic housing around each LED. This helped quite a bit to diffuse more the light to the surrounding section

Sanded LEDs

With five LED sections made I just needed to tape them down in the correct spot in the box and connect each to the proper place on the protoshield. I programmed a quick Arudino sketch to turn on all the LEDs to make sure everything worked.

Center Lit

 

Lots of Duct Tape

Closeup Of Board Taped

 

Close Up Of The Arduino In Place

The last step of the box assembly was to tape a few sheets of wax paper on the inside of the lid of the box in order to help diffuse the LEDs and better hide the wiring and tape on the inside.

All LEDs OnSide View

 

Side View With Switch

The Software

I connected each quarter circle to a digital I/O pin on the Arduino. The center LEDs were connected to a PWM pin which allowed me to control the brightness. This was used to make a fade in and out effect for the center button.

The code runs through a set of functions to mimic the Xbox 360 startup sequence. Mostly this was just flashing various LEDs. To create the “chasing circle” effect the Arduino flashes the quarter circle sections one after the other for several revolutions around a circle.

The main loop switches between running the startup sequence, waiting with the “Xbox” on, turning everything off and waiting, fading the center LED, waiting, and running the startup sequence again. The delays make it so that your costume isn’t constantly flashing in peoples’ faces. It’s also cool when someone initially doesn’t realize the costume lights up and then it starts flashing like crazy.

The Arduino code is available on GitHub.

Finishing Touches

The last thing I needed to sell the costume was the rest of the Xbox. I used a sharpie and a blank t-shirt to draw out the rest of the front and back of the Xbox.

Tshirt Front

 

Tshirt Back

 

All that is needed is to throw on the shirt and pizza box power button and press the switch. The project looks okay in well lit rooms, but even better in the dark! Check out the completed project in action below.

 

 

 

GNU Radio: Some More Tools for Offline Processing In MATLAB

In my last post I talked about how data can be stored and read in MATLAB for analysis. The only downside is that these data files do not include any information about timing relative to other blocks. GNU Radio has a built-in functionality with stream tags to keep track of timing information. This can be useful for working with packetized data, but currently there isn’t any way to save those tags along with data to look at later. I’ve been working on a few blocks that might be able to help with this.

Bursty Data & Stream Tags

Originally GNU Radio was great for continuous streaming of samples, but lacked the ability to pass ancillary information like meta data, packet lengths, and the like that would help with decoding bursty data sent in packets. However, in recent years there has been quite a bit of work done to improve this.

One of the features that has helped extend the project’s functionality is Stream Tags. These stream tags operate as a separate data stream to pass information along to blocks downstream in the flow graph. These tags are associated with a certain sample in the data stream and that timing relation is preserved as the tags propagate through the remaining blocks. For instance, there are several blocks in GNU Radio that expect the first sample of a packet to have a tag containing the length of the packet. The block can then do its processing based on packet length.

Stream Tags are Polymorphic Types, a data type that can be used as a general container for data, be it vectors, strings, or any number of data formats such as ints and floats. Each tag has a specific format that contains several parts:

  1.      Offset:          The data stream sample that the tag is associated with
  2.      Key:              A PMT symbol that contains an identifier for the tag
  3.      Value:           A PMT representation of the data the tag is passing
  4.      Source ID:    A PMT symbol representing the block that created the tag (optional)

Saving Tags To File

In my last post I went through using file sinks to process data offline using software such as MATLAB. Currently, the file sinks don’t save tags along with that data. However, such information such as the timing and value of tags might be useful for debugging. For example, if you have a tag denoting the start of each packet you may wish to have that timing information available in MATLAB.

To do this I wrote a fairly simple block “Tag to Byte”. For a parameter it asks for the key associated with a given tag, which in this example is “packet_len”. It can be inserted anywhere into a stream, just change the IO Type parameter to match the input data type. The Tag to Byte block can be followed by a file sink.

Tag To Byte

 

Tag to Byte Block In A Flowgraph

 

The block searches the stream for a tag matching the key. When it finds one it outputs a ‘1’ for that sample only. For any samples that don’t have a tag it outputs a ‘0’. This way the timing between tags is preserved as it is written to file. The file length will be the same as a file containing the data from the same point in the flow graph and the tags will be at the correct offset. The extra timing information from the tags can be used in processing data offline.

Tag and Data

 

Plotting Data and Tags in MATLAB

 

Adding Tags From A File

There also is some utility in being able to add tags anywhere in a data stream. GNU Radio has some functionality for this already. There is a stream to tagged stream block that will add tags at evenly spaced intervals. This can be useful for data that is evenly spaced. However if the tags need to correspond to data that is unevenly spaced, such as simulated irregular bursty transmissions we need another tool to do so.

A block I’ve written called “Add Tag at Offset” takes care of this. It can be inserted anywhere in a data stream and will insert tags into the stream. As parameters it will ask for the key to be associated with the tags and the value to insert. The last parameter is the offset for the tags, and this can be a vector of any length.

Add Tag at Offset

Using Add Tag at Offset In A Flow Graph

 

Every time the block reaches a sample with the same offset as is in its offset vector it will add a tag to that sample. All samples are passed through so the block does not interrupt the data flow.

This can be useful if we wish to take a block that uses tags in a complex flow graph and examine its performance by itself. We can load data from a file and add tags anywhere in the input stream. From the block’s perspective it seems as if it is still in the overall flow graph.

Both of these blocks and a few more that are useful for working with stream tags are available on GitHub.

What’s Next

There are a few obvious improvements to make to these tools that will be coming soon. It would be nice if the Add Tag at Offset block was able to add tags of different values instead of writing the same value each time. Its current operation might be okay if you were say passing the length of packets to the next block but less useful if you were using the tag to carry information that changes from packet to packet (an estimate of the packet’s carrier frequency offset, for example). A future improvement would be to have this block read the tag values from a vector as well.

It would also be nice if Tag to Byte would pass the value of the tags along to a file sink instead of just a ‘1’ to represent the presence of a tag. A new block with the working title “Tag Extractor” is being developed that will do just that. It will take some doing to cover all stream data types and tag data types, but I’m working on it. The first version of this (only for complex streams and complex-valued tags) is also available on GitHub.

 

GNU Radio: Tools for Offline Processing With MATLAB

Some Background

The GNU Radio project is pretty awesome.

My research focusses on wireless communications. The concept of radio receiver incredibly simple: use an antenna to receive a signal through the air and process that signal to extract the useful information (voice, data, etc). A transmitter is the same idea, in reverse order. The challenging part is the signal processing turn radio waves into information you care about.

When doing work in signal processing for radio communications it is very valuable to be able to test out your ideas with real radios transmitting over the air. In the not-to-distant past this would mean fabricating a new circuit board for every new design. The concept behind software-defined radio is to replace the signal processing done by the fixed hardware with signal processing done digitally. With a software-defined radio we can change the radio just by changing code and test out many new radio designs without having to build new hardware each time.

GNU Radio provides an excellent framework for experimenting signal processing for communication. A receiver or transmitter design in GNU Radio is made up of many blocks each performing one specific function (modulation, encoding, scaling, etc). Each block, written in C++ or Python, takes in data through an input port, processes it, and outputs it to an output port. GNU Radio provides the framework to glue the inputs and outputs together to form a chain of blocks to accomplish a task. This collection of connected blocks is called a flow graph. It even comes with a Simulink-style GUI where connections are shown graphically.

An Example Flowgraph What A Flow Graph in GNU Radio Companion Looks Like

 

With a flow graph implementing the signal processing necessary for, let’s say, an FM radio receiver, you can connect a software-defined radio to your PC and process the data from raw signal to recovered audio.

GNU Radio also gives users the ability to save data at any point in the flow graph to a binary file using file sinks and file sources. The resulting files can be read after the flow graph has run and are useful tools for debugging complicated flow graphs.

Connecting A File Sink Connecting A File Sink

 

Working With File Sinks

The file sink block uses stdio to write raw samples to a file. By default, during this process a certain number of samples will be buffered before being written to file. The number of samples varies by operating system. If there is only a short amount of data going into that file sink you may find the file to be empty after the flow graph is stopped. For this case, we can use the “unbuffered” option. This bypasses the buffering operation and writes all samples directly to file.

Another thing to note is that GNU Radio companion uses absolute file paths. So be sure to change the paths if you move your flow graph to another directory or machine.

There are several ways that data can be represented in GNU Radio. These data types can be selected in the file sink block and must match the data type of the samples that are streaming to it. The data types used are:

Complex 32 bit floating point for both I and 32 Q
Float 32 bit single precision floating point
Integer 32 bit signed integer
Short 16 bit signed integer
Byte 8 bit signed integer

 

Reading Binary Files in MATLAB

Once data has been written to a file there are several ways we can examine it. A file source can be used to read back the file into another GNU Radio flow graph. We could also use Python to read and analyze the data. While it’s not free, MATLAB can be a particularly useful tool and one which most engineers are rather familiar with.

Raw data files can be read into MATLAB quite easily with a few lines of code:

f = fopen(filename, 'rb');
v = fread(f,count);
fclose(f);

The first line tells MATLAB to open the file given by filename as read-only with Big-Endian encoding. The file identifier is stored in the variable f. The last line closes the file.

The MATALB function fread does the work of pulling data out of the file and into the array v. We give it the file identifier and the number of items to read (or tell it to read the file until empty). By default, MATLAB will read the file assuming the data type is an 8-bit integer. To read different file types we will need to add an extra parameter. For example, to read floats from a file we will use

v = fread (f, count, 'float');

For the case of complex numbers the I and Q samples are interleaved. The data file will contain the I for sample 1, the Q for sample 1, the I for sample 2, etc. The read_complex_binary.m file distributed with GNU Radio shows how to take care of this

t = fread (f, [2, count], 'float');
v = t(1,:) + t(2,:)*i;
[r, c] = size (v);
v = reshape (v, c, r);

We will read the data two floats at a time. Then convert the two floats to one complex number. That will then be reshaped into one complex vector.

It is convenient to create a function that does the file read operation for each data type. Several of these files come with GNU Radio such as read_float_binary.m and read_complex_binary.m. I’ve written functions that do the same for all the other data types used in GNU Radio. They are available to download from GitHub.

Writing Binary Files From MATLAB

We can also write data from MATLAB to a file and play that file back in GNU Radio using a file source. We’ll use a similar set of commands.

f = fopen (filename, 'wb');
v = fwrite (f, data);
fclose (f);

We’ll open a file specified by filename, this time making it writable. We’ll write the vector data into that file using MATLAB’s fwrite command. The variable v will show the number of elements in data that were successfully written to file.

We will need to give fwrite the same parameters to deal with different data types as in fread. For example, to write a vector of floats to file we will use

v = fwrite (f, data, 'float');

As with the read functions, there are several MATLAB files distributed with GNU Radio to handle writing to files from MATLAB. I’ve added functions to handle other data types which are also available in the GitHub repository.