Tutorial 3: Working with GNU Radio in Python

# **Working with GNU Radio in Python**

## 目标
* Python Blocks
* OOT模块实现功能
* 如何添加OOT
* 如何用gr_modtool添加python block以及如何编写
* QPSK mapping
* 如何添加GRC绑定

## 前提
* 安装GNU Radio3.7.4 和 之后版本
* 建议了解 GRC Tutorial
* 熟悉python
----
## **3.1 简介**
本节分为三个部分。首先是如何建立、改变和简单理解GRC产生的python文件。其次，是如何从头开始建立自己的OOT模块。最后，我们举一个实际项目作为例子。和上一节一项，所有的源文件都在[gr-tutorial repository](https://github.com/gnuradio/gr-tutorial)中。

### **3.1.1 GRC生成的python文件**
先看一个GRC的例子
![title](https://leanote.com/api/file/getImage?fileId=58464b95ab644137810266b2)
点击Generate按钮，终端里会显示它生成了一个.py文件。打开该文件，代码如下：
```python
#!/usr/bin/env Python
##################################################
# Gnuradio Python Flow Graph
# Title: Tutorial Three
# Generated: Wed Mar 12 15:35:18 2014
##################################################

from gnuradio import analog
from gnuradio import audio
from gnuradio import eng_notation
from gnuradio import gr
from gnuradio.eng_option import eng_option
from gnuradio.filter import firdes
from optparse import OptionParser

class tutorial_three(gr.top_block):

def __init__(self):
        gr.top_block.__init__(self, "Tutorial Three")

##################################################
        # Variables
        ##################################################
        self.samp_rate = samp_rate = 32000

##################################################
        # Blocks
        ##################################################
        self.audio_sink_0 = audio.sink(samp_rate, "", True)
        self.analog_sig_source_x_1 = analog.sig_source_f(samp_rate, analog.GR_SIN_WAVE, 350, .1, 0)
        self.analog_sig_source_x_0 = analog.sig_source_f(samp_rate, analog.GR_SIN_WAVE, 440, .1, 0)

##################################################
        # Connections
        ##################################################
        self.connect((self.analog_sig_source_x_1, 0), (self.audio_sink_0, 1))
        self.connect((self.analog_sig_source_x_0, 0), (self.audio_sink_0, 0))

# QT sink close method reimplementation

def get_samp_rate(self):
        return self.samp_rate

def set_samp_rate(self, samp_rate):
        self.samp_rate = samp_rate
        self.analog_sig_source_x_0.set_sampling_freq(self.samp_rate)
        self.analog_sig_source_x_1.set_sampling_freq(self.samp_rate)

if __name__ == '__main__':
    parser = OptionParser(option_class=eng_option, usage="%prog: [options]")
    (options, args) = parser.parse_args()
    tb = tutorial_three()
    tb.start()
    raw_input('Press Enter to quit: ')
    tb.stop()
    tb.wait()
```
有了python文件，我们就可以修改文件，做一些GRC做不了的事情，比如[simulations](http://gnuradio.org/redmine/projects/gnuradio/wiki/Simulations)。现在来探索GRC python文件的结构。

## **3.1.2 Hello World 解析**
当检查代码的时候，我们需要熟悉文档。[GNU Radio的手册](http://gnuradio.org/doc/doxygen/)使用了Doxygen来做。浏览该文档最容易的方式是浏览我们正在使用的功能。因此让我们用简化的、仅仅包含框架的代码来运行一个dial-tone的例子。
例子：hello_world.py
```python
#!/usr/bin/env Python

from gnuradio import gr
from gnuradio import audio
from gnuradio import analog

class my_top_block(gr.top_block):
    def __init__(self):
        gr.top_block.__init__(self)

sample_rate = 32000
        ampl = 0.1

src0 = analog.sig_source_f(sample_rate, analog.GR_SIN_WAVE, 350, ampl)
        src1 = analog.sig_source_f(sample_rate, analog.GR_SIN_WAVE, 440, ampl)
        dst = audio.sink(sample_rate, "")
        self.connect(src0, (dst, 0))
        self.connect(src1, (dst, 1))

if __name__ == '__main__':
    try:
        my_top_block().run()
    except [[KeyboardInterrupt]]:
        pass
```

```
#!/usr/bin/env Python
```

这一句指定解释器。

<pre>
from gnuradio import gr
from gnuradio import audio
from gnuradio import analog
</pre>
导入需要的依赖。我们必须有导入gr来运行GNU Radio的应用。audio sink 和signal_source_f是被包括在audio模块中的，所以我们要导入。[PEP8](http://legacy.python.org/dev/peps/pep-0008/)告诉我们应该导入每个模块在单独行。(`这一段我不是很认同，感觉可以从一个包里一行直接导入所需要的模块的，暂且就这样吧`)
<pre>
class my_top_block(gr.top_block):
</pre>
定义my_top_block类派生自gr.top_block类。这个类是流图的容器。通过派生自gr.top_block，我们得到添加blocks和互联它们时所需的钩子和函数。
<pre>
def __init__(self):
</pre>
这个类中仅仅定义了一个成员函数__init__，它是该类的构造函数
<pre>
gr.top_block.__init__(self)
</pre>
父类的构造函数被调用。
<pre>
sample_rate = 32000
ampl = 0.1
</pre>
声明并初始化我们稍后会用到的变量

## **3.1.3 瞅一瞅文档**
<pre>
src0 = analog.sig_source_f(sample_rate, analog.GR_SIN_WAVE, 350, ampl)
src1 = analog.sig_source_f(sample_rate, analog.GR_SIN_WAVE, 440, ampl)
</pre>
可以在[the GNU Radio manual](http://gnuradio.org/doc/doxygen/classgr_1_1analog_1_1sig__source__f.html)中找到analog.sig_source_f的文档。
![title](https://leanote.com/api/file/getImage?fileId=58466827ab6441378102693d)
找到Member Function Documentation可以查看函数如何被使用和形参如下图
![title](https://leanote.com/api/file/getImage?fileId=58466862ab64413781026945)

继续查看audio.sink的使用手册
![title](https://leanote.com/api/file/getImage?fileId=58466af6ab6441703200b58a)
说明如下：
![title](https://leanote.com/api/file/getImage?fileId=58466b06ab644137810269ae)

## **3.14 将block互联**
<pre>
self.connect(src0, (dst, 0))
self.connect(src1, (dst, 1))
</pre>
连接模块的语法：self.connect(block1, block2, block3...)，这会将block1的输出连接到block2的输入上 ，block2的输出连接到block3的输入上，依次。这仅仅在一对一的端口时有效。如何我们一开始的流图，audio sink block有俩个输入咋办？可以用上面那个语法去连接。
幸运的是，现在我们有GRC这种东西可以画一画连一连，但是仍然有必要去了解GRC的底层原理是啥样子的，以便我们可以对程序有更大的可控性。
<pre>
if __name__ == '__main__':
    try:
        my_top_block().run()
    except KeyboardInterrupt:
        pass
</pre>
这几行表示，开始运行这个流图，并提供键盘中断。

## **3.1.5 修改GRC生成的py文件**

例如，如果我们需要当某个事件发生时改变频率或者幅度那该咋办。我们如何在GNU Radio中实现if语句，状态机等等。一种方式是不断钻研建立自己的block，另一种方式是直接改变GRC生成的py文件。

我们的朋友听说我们对RF感兴趣，因此恳求用RF给他家供电。白天，家里需要大功率来供给电视和玩游戏。晚上，家里只需要低功率来供给闹钟。我们首先设立计时器来追踪一天内时间的变化。1表示白天，0表示黑夜。一旦我们得到时间，我们可以通过后院的放大器和设备来供给能量(用正弦波表示)。我们简单评估一下，白天供给1kHz、1V，晚上供给100Hz、0.3V。我们先尝试构建下面的流图。
![title](https://leanote.com/api/file/getImage?fileId=5846773dab64413781026b1f)

- sine signal source中的Frequency设为"freq",Amplitude设为"ampl"
- Probe Signal的ID设为"probe"
- 其他参数如图所示

运行，得到下图。

![title](https://leanote.com/api/file/getImage?fileId=584a12f0ab6441378102ba3a)

然后打开GRC生成的py文件。

```python
#!/usr/bin/env python
##################################################
# Gnuradio Python Flow Graph
# Title: Top Block
# Generated: Wed Jul  2 01:39:19 2014
##################################################

from PyQt4 import Qt
from gnuradio import analog
from gnuradio import blocks
from gnuradio import eng_notation
from gnuradio import gr
from gnuradio import qtgui
from gnuradio.eng_option import eng_option
from gnuradio.filter import firdes
from optparse import OptionParser
import sip
import sys
import threading
import time

class top_block(gr.top_block, Qt.QWidget):

def __init__(self):
        gr.top_block.__init__(self, "Top Block")
        Qt.QWidget.__init__(self)
        self.setWindowTitle("Top Block")
        try:
             self.setWindowIcon(Qt.QIcon.fromTheme('gnuradio-grc'))
        except:
             pass
        self.top_scroll_layout = Qt.QVBoxLayout()
        self.setLayout(self.top_scroll_layout)
        self.top_scroll = Qt.QScrollArea()
        self.top_scroll.setFrameStyle(Qt.QFrame.NoFrame)
        self.top_scroll_layout.addWidget(self.top_scroll)
        self.top_scroll.setWidgetResizable(True)
        self.top_widget = Qt.QWidget()
        self.top_scroll.setWidget(self.top_widget)
        self.top_layout = Qt.QVBoxLayout(self.top_widget)
        self.top_grid_layout = Qt.QGridLayout()
        self.top_layout.addLayout(self.top_grid_layout)

self.settings = Qt.QSettings("GNU Radio", "top_block")
        self.restoreGeometry(self.settings.value("geometry").toByteArray())

##################################################
        # Variables
        ##################################################
        self.variable_function_probe_0 = variable_function_probe_0 = 0
        self.samp_rate = samp_rate = 32000
        self.freq = freq = 1000
        self.ampl = ampl = 1

##################################################
        # Blocks
        ##################################################
        self.probe = blocks.probe_signal_f()
        self._freq_tool_bar = Qt.QToolBar(self)
        self._freq_tool_bar.addWidget(Qt.QLabel("freq"+": "))
        self._freq_line_edit = Qt.QLineEdit(str(self.freq))
        self._freq_tool_bar.addWidget(self._freq_line_edit)
        self._freq_line_edit.returnPressed.connect(
            lambda: self.set_freq(int(self._freq_line_edit.text().toAscii())))
        self.top_layout.addWidget(self._freq_tool_bar)
        self._ampl_tool_bar = Qt.QToolBar(self)
        self._ampl_tool_bar.addWidget(Qt.QLabel("ampl"+": "))
        self._ampl_line_edit = Qt.QLineEdit(str(self.ampl))
        self._ampl_tool_bar.addWidget(self._ampl_line_edit)
        self._ampl_line_edit.returnPressed.connect(
            lambda: self.set_ampl(int(self._ampl_line_edit.text().toAscii())))
        self.top_layout.addWidget(self._ampl_tool_bar)
        def _variable_function_probe_0_probe():
            while True:
                val = self.probe.level()
                try:
                    self.set_variable_function_probe_0(val)
                except AttributeError:
                    pass
                time.sleep(1.0 / (10))
        _variable_function_probe_0_thread = threading.Thread(target=_variable_function_probe_0_probe)
        _variable_function_probe_0_thread.daemon = True
        _variable_function_probe_0_thread.start()
        self.qtgui_time_sink_x_0 = qtgui.time_sink_f(
            1024, #size
            samp_rate, #samp_rate
            "QT GUI Plot", #name
            1 #number of inputs
        )
        self.qtgui_time_sink_x_0.set_update_time(0.10)
        self.qtgui_time_sink_x_0.set_y_axis(-1, 1)
        self.qtgui_time_sink_x_0.enable_tags(-1, True)
        self.qtgui_time_sink_x_0.set_trigger_mode(qtgui.TRIG_MODE_FREE, qtgui.TRIG_SLOPE_POS, 0.0, 0, 0, "")
        self.qtgui_time_sink_x_0.enable_autoscale(False)

labels = ["", "", "", "", "",
                  "", "", "", "", ""]
        widths = [1, 1, 1, 1, 1,
                  1, 1, 1, 1, 1]
        colors = ["blue", "red", "green", "black", "cyan",
                  "magenta", "yellow", "dark red", "dark green", "blue"]
        styles = [1, 1, 1, 1, 1,
                  1, 1, 1, 1, 1]
        markers = [-1, -1, -1, -1, -1,
                   -1, -1, -1, -1, -1]
        alphas = [1.0, 1.0, 1.0, 1.0, 1.0,
                  1.0, 1.0, 1.0, 1.0, 1.0]

for i in xrange(1):
            if len(labels[i]) == 0:
                self.qtgui_time_sink_x_0.set_line_label(i, "Data {0}".format(i))
            else:
                self.qtgui_time_sink_x_0.set_line_label(i, labels[i])
            self.qtgui_time_sink_x_0.set_line_width(i, widths[i])
            self.qtgui_time_sink_x_0.set_line_color(i, colors[i])
            self.qtgui_time_sink_x_0.set_line_style(i, styles[i])
            self.qtgui_time_sink_x_0.set_line_marker(i, markers[i])
            self.qtgui_time_sink_x_0.set_line_alpha(i, alphas[i])

self._qtgui_time_sink_x_0_win = sip.wrapinstance(self.qtgui_time_sink_x_0.pyqwidget(), Qt.QWidget)
        self.top_layout.addWidget(self._qtgui_time_sink_x_0_win)
        self.blocks_throttle_0 = blocks.throttle(gr.sizeof_float*1, samp_rate,True)
        self.analog_sig_source_x_1 = analog.sig_source_f(samp_rate, analog.GR_SIN_WAVE, freq, ampl, 0)
        self.analog_sig_source_x_0 = analog.sig_source_f(samp_rate, analog.GR_SQR_WAVE, 0.1, 1, 0)

##################################################
        # Connections
        ##################################################
        self.connect((self.analog_sig_source_x_0, 0), (self.blocks_throttle_0, 0))
        self.connect((self.blocks_throttle_0, 0), (self.probe, 0))
        self.connect((self.analog_sig_source_x_1, 0), (self.qtgui_time_sink_x_0, 0))

# QT sink close method reimplementation
    def closeEvent(self, event):
        self.settings = Qt.QSettings("GNU Radio", "top_block")
        self.settings.setValue("geometry", self.saveGeometry())
        event.accept()

def get_variable_function_probe_0(self):
        return self.variable_function_probe_0

def set_variable_function_probe_0(self, variable_function_probe_0):
        self.variable_function_probe_0 = variable_function_probe_0

def get_samp_rate(self):
        return self.samp_rate

def set_samp_rate(self, samp_rate):
        self.samp_rate = samp_rate
        self.blocks_throttle_0.set_sample_rate(self.samp_rate)
        self.analog_sig_source_x_0.set_sampling_freq(self.samp_rate)
        self.qtgui_time_sink_x_0.set_samp_rate(self.samp_rate)
        self.analog_sig_source_x_1.set_sampling_freq(self.samp_rate)

def get_freq(self):
        return self.freq

def set_freq(self, freq):
        self.freq = freq
        Qt.QMetaObject.invokeMethod(self._freq_line_edit, "setText", Qt.Q_ARG("QString", str(self.freq)))
        self.analog_sig_source_x_1.set_frequency(self.freq)

def get_ampl(self):
        return self.ampl

def set_ampl(self, ampl):
        self.ampl = ampl
        Qt.QMetaObject.invokeMethod(self._ampl_line_edit, "setText", Qt.Q_ARG("QString", str(self.ampl)))
        self.analog_sig_source_x_1.set_amplitude(self.ampl)

if __name__ == '__main__':
    import ctypes
    import sys
    if sys.platform.startswith('linux'):
        try:
            x11 = ctypes.cdll.LoadLibrary('libX11.so')
            x11.XInitThreads()
        except:
            print "Warning: failed to XInitThreads()" 
    parser = OptionParser(option_class=eng_option, usage="%prog: [options]")
    (options, args) = parser.parse_args()
    Qt.QApplication.setGraphicsSystem(gr.prefs().get_string('qtgui','style','raster'))
    qapp = Qt.QApplication(sys.argv)
    tb = top_block()
    tb.start()
    tb.show()
    def quitting():
        tb.stop()
        tb.wait()
    qapp.connect(qapp, Qt.SIGNAL("aboutToQuit()"), quitting)
    qapp.exec_()
    tb = None #to clean up Qt widgets
```
我们先看probe被读的部分。
```python
def _variable_function_probe_0_probe():
            while True:
                val = self.probe.level()
                try:
                    self.set_variable_function_probe_0(val)
                except AttributeError:
                    pass
                time.sleep(1.0 / (10))
```
变量val存储着probe block的值，我们可以基于这val值来改变sin波的幅度和频率。找到下面这段代码：
```python
  def set_freq(self, freq):
        self.freq = freq
        Qt.QMetaObject.invokeMethod(self._freq_line_edit, "setText", Qt.Q_ARG("QString", str(self.freq)))
        self.analog_sig_source_x_1.set_frequency(self.freq)
```
和
```python
   def set_ampl(self, ampl):
        self.ampl = ampl
        Qt.QMetaObject.invokeMethod(self._ampl_line_edit, "setText", Qt.Q_ARG("QString", str(self.ampl)))
        self.analog_sig_source_x_1.set_amplitude(self.ampl)
```
我们可以看见set_ampl和set_freq函数被用来设置幅度和频率。因此，我们可以用if-else语句改变probe function，来实现给我们的朋友发送不同时段的不同的能量。
```python
def _variable_function_probe_0_probe():
            while True:
                val = self.probe.level()
                print val
                if val == 1:
                    self.set_ampl(1)
                    self.set_freq(1000)
                else:
                    self.set_ampl(.3)
                    self.set_freq(100)
                try:
                    self.set_variable_function_probe_0(val)
                except AttributeError:
                    pass
                time.sleep(1.0 / (10))
```
终端里执行
```bash
python if_else_mod.py
```
可以发现随着方波的瞬时值的改变，正弦波的幅度和频率也在交替变换。

本教程仅仅是介绍基于GNU Radio使用python。更详细的教程可以在[TutorialsWritePythonApplications](http://gnuradio.org/redmine/projects/gnuradio/wiki/TutorialsWritePythonApplications)

# 3.2. Blocks如何形成的？

现在我们已经掌握更改GRC生成的py文件来满足特定项目功能的方式。接下来我们将准备试一试创建一个block用来实现乘以一个特定的数。首先，我们需要知道GNU Radio自带gr_modtool工具，它可以用来很容易的创建模块。让我们打开终端，创建一个项目文件夹，开始学习。

## 3.2.1 使用gr_modtool
打卡终端，通过gr_modtool help查看命令使用方式如下：
```bash
$ gr_modtool help
Usage:
gr_modtool <command> [options] -- Run <command> with the given options.
gr_modtool help -- Show a list of commands.
gr_modtool help <command> -- Shows the help for a given command.

List of possible commands:

Name      Aliases          Description
=====================================================================
disable   dis              Disable block (comments out CMake entries for files)
info      getinfo,inf      Return information about a given module
remove    rm,del           Remove block (delete files and remove Makefile entries)
makexml   mx               Make XML file for GRC block bindings
add       insert           Add block to the out-of-tree module.
newmod    nm,create        Create a new out-of-tree module
```
在本教程中，我们仅仅介绍newmod和add的使用方式。其他命令可以通过help查看文档。

首先，查看newmod的帮助文档，如下：
```bash
$ gr_modtool help newmod
Usage: gr_modtool nm [options].
 Call gr_modtool without any options to run it interactively.

Options:
  General options:
    -h, --help          Displays this help message.
    -d DIRECTORY, --directory=DIRECTORY
                        Base directory of the module. Defaults to the cwd.
    -n MODULE_NAME, --module-name=MODULE_NAME
                        Use this to override the current module's name (is
                        normally autodetected).
    -N BLOCK_NAME, --block-name=BLOCK_NAME
                        Name of the block, where applicable.
    --skip-lib          Don't do anything in the lib/ subdirectory.
    --skip-swig         Don't do anything in the swig/ subdirectory.
    --skip-Python       Don't do anything in the Python/ subdirectory.
    --skip-grc          Don't do anything in the grc/ subdirectory.
    --scm-mode=SCM_MODE
                        Use source control management (yes, no or auto).
    -y, --yes           Answer all questions with 'yes'. This can overwrite
                        and delete your files, so be careful.

New out-of-tree module options:
    --srcdir=SRCDIR     Source directory for the module template
```
我们要学会的是-n这一选项，后面跟模块名。

## 3.2.2 建立新block

```bash
$ gr_modtool newmod tutorial
Creating out-of-tree module in ./gr-tutorial... Done.
Use 'gr_modtool add' to add a new block to this currently empty module
```
注意：我练习时命名成test，结果在后续步骤中出现了模块无法找到等奇怪情况，应该是和其他内置的一些东西冲突了。建议不要起内置的一些名称。。

我们应该能够在当前目录下看到一个新的目录。进入该目录看看gr_modtool干了什么事情。
```shell
gr-tutorial$ ls
apps  cmake  CMakeLists.txt  docs  examples  grc  include  lib  Python  swig
```
因为我们在本教程中使用python，所以只需要关注python文件夹和grc文件夹。在深入代码之前，我们需要根据模板创建block。有四种类型的blocks，但是现在介绍操之过急。我们会举一个synchronous 1:1 input to output类型(输入和输出数相同)的例子以便说明。

现在我们知道我们会用python编写block和我们要添加的block类型。那么怎么添加block？我们需要add这个命令。通过help查看add的使用方式如下：
```
gr-tutorial$ gr_modtool help add
... (General Options from Last Help)
Add module options:
    -t BLOCK_TYPE, --block-type=BLOCK_TYPE
                        One of sink, source, sync, decimator, interpolator,
                        general, tagged_stream, hier, noblock.
    --license-file=LICENSE_FILE
                        File containing the license header for every source
                        code file.
    --argument-list=ARGUMENT_LIST
                        The argument list for the constructor and make
                        functions.
    --add-Python-qa     If given, Python QA code is automatically added if
                        possible.
    --add-cpp-qa        If given, C++ QA code is automatically added if
                        possible.
    --skip-cmakefiles   If given, only source files are written, but
                        CMakeLists.txt files are left unchanged.
    -l LANG, --lang=LANG
                        Language (cpp or Python)
```
我们可以看到-l LANG 和-t BLOCK_TYPE是和我们的例子相关联的。使用add命令添加模块。过程中会提示写入name、arguments list、QA（Quantity Assurance），依次填"multiply_py_ff"、"multiple"、"y"。
```bash
gr-tutorial$ gr_modtool add -t sync -l python
GNU Radio module name identified: tutorial
Language: Python
Enter name of block/code (without module name prefix): multiply_py_ff
Block/code identifier: multiply_py_ff
Enter valid argument list, including default arguments: multiple
Add Python QA code? [Y/n] y
Adding file 'Python/multiply_py_ff.py'...
Adding file 'Python/qa_multiply_py_ff.py'...
Editing Python/CMakeLists.txt...
Adding file 'grc/tutorial_multiply_py_ff.xml'...
Editing grc/CMakeLists.txt...
```
我们能观察到grc和python的五处变化：

1. 由两处改变是在CMakeLists.files里
 2. grc下多了一个tutorial_multiply_py_ff.xml文件，用于连接block到GRC。
 3. python下多了multiply_py_ff.py（功能部分）和qa_multiply_py_ff.py（用来测试代码）文件

### 3.2.2.1 _ff是什么？

对于拥有严格数据类型的block，我们用后缀来表明输入输出数据类型。因为该模块输入输出都是floats，所以我们用后缀_ff来表示：float in，float out。其他还有_cc(complex in, complex out)，或者简单的_f(a sink or source with no in- or outputs that uses floats)。更多详细描述，见(FAQ)[http://gnuradio.org/redmine/projects/gnuradio/wiki/FAQ]和(BlocksCodingGuide)[http://gnuradio.org/redmine/projects/gnuradio/wiki/BlocksCodingGuide]

## 3.2.3. 改变python block file

打开multiply_py_ff.py，如下：
```
import numpy
from gnuradio import gr

class multiply_py_ff(gr.sync_block):
    """ 
    docstring for block multiply_py_ff
    """ 
    def __init__(self, multiple):
        gr.sync_block.__init__(self,
            name="multiply_py_ff",
            in_sig=[<+numpy.float+>],
            out_sig=[<+numpy.float+>])
        self.multiple = multiple

def work(self, input_items, output_items):
        in0 = input_items[0]
        out = output_items[0]
        # <+signal processing here+>
        out[:] = in0
        return len(output_items[0])
```
我们一行行的看，import很简单，跳过。然后是__init__部分。如果我们需要multiple参数，那么我们需要加这一句。
```
self.multiple = multiple
```
我们观察到程序里有很多"<+...+>"字样。这些占位符都来自gr_modtool，这是告诉我们这里需要改动。
```
in_sig=[<+numpy.float+>]
out_sig=[<+numpy.float+>]
```
gr.sync_block.__init__有四个形参：self, name, 输入类型，输出类型。如果我们想将输入或输出设置为单精度float，那么可以用numpy.float32替代之。如果我们设置输入为向量，那么可以像这样设置：[(numpy.float32, 4), numpy.float32]。这意味着有俩个输入端口，一个是用于向量（4个float），另一个用于标量。如果输入为空，则意味着它是个source block。同样，如果输出为空，那么它是个sink block，当然此时你需要将return len(output_item[0])改为return len(input_item[0])。
这里，我们将输入输出改动如下:
```python
in_sig = [numpy.float32]
out_sig = [numpy.float32]
```
另一段代码是work函数。
```
def work(self, input_items, output_items)
```
因为这是sync block，所以输入的数目和输出的数目相同。抽取和差值blocks也同样如此。我们将要进一步讨论什么时候用什么类型的block。现在我们看看占位符：
```python
in0 = input_items[0]
out = output_items[0]
# <+signal processing here+>
out[:] = in0
return len(output_items[0])
```
"in0" 和 "out"存储输入和输出。信号处理可以包括if语句、循环、函数调用。但是对于这个例子来说，我们只需要改动out[:] = in0以便我们输入信号可以被乘到我们的变量上。所以我们需要添加下面这句来让in0乘以multiple参数。
```python
out[:] = in0 * self.multiple
```
我们的block现在可以"乘"了。但是确保我们有Quality Assurance test！

## 3.2.4 QA Tests

现在我们需要测试block以确保可以其正确运行。这是一个非常重要的步骤，我们不应该忘记测试我们的代码!让我们打开qa_mulitply_py_ff.py如下：
```python
from gnuradio import gr, gr_unittest
from gnuradio import blocks
from multiply_py_ff import multiply_py_ff

class qa_multiply_py_ff (gr_unittest.TestCase):

def setUp (self):
        self.tb = gr.top_block ()

def tearDown (self):
        self.tb = None

def test_001_t (self):
        # set up fg
        self.tb.run ()
        # check data

if __name__ == '__main__':
    gr_unittest.run(qa_multiply_py_ff, "qa_multiply_py_ff.xml")
```

gr_unittest添加支持对元组float和complex类型的检查。我们需要考量的是test_001_t函数。我们首先得构造数据。我们想要它以一个向量的形式，以便于我们可以一次可以测试多个值。让我们构建一个float向量。
```python
src_data = (0, 1, -2, 5.5, -0.5)
```
我们也需要输出数据，所以我们比较block的输出以确保，我们也需要构造输出数据，简单起见，我们在输入的基础上都乘以2
```python
expected_data = (0, 2, -4, 11, -1)
```
现在我们可以创建一个流图，就像我们第一次在GNU Radio中使用python一样。可以阅读[vector_source_f](http://gnuradio.org/doc/doxygen/classgr_1_1blocks_1_1vector__source__f.html)和[vector_sink_f](http://gnuradio.org/doc/doxygen/classgr_1_1blocks_1_1vector__sink__f.html)的文档。先定义三个变量src、mult、sink。
```
src = blocks.vector_source_f(src_data)
mult = multiply_py_ff(2)
snk = blocks.vector_sink_f()
```
现在我们需要连接src->mult->snk。在这里我们没用self.connect，y因为top_block()在setUp函数中给了self.tb，我们需要用self.tb.connect。如下：
```
self.tb.connect(src, mult)
self.tb.connect(mult, snk)
```
然后我们可以run这个流图，并将sink的数据取出，如下：
```
self.tb.run()
result_data = snk.data()
```
用assertFloatTuplesAlmostEqual代替python的unittest中的assert方法（参见https://docs.python.org/2/library/unittest.html#assert-methods，由于浮点数的四舍五入，会导致结果结果不对）来比较结果，
```
self.assertFloatTuplesAlmostEqual(expected_result, result_data, 6)
```
将上述的代码结合一起：
```
src_data = (0, 1, -2, 5.5, -0.5)
expected_result = (0, 2, -4, 11, -1)
src = blocks.vector_source_f(src_data)
mult = multiply_py_ff(2)
snk = blocks.vector_sink_f()
self.tb.connect(src, mult)
self.tb.connect(mult, snk)
self.tb.run()
result_data = snk.data()
self.assertFloatTuplesAlmostEqual(expected_result, result_data, 6)
```
我们可以到python目录下，然后运行
```
gr-tutorial/python$ python qa_multiply_py_ff.py
.
----------------------------------------------------------------------
Ran 1 test in 0.004s

OK
```
学习到这，我们可以改变src_data中的值，确保block没有问题。python可以在不编译的情况系快速测试block。
注：
```
 def assertFloatTuplesAlmostEqual (self, a, b, places=7, msg=None):
         self.assertEqual (len(a), len(b))
         for i in xrange (len(a)):
             self.assertAlmostEqual (a[i], b[i], places, msg)
```

## 3.2.5. XML Files
现在我们已经能写python的block和QA测试。接下来要做的是编辑grc目录下的XML文件，以便于我们可以在GRC中使用它。GRC用XML文件去表征所有我们能看到的选项。我们实际不需要写任何python或者c++代码。切到grc目录下。gr_modtool里有个工具叫makexmk，但是这个实际上是用于c++ block，所以我们还是老老实实改xml文件吧。
```xml
<?xml version="1.0"?>
<block>
  <name>multiply_py_ff</name>
  <key>tutorial_multiply_py_ff</key>
  <category>tutorial</category>
  <import>import tutorial</import>
  <make>tutorial.multiply_py_ff($multiple)</make>
  
  <param>
    <name>...</name>
    <key>...</key>
    <type>...</type>
  </param>

<sink>
    <name>in</name>
    <type></type>
  </sink>

<source>
    <name>out</name>
    <type></type>
  </source>
</block>
```
name标签里包含的是显示的名称，category包含的是显示的目录
我们还看到了下面这段文本注释：
```

```
当我们创建我们的block时，这个会被对应到block的参数。我们可以按照下面填：
```
  <param>
    <name>Multiple</name>
    <key>multiple</key>
    <type>float</type>
  </param>
```
接下来是sink和source的标签：
```
<sink>
    <name>in</name>
    <type></type>
</sink>
```
在source和sink的标签中，我们可以填写type为float。填写xml文件的最好的方式是查看之前写的block的源码

## 3.2.6 安装Python Blocks
现在我们已经编辑好了XML文件;我们准备安装它到GRC中。首先，我们需要跳出grc目录。创建一个build目录。在build目录中，我们运行下列命令:
```bash
cmake ../
make
sudo make install
sudo ldconfig
```
我们打开GRC，瞅一眼新的block
![title](https://leanote.com/api/file/getImage?fileId=584e2b7aab64416c6b00269d)
我们可以看到命名的目录和名称。让我们测试它以确保其工作正常。下面是一个例子来测试，也是许多测试方法之一。
![title](https://leanote.com/api/file/getImage?fileId=584e2be6ab64416c6b0026a3)

# 3.3. 卫星的QPSK解调
现在我们已经添加一个新的block到GRC中了，我们再举另外一个例子。这次我们将要用之前的相同方法创建一个QPSK解调block。
我们想象以下场景：有一个noise source输出复数float的数据，但是我们假装它来自卫星。我们的情报人员告诉我们这个特殊的卫星用QPSK编码数字信号。我们可以用QPSK解码，将数据按字节输出。我们情报人员告诉我们不确定是否是格雷码。我们想要用一个time sink读取bytes。那么问题来了，我们的流图像什么样子?
![title](https://leanote.com/api/file/getImage?fileId=584e3036ab64416d7500271e)
现在，我们知道输入类型，输出类型和参数，我们可以考虑一下之前在写multiply_py_ff block的问题-我们应该选择什么类型的block?

## 3.3.1 选择一个Block类型
GNU Radio调度器优化吞吐量（比如改进延迟）。要做到这一点，它需要知道每个块输入和输出的样本数，从而产生抽取和插值块，其中我们指定多因子。这与我们在教程2中讨论的采样率直接相关，这些特殊类型的块能够将采样率改变为其他值，以便符合特定的硬件，例如我们的声卡或特定的调制/解调。
* Synchronous(1:1) - 输入和输出端口的数量相等。比如multiply_py_ffblock
* Decimation(N:1) - 输入端口时输出端口数量的倍数。比如抽取高通滤波器和低通滤波器。
* Interpolation(1:M) - 输出端口是输入端口的倍数。比如，插值FIR滤波器。
* Gerneral/Basic(N:M) - 输入和输出之间没有关系。比如合理的重采样器块，其可以是同步，抽取器或内插器。

我们需要使用的block是Sync Block或者Basic Block

## 3.3.2 添加另一个block到我们的OOT模块
现在我们知道了用gr_modtool创建block的每一件事情。复习一下命令：
```bash
gr-tutorial$ gr_modtool add -t sync -l python
```
name:qpsk_demod_py_cb(c是complex输，b是指byte/char/int8输出)
args:gray_code
QA：y
现在我们开始编辑在python目录下的qpsk_demod_py.py文件。

## 3.3.3. QPSK解调器

首先，我们规划一下。我们可以考虑一个星座图，其有四个分量，均用二进制表示。

使用格雷码。注意我们这用的映射是不同于维基百科上的。

>(-1+1j) 10 | 00 (1+1j)
-----------+-----------
(-1-1j) 11 | 01 (1-1j)

不使用格雷码：
>(-1+1j) 11 | 00 (1+1j)
-----------+-----------
(-1-1j) 10 | 01 (1-1j)

既然用到了格雷码，那么我们就避免不了使用if-else语句。我们在if-else语句中也需要四个if-else来完成映射。伪代码如下：
```
if gray_code
    if 1+1j
        binary "00" = 0
        ....
    elif -1-1j
        binary "11" = 3
else
    if 1+1j
        binary "00" = 0
        ....
    elif -1-1j
        binary "10" = 2
```
开始编写py文件的init部分，如下：
```
def __init__(self, gray_code):
    self.gray_code = gray_code
    gr.sync_block.__init__(self,
        name="qpsk_demod_py",
        in_sig=[numpy.complex64],
        out_sig=[numpy.uint8]);
```
然后是work函数，简单起见，编写一个"get_minimum_distance"函数，将采样作为输入，内容即是上面的伪码要实现的功能。
在multiply_py_ff例子中，我们处理所有采样点，通过out[:] = in0 * self.multiple。in0世纪是一个vector，其包含许多采样点。那个例子每个采样都是需要同样的操作，所以整个向量乘以一个值就ok了。但是先，我们需要对每个采样进行不同的操作，就应该如下操作。
```
 for i in range(0, len(in0)):
            sample = in0[i]
            out[i] = self.get_minimum_distances(sample)
```
现在我们开始编写get_minimum_distance(self, sample)函数。我们已经有了伪代码，所以下一步是将其翻译成python。下面是代码片段。
```
def get_minimum_distance(self, sample):
    if self.gray_code = 1:
        if (sample.imag>=0 and sample.read>=0 ):
            return 0 # 1+1j
        elif (sample.imag>=0 and sample.real<0):
            return 2 # -1+1j
```
让我们试着填写gray_code的其他情况以及非格雷码情况下语句。下面是整个python文件：
```
import numpy
from gnuradio import gr

class qpsk_demod_py(gr.sync_block):
    """ 
    docstring for block qpsk_demod_py
    """ 
    def __init__(self, gray_code):
        self.gray_code=gray_code
        gr.sync_block.__init__(self,
            name="qpsk_demod_py",
            in_sig=[numpy.complex64],
            out_sig=[numpy.uint8])

def get_minimum_distances(self, sample):
        if self.gray_code == 1:
            if (sample.imag >= 0 and sample.real >= 0):
                return 0 # 1+1j
            elif (sample.imag >= 0 and sample.real < 0):
                return 2 # -1+1j
            elif (sample.imag < 0 and sample.real < 0):
                return 3 # -1-1j
            elif (sample.imag < 0 and sample.real >= 0):
                return 1 # 1-1j
        else:
            if (sample.imag >= 0 and sample.real >= 0):
                return 0 # 1+1j
            elif (sample.imag >= 0 and sample.real < 0):
                return 3 # -1+1j
            elif (sample.imag < 0 and sample.real < 0):
                return 2 # -1-1j
            elif (sample.imag < 0 and sample.real >= 0):
                return 1 # 1-1j

def work(self, input_items, output_items):
        in0 = input_items[0]
        out = output_items[0]

for i in range(0, len(in0)):
            sample = in0[i]
            out[i] = self.get_minimum_distances(sample)

return len(output_items[0])
```

### 3.3.4 Multiple QA Tests
我们可以测试qpsk_demod_py分别在gray_code为1和0时的输出。所以我们需要在QA文件里建立多个测试。QA通常和之前的结构一样。我们定义一些输入，然后对比输出和期望输出。唯一不同是，多个qa测试需要多个测试用例。有四个象限和两种模式，因此我们需要8个用例。我们可以打开qa_qpsk_demode_py_ff文件来修改这些。
之前qa_multiply_py_ff的代码如下：
```
def test_001_t (self):
    src_data = (-3, 4, -5.5, 2, 3)
    expected_result = (-6, 8, -11, 4, 6)
    src = blocks.vector_source_f (src_data)
    mult = multiply_py_ff (2)
    dst = blocks.vector_sink_f ()
    self.tb.connect (src, mult)
    self.tb.connect (mult, dst)
    self.tb.run ()
    result_data = dst.data ()
    self.assertFloatTuplesAlmostEqual (expected_result, result_data, 6)
```
这次，我们的输入是复数，所以需要改变类型，查找手册可以发现其他选项：
>b - bytes/unsigned char/int8
c - complex
f - float
i - int
s - short
```
src = blocks.vector_source_c(src_data)
dst = blocks.vector_sink_b()
```
我们还需要创建一个变量gray_code来表明是哪种测试模式
比如
```
gray_code = False
```
一旦我们确认测试的是哪种模式，我们可以根据上面的设定，来编写一些适合的输入和期望输出。例如，如果我们测试非格雷模式下的两个例子，我们可以：
```
src_data = ((-1-1j), (-1+1j))
expected_result = (2, 3)
```
最后一件事情是调用新的block，然后传递参数
```
qpsk = qpsk_demod_py_cb(gray_code)
```
现在我们完成了非格雷码模式下的测试，我们可以再定义另外一个测试函数"def tess_002_t(self)"。
完整代码如下：
```
from gnuradio import gr, gr_unittest
from gnuradio import blocks
import numpy
from qpsk_demod_py_cb import qpsk_demod_py

class qa_qpsk_demod (gr_unittest.TestCase):

def setUp (self):
        self.tb = gr.top_block ()

def tearDown (self):
        self.tb = None

def test_001_t (self):
        gray_code = False
        src_data = ((-1-1j), (-1+1j), (1+1j), (1-1j))
        expected_result = (2, 3, 0, 1)
        src = blocks.vector_source_c (src_data)
        qpsk = qpsk_demod_py (gray_code)
        dst = blocks.vector_sink_b ()
        self.tb.connect (src, qpsk)
        self.tb.connect (qpsk, dst)
        self.tb.run ()
        result_data = dst.data ()
        self.assertFloatTuplesAlmostEqual (expected_result, result_data, 6)

def test_002_t (self):
        gray_code = True
        src_data = ((-1-1j), (-1+1j), (1+1j), (1-1j))
        expected_result = (3, 2, 0, 1)
        src = blocks.vector_source_c (src_data)
        qpsk = qpsk_demod_py (gray_code)
        dst = blocks.vector_sink_b ()
        self.tb.connect (src, qpsk)
        self.tb.connect (qpsk, dst)
        self.tb.run ()
        result_data = dst.data ()
        self.assertFloatTuplesAlmostEqual (expected_result, result_data, 6)

if __name__ == '__main__':
    gr_unittest.run(qa_qpsk_demod, "qpsk_demod_py_cb.xml")
```
运行qa测试，我们可以得到：
```
Ran 2 tests in 0.005s

OK
```
从而我们可以确认它工作正常，然后我们可以编辑XML文件，安装到GRC中去。

### 3.3.5 
这个XML和multiply_py_ff的XML文件相似，我们需要做的是设置gray_code参数以及正确的输入输出类型。如下：
```xml
<?xml version="1.0"?>
<block>
  <name>qpsk_demod_py</name>
  <key>tutorial_qpsk_demod_py</key>
  <category>tutorial</category>
  <import>import tutorial</import>
  <make>tutorial.qpsk_demod_py($gray_code)</make>
  
  <param>
    <name>Gray Code</name>
    <key>gray_code</key>
    <type>int</type>
  </param>

<sink>
    <name>in</name>
    <type>complex</type>
  </sink>

<source>
    <name>out</name>
    <type>byte</type>
  </source>
</block>
```
然后安装，为了加入新的block，我们需要重新cmake编译:
```bash
cd build
cmake ../
make
sudo make install
sudo ldconfig
```
打开GRC文件，然后构建流图，期望输出如下：
![title](https://leanote.com/api/file/getImage?fileId=58520a59ab64416d76004a5a)

# 3.4. 总结

这节是关于python，关于c++的教程，请移步[c++ tutorial](http://gnuradio.org/redmine/projects/gnuradio/wiki/NewTutorials4)

## 3.4.1 现在我们有能力解答的问题

1. 我们如何在python的blocks中设定输入和输出
2. Consider this I/O signature: (FIXME). Which input types and output types does it take?

## 3.4.2 关于高级教程的一些链接
* [Blocks Coding Guide](http://gnuradio.org/redmine/projects/gnuradio/wiki/BlocksCodingGuide)
* [Out-of-Tree Modules](http://gnuradio.org/redmine/projects/gnuradio/wiki/OutOfTreeModules)
* [Writing Python Applications](http://gnuradio.org/redmine/projects/gnuradio/wiki/TutorialsWritePythonApplications)

# 3.5 将来的候选章节

Possible topics we may want to add depending on feedback and questions on the mailing list
- 如何给blocks添加documentation
- 构造函数参数，历史，多输入

逆风起笔