Python Block Tags

TODO:
 * make a picture associating tags with samples
 * describe how tag indexing works (both read, write)

This tutorial demonstrates how to create two Embedded Python Blocks for detecting when the input signal crosses the threshold and writing a tag for it and then reading the tag in a separate block and updating the output with the time since the last detection.

The previous tutorial, Python Block Message Passing demonstrates how to send and receive messages using the Embedded Python Block. The next tutorial, Low Pass Filter Example, demonstrates how to use filtering blocks in GNU Radio.

Tags Overview
Tags are a way to convey information alongside digitized RF samples in a time-synchronous fashion. Tags are particularly useful when downstream blocks need to know upon which sample the receiver was tuned to a new frequency, or for including timestamps with specific samples.

Where messages convey information in an asynchronous fashion with no clock-based time guarantee, tags are information which are associated with specific RF samples. Tags ride alongside digitized RF samples in data streams and vectors, including Complex Float 32, Float 32, Byte and all of the other formats.

Tags are added using the line: self.add_item_tag(outputPortNumber, absoluteIndex, key, value)

The outputPortNumber determines which output stream the tag will be added to. The absoluteIndex is the sample index the tag will be added to. The flowgraph counts each sample and the first sample produced is at absolute sample index 0. The key is a PMT type containing the name of the variable to be stored and value is another PMT type that contains the information to be stored.



Reading tags can be done with the function: tagTuple = self.get_tags_in_window(inputPortNumber, relativeIndexStart, relativeIndexStop))



More information about tags can be found here: Stream Tags

Creating Test Signal
A test signal is needed. Begin by dragging in the blocks for the input signal:
 * GLFSR Source
 * Repeat
 * Multiply Const
 * Add Const
 * Single Pole IIR Filter
 * Throttle
 * QT GUI Time Sink

Change the following parameters:
 * GLFSR Source, Degree: 32
 * Repeat, Interpolation: 128
 * Multiply Const, Constant: 0.5
 * Add Const, Constant: 0.5
 * Single Pole IIR Filter, Alpha: 0.05
 * QT GUI Time Sink
 * Number of Points: 2048
 * Autoscale: Yes
 * samp_rate Variable, Value: 3200

Change all of the blocks to be Float input and output. Connect them all according to the following flowgraph:



Run the flowgraph. A pseudo-randomized sequence of filtered 0s and 1s is generated:



Threshold Detector: Defining the Block
Drag in a Python Block and double-click it to edit the source code. Recall that Embedded Python Blocks use indentation in multiples of 4 spaces.

Change the example_param variable name and add a new parameter report_period:

def __init__(self, threshold=1.0, report_period=128):

Update the block name:

name='Threshold Detector',

Change the input and output types to Float:

in_sig=[np.float32], out_sig=[np.float32]

Change the variable name from self.example_param:

self.threshold = threshold self.report_period = report_period

Remove the multiplication by self.example_param:

output_items[0][:] = input_items[0]

The code should now look like the following:



Save the code (CTRL + S) and return to GRC. The block will now look like the following:



If the block did not update properly there may be a problem with the Python syntax. Double-click the Embedded Python Block to view any potential syntax errors. The following image gives an example of where the synax errors are located:



Add a Virtual Sink and Virtual Source block to the flowgraph. Change the following block properties:
 * Threshold Detector
 * Threshold: 0.75
 * Report Period: 128
 * Virtual Sink, Stream ID: signal
 * Virtual Source, Stream ID: signal
 * QT GUI Time Sink, name: "Threshold Detector"

Connect the blocks according to the flowgraph:



Threshold Detector: Writing Tags
The internals of the Threshold Detector now need to be written. Recall that Embedded Python Blocks use indentation in multiples of 4 spaces.

Import the pmt library:

import pmt

Add two new variables, self.timer and self.readyForTag under the __init__ function:

self.timer = 0 self.readyForTag = True



The work function needs to be modified. Create a for loop to iterate through all of the input samples:

for index in range(len(input_items[0])):

Three sections of code need to be written. The first block writes the amplitude level into a tag named detect once the threshold is met or exceeded. The tag will only be written if the self.readyForTag state variable is True. Once a tag is written the state variable self.readyForTag is set to False.

if (input_items[0][index] >= self.threshold and self.readyForTag == True): # define the key as 'detect' key = pmt.intern('detect') # get the detection value value = pmt.from_float(np.round(float(input_items[0][index]),2)) # tag index to be written writeIndex = self.nitems_written(0) + index # add the tag object (key, value pair) self.add_item_tag(0, writeIndex, key, value ) # tag has been written, set state self.readyForTag = False
 * 1) write the tag

The next block of code is used to run the timer. The timer increases by 1 for each input sample as long as self.readyForTag is False:

if (self.readyForTag == False): self.timer = self.timer + 1
 * 1) increase  the timer by 1

The third block of code controls the state variable self.readyForTag. Once self.timer reaches the maximum value the timer is reset and the state variable self.readyForTag is set to True:

if (self.timer >= self.report_period): # reset timer self.timer = 0 # reset state once timer hits max value self.readyForTag = True
 * 1) set flag to write



Run the flowgraph. Tags will be displayed in the QT GUI Time Sink:



Detection Counter: Defining the Block
A new Embedded Python Block will be created to read the read the tags, count the number of samples since the last tag, and produce that number as an output.

Drag and drop a new Python Block into the GRC workspace. Do not copy and paste the existing python block, it will only create a second copy of Threshold Detector.

Double-click on the Embedded Python Block and edit the code.

Remove the self.example_param parameter: def __init__(self):

Change the name: name='Detection Counter',

Make the input and output ports Floats: in_sig=[np.float32], out_sig=[np.float32]

Remove the line self.example_param = example_param and the multiplication by self.example_param: output_items[0][:] = input_items[0]



Save the code (CTRL + S). Add another QT GUI Time Sink and change the properties:


 * QT GUI Time Sink
 * Name: "Detection Counter"
 * Number of Points: 2048
 * Autoscale: Yes

Connect the Detection Counter block after the Threshold Detection.



Detection Counter: Reading Tags
The Detection Counter block needs to be modified to read the tags.

Import the pmt library: import pmt

Add a new variable under __init__: self.samplesSinceDetection = 0



Now modify the work function to read the tags:

tagTuple = self.get_tags_in_window(0, 0, len(input_items[0]))
 * 1) get all tags associated with input_items[0]

Loop through all of the tags with key detect, calculate their relative offset and store it in a list:

relativeOffsetList = []
 * 1) declare a list

for tag in tagTuple: if (pmt.to_python(tag.key) == 'detect'): relativeOffsetList.append( tag.offset - self.nitems_read(0) )
 * 1) loop through all 'detect' tags and store their relative offset

Perform a sort of the offsets so they are ordered smallest to largest: relativeOffsetList.sort
 * 1) sort list of relative offsets

Loop through all of the output samples:

for index in range(len(output_items[0])):
 * 1) loop through all output samples

For each output sample, produce an output that is the number of samples since the last detect tag:

output_items[0][index] = self.samplesSinceDetection
 * 1) output is now samples since detection counter

If the current output sample index is greater than or equal to the index of the current detect tag, then remove the offset value from the list and reset the sample counter self.samplesSinceDetection. Otherwise, increase the sample counter by 1.

if (len(relativeOffsetList) > 0 and index >= relativeOffsetList[0]): # clear the offset relativeOffsetList.pop(0) # reset the output counter self.samplesSinceDetection = 0 else: # a detect tag has not been seen, so continue to increase # the output counter self.samplesSinceDetection = self.samplesSinceDetection + 1
 * 1) make sure the list is not-empty, and if the current input sample
 * 2) is greater than or equal to the next

Remove the output assignment: output_items[0][:] = input_items[0]

The work function should now look like:



Save the code (CTRL + S). Run the flowgraph. The output will now look like the following:



Notice that all of the tags from the input to Detection Counter are automatically conveyed to the output.

Tag Propagation
By default all input tags are propagated to all output tags. It can be useful to reduce or completely remove tags from certain streams. The Tag Gate block can be used to remove tags from an output stream. Connect the Tag Gate after the Detection Counter block:



Run the flowgraph. The tags will be removed from the QT GUI Time Sink:



The next tutorial, Low Pass Filter Example, demonstrates how to use filtering blocks in GNU Radio.