[转]GNU Radio Companion - GRC

GNU Radio Companion - GRC

注：该文档适应于捆绑 GNU Radio 的 GRC，它不适应任何独立发行本的 GRC。如果想使用 GRC 0.70 请参阅 GNU Radio Companion (Old) 。

GNU Radio Companion (GRC) 是一个用来产生信号流程图及流程图源代码的图形化工具。它目前是由 Josh Blum 构建。  

新特性 

同稳定版 GRC 0.70 不同的，GRC 目前有哪些新特性？

• 捆绑式发行（Bundled）- GRC 目前是同 GNU Radio 源代码捆绑在一起。如若所有的依赖关系得以满足，GRC 便会在 GNU Radio 安装的同时被安装。相关内容请参阅安装及运行部分。
• 桌面的集成（Desktop Integration）- GRC 可以被完全的集成到支持自由桌面风格标准元素的桌面环境（xdg-utils 兼容）中：这些元素包括图标（icons）、文件扩展（mime type）、及菜单（menu items）等。
• 代码的生成（Code Generation）- GRC 不再仅仅孤立的通过可执行文件载入 *.grc.xml 并动态地构建流程图。相应地，GRC 它使用模板（Cheetah templates） 来生成用于构建流程图的 python 源代码。GRC 可生成用户图形接口（WX GUI） 及非图形接口（non-GUI）的流程图的代码，也可生成阶梯形功能模块（hierarchical blocks）。
• 文档的生成（Documentation）- GRC 能够通过对基于 doxygen 生成的 xml 文档的提取来为 GNU Radio 的功能模块构建文档。该功能能够被使用的前提是在 GNU Radio 的安装配置过程中需激活 doxygen 功能。 
• 变量的处理（Variables）- 早期版本的变量编辑窗口（variable editor window）现在被变量功能模块（variable blocks）所取代。该变量功能模块在流程图的构建时被用到，它同其它功能模块的行为表现无异，所不同的是它没有 IO 端口。变量功能模块将其唯一性的标识（也就是变量的名称）映射成一个特定的数值。GRC 还有几个图形化变量功能模块用来构建 WX GUI 类型的用户图形接口的流程图，它使得该流程图具有可视化控制表现形式，滑动条控件（sliders）、文本框（text boxes）、按钮（buttons）、下拉框（drop downs）、及单选按钮（radio buttons）。
• 功能的定义（Block Definitions）- GRC 中的每一个模块都有一个对应的 xml 文件，它包含参数、IO 端口、及用于代码生成用的模板。每个 xml 文件的关键标识（id）及文件名称同 GNU Radio 的功能块严格对应，其目的是确保其日后的可移植性（portability）。在模块被执行时 GRC 确认模块的所有的定义，只要有定义不能被确认时，该模块便会报错并退出其运行过程。
• 文件的格式（File Format） - 假定变量及功能块的定义有所改动的话，其对应的内部被存储的流程图的构架也会相应更改。幸运的是，GRC 会自动将旧有的流程图转化为新的内容；不幸的是，转换并非 100% 的发生。
• 功能的操作（Block Manipulation） - 没奢望能够构造发射 / 接收更改的功能模块，也无需删除它？（Ever wish that you could take a block out of your transmit/receive change, but not delete it? ）。功能模块具有使能 / 使无效（enabled / disabled）状态。缺省的，一个功能块是处于使能状态（enabled）。如若一个功能块处于“使无效”（disabled）状态的话，在流程图中它便处于无效灰白色（grayed out），它也会因此招致流程图确认器及代码生成器的冷遇。功能模块也能够被从一个流程图剪切（cut）、复制（copied）及粘贴（pasted）到另外一个流程图中。
• 阶梯形功能（Hierarchical Blocks） - GRC 能够基于内置功能模块来构建阶梯形功能模块。详情参阅 阶梯形功能模块 部分。

要求

GRC 的要求

在对应的 Linux 的版本管理器中便会发现下面这些大多数（非全部）的要求。

• [Python 2.5 (或更高版本) http://www.python.org/download/]
• [Python-LXML 2.0 (或更高版本)http://codespeak.net/lxml/installation.html]
• [Cheetah Template Engine 2.0 (或更高版本)http://www.cheetahtemplate.org/download.html]
• [Python-GTK 2.10 (或更高版本)http://www.pygtk.org/downloads.html]

GNU Radio 的要求

在 GNU Radio 版本 3.2 及以后的版本中 GRC 是一捆绑形式发行的。在此强烈建议，使用支持 wx-python, usrp, 及 audio 选项来配置 GNU Radio 的安装过程。尽管任何配置都是可行的，详细安装过程还是敬请参阅 创建指导 。

注：无论安装与否 GRC 都将会产生构建流程图所关联的所有的元素。举例来说，构建带有 USRP 信源（usrp source）的流程图。该流程图生产的代码在没有安装支持 USRP 的 GNU Radio 的环境中运行将会出错，除非运行在支持 USRP 的 GNU Radio 环境下。

GRC 安装

安装 GRC

GRC 是同 GNU Radio 捆绑发行的。因此延循安装指导是足以成功安装 GNU Radio。但是如若缺失任何必须的部件，GRC 的安装会导致失败。使用下面命令来安装任何缺失的部件及重启 configure/install: 

cmake ..
make
sudo make install

这时 GRC 理应处于被配置部件的清单上；如若意外，请仔细阅读配置来辨析错误所在。

安装文档

若想能够查看 GRC 内部的功能模块的文档，安装 doxygen 以及将 GNU Radio 配置成支持 doxygen 便是必须的:

./configure --enable-doxygen
make
sudo make install

Icons、Mime 类型、及 Menu 的安装

如果所运行的操作系统支持自由桌面标准（freedesktop.org standards）元素 (Gnome, KDE, XFCE)，或许需要安装同 GRC 绑定的 icons, mime type, 及 menu items，如若如此请运行如下命令：

cd <prefix>/libexec/gnuradio/
sudo grc_setup_freedesktop install

运行 Execution

GRC 通过将数个可被执行的 Python 文件安装到系统并将其配置到系统路径上来运行。

运行流程图编辑器（Flow Graph Editor）

打开终端窗口并键入：

gnuradio-companion

使用指南 - Usage Tips

• 添加功能模块：在功能模块选择窗口中双击某个功能块。
• 连接功能模块：点击一个功能模块的端口部分，便可将其同另外一个功能模块的端口相连。
• 去除连接部分：点击连接部分，然后选择删除，或者将连接部分拖之去除。- Remove a connection: click on the connection, press delete, or drag the connection to remove.
• 编辑模块参数：双击流程图中功能模块。
• 选择一个功能模块，然后通过向上或向下遍历便可进行类型变化。
• 更多快捷键的了解，请参阅菜单的热键。
• 运行处于完全仿真状态（也就是没有 audio 或者 usrp 模块）流程图将会占据 100% 的 CPU 资源，这是的 GUI 元素将会因为系统资源的枯竭而无法响应。预防这种情况，模块 Misc->Throttle 是流程图的必要模块，它的功用遏制数据流的流量作用的。

变量 - Variables

变量将符号名（symbolic name）映射为数值。在 GRC 中，一个变量可以用来定义全局常量，也可被用来协调 GUI 对例程图的控制及运行。

变量块 - Variable Block

使用变量形式的功能模块（变量块）是 GRC 使用变量的最基本表现形式。变量块的参数 ID 对应“符号名 - symbolic name”。 符号名必须是由字母和数字（也允许下划线）组成并以字母开头。使用变量（准确的说，变量功能块）的简单的方法是在其它功能块的参数中使用该变量的符号名便可。

变量控制 - Variable Controls

某些功能模块具有在运行流程图的同时更改自身参数功能的回呼方法（callback methods）。 GRC 的变量控制是指使用变量通过回呼方法修改自身参数。如果某个参数具有回呼方法，该参数便会在功能块属性的对话窗口（block-properties dialog）便强调。变量滑动条控件（variable slider）、变量文本框（variable text box）、及变量选择器功能模块（variable chooser block）便会提供一些图形小插件（graphical widgets）诸如滑动条控件（sliders）、文本框（text boxes）、按钮（buttons）、下拉框（drop downs）、及单选按钮（radio buttons）实施变量控制。除此之外，变量信宿功能模块采自源于 gnuradio 信号流并将该采样数据写入变量之中。

字符串赋值 -String Evaluation

字符串参数是通过二阶段赋值。首先，GRC 对其参数自然赋值。如果参数无法使用字符串数据类型被赋值或者赋值故障，便可以理解该参数内含引用（it is understood that the parameter had implied quotation）。在此 GRC 需要使用引号对该参数重新赋值；这样一来该参数所返回的字符串将严格依据参数窗口所规约的类型。String parameters have a two-phase evaluation. First, GRC evaluates the parameter as-is. If the parameter does not evaluate to a string data type or the evaluation fails, then it is understood that the parameter had implied quotation. In this case, GRC will evaluate the parameter again with quotation marks; which will return a string with the exact code that was typed into the parameter window.

使用字符串类型的变量，简单在参数区域键入变量的名称 parameter: my_var 。 如果该变量数据类型不是字符串，使用 python 的函数 str 对其进行类型转换：str(my_var)。标准 python 的字符串函数也适用于此："My Var = " + str(my_var). To use a variable inside a string simply type the name of the variable into the parameter: my_var. If the variable is not a string, cast the variable with python's str function: str(my_var). Standard python string functionality applies: "My Var = " + str(my_var).

注: 字符串参数类型也包括文件打开（file open）及文件存储（file save）。 

滤波器设计 - Filter Design

GNU Radio 的许多功能模块都接纳复数及实数阈值构成的数组作为其参数。它也提供了一个用于产生各种滤波器及窗口阈值的软件包。有关详细咨询请参阅： firdes package 。

FIR 滤波器设计中的阈值生成器 - Firdes Taps Generators

• low_pass(gain, samp_rate, cutoff_freq, width, [window], [beta])
• high_pass(gain, samp_rate, cutoff_freq, width, [window], [beta])
• band_pass(gain, samp_rate, low_cutoff_freq, high_cutoff_freq, width, [window], [beta])
• complex_band_pass(gain, samp_rate, low_cutoff_freq, high_cutoff_freq, width, [window], [beta])
• band_reject(gain, samp_rate, low_cutoff_freq, high_cutoff_freq, width, [window], [beta])
• gaussian(gain, spb, bt, int ntaps)
• hilbert(int ntaps, window, beta)
• root_raised_cosine(gain, samp_rate, symbol_rate, alpha, int ntaps)
• window(window, int ntaps, beta)

FIR 滤波器设计中所用到的窗口类型 - Firdes Window Types

• WIN_HAMMING
• WIN_HANN
• WIN_BLACKMAN
• WIN_RECTANGULAR
• WIN_KAISER

FIR 滤波器设计的一些注解 - Firdes Notes

对于带通功用而言，其缺省的窗口类型设定为 Hamming window。beta parameter 缺省为 6.76，它仅适用于 Kaiser window 。

FIR 滤波器设计的用法例解 - Firdes Usage Example

构建一个全新的可被导入（"import"）功能模块如下：

from gnuradio.gr import firdes

注：带有阈值参数（taps parameter）的大多数功能模块将被自动地从 firdes 模块中被导入（import）。仅在 firdes 不能被赋值时，才需使用该模块(You only need to use the import block when firdes will not evaluate)。

在滤波器的阈值参数中添加下面内容便可：

firdes.low_pass(1.0, samp_rate, 1000, 100, firdes.WIN_HAMMING)

使用基于文件格式存储的滤波器阈值 - Use Taps from a File

如果滤波器的阈值数组以文档格式被存储，并欲意于 GRC 中使用此文件：

首先，构建一个全新的可被导入（“import”）功能模块如下：

import numpy

其次，将下面参数添加到该滤波器功能模块的阈值参数中：

numpy.fromfile('taps file path', numpy.complex64)

这意味着将会将整个二进制格式的文件被全部读入，然后对其依据编译语法规则以 64 bytes 为基本单元将其描述或解析成为一个复数格式的阈值表现形式。想要将其解析成实数格式的阈值时，需使用 numpy.float32 。更多高级用法请参阅 numpy.fromfile 的帮助文档： 

Help on built-in function fromfile in numpy（用于 numpy 的 fromfile 的内含函数的帮助文档）: 

numpy.fromfile = fromfile(...)

fromfile(file=, dtype=float, count=-1, sep=_) -> array. 

Required arguments（所需的参数）: 

file -- open file object or string containing file name（所要打开的文档对象的名称或包含该文件名称的字符串）. 

Keyword arguments（主要参数）:

dtype -- type and order of the returned array (default float) -- 所返回数组（缺省 浮点型）的类型及顺序

count -- number of items to input (default all) -- 所需输入（缺省 全部）的内容的大小

sep -- separater between items if file is a text file (default "") -- 如果该文件的格式的文本格式（缺省 ""）的情况时，其用于隔离其基本单元的格式

该函数返回一组数组，它源自于文本或者二进制码的文档，并以给定的数据类型为格式。上面的参数 'file' 可以是一个打开的文件或包含需要读取的文件的名称的字符串。参数 'count' == -1 意味着整个文件将被读入，否则的话它将会定义以给定格式被读入的内容（数目）的大小。如果参数 'sep' 表现形式是 "" 时，它便使用 dtype 所规约的格式从二进制文档中读取数据，否则它便会对文本文档的元素之间给出分隔符。参数 'dtype' 用于确定所返回数组（二进制文档）元素的大小及顺序。Return an array of the given data type from a text or binary file. The 'file' argument can be an open file or a string with the name of a file to read from. If 'count' == -1 the entire file is read, otherwise count is the number of items of the given type to read in. If 'sep' is "" it means to read binary data from the file using the specified dtype, otherwise it gives the separator between elements in a text file. The 'dtype' value is also used to determine the size and order of the items in binary files.

网栅格的定位 - Grid Positioning

GRC 提供若干个图形信宿及构建 wx-gui 风格的流程图用的图形化控制构件（范围 - scope sink、FFT - fft sink、数目 - number sink、 瀑布图 - waterfall sink、 星云图 - constellation sink、 滑动窗口控件 - slider control, 及选择器控件 - chooser control）。这些图形元素都有栅格定位参数用于其精确定位。

栅格定位参数是以 4 个整数数组（行坐标, 列坐标, 行大小, 列大小）为单位的。行坐标和列坐标定义了该图形元素的左上角的定位坐标。最小数值的位置，（0，0），便是栅格的右上角。

If left blank, the grid parameter specifies that the graphical element will be automatically stacked into a vertical sizer. The vertical sizer is positioned directly above the grid sizer. If you do not want any elements to be added to the vertical sizer, leave no grid parameters blank.

行及列的大小描述网栅的延伸程度，或者图形元素可以延伸的行数及列数。行大小描述自网栅原点向下延伸的行数，列大小描述网栅向右延伸的列数。这种延伸必须以（1， 1）为单元占据最少一个栅格。

例子 - Example

用户

The user wishes to place a slider, centered directly above a graphical sink. The slider will be positioned at the 2nd column of the top row and with a column span of 2. The sink will be positioned on the 2nd row, and with a row span of 2 and a column span of 4. Notice the grid parameters below, and the resulting gui layout:

元素 - The Elements:

• Slider Control: (0, 1, 1, 2)
• Graphical Sink: (1, 0, 2, 4)

The Resulting GUI:

	0,0		0,1		0,2		0,3
	1,0		1,1		1,2		1,3
	2,0		2,1		2,2		2,3

 

阶梯形功能块 - Hierarchical Blocks

GRC can create hierarchical blocks out of the built-in blocks. Hierarchical blocks can be instantiated inside of other grc flow graphs. The python code generated from a hierarchical block can itself be used in non-GRC flow graphs. Four important blocks are used in the creation of a hierarchical block: The options block, parameter blocks, and the pad source and pad sink.

选项功能块 - The Options Block

In order to make a hierarchical block, the parameters in the options block must be set properly. The id of the options block sets the module name, and must be unique among the entire library of blocks (built-in and custom). The title parameter sets the display name for the block. The generate options must be set to "Hier Block". The category parameter sets the category for the new block. This category can be an existing category in the block selection window or a new category. Categories may be nested by specifying a name with slashes, ex: Custom/Filters. To put blocks into the root category, specify a single slash "/" (a blank category will hide your block).

参数功能块 - Parameter Blocks

Parameter blocks specify variables in your hierarchical block that should be configurable in the top level block. Parameter blocks work much like variable blocks with a few exceptions: Parameters blocks cannot depend on variable blocks or other parameter blocks. Parameter blocks have a label parameter for display purposes. Parameter blocks take the place of a variable block, do not try to create a variable block with the same id as your parameter block.

Pad Source and Sink Blocks

The pad source and sink blocks create inputs and outputs for the hierarchical block. The pad blocks have configurable data types, vector lengths, and number of ports. A flow graph can have at most, one pad source, and one pad sink. A hierarchical block may have one pad sink and no pad source or no pad sink and one pad source, but it must have at least one pad block.

生成及实例化 - Creating and Instantiating

• Start with a blank slate and create a new (empty) flow graph.
• Setup the options block as described above, with the id, title, generate options, and category.
• Add parameter blocks for all variables you wish to configure/control outside of the block.
• Create at most one pad source and one pad sink to match the IO type and connect them.
• When finished, click the generate button, and close/reopen GRC.
• The hierarchical block will appear in the block selection window.
• Add the hierarchical block to a flow graph as your would any other block.

注解 - Notes

• After making changes to your hierarchical block, make sure to regenerate, and reopen GRC before usage.
• The ID parameter of the block must be unique. If two blocks share the same ID, the last one to be generated will overwrite the other.
• Custom hierarchical blocks may instantiate other custom hierarchical blocks. Just don't have a block instantiate itself!

添加定制功能块 - Adding Custom Blocks

Every block in GRC corresponds to an XML file that describes the block's parameters, inputs, outputs, and other attributes. Adding a custom block into GRC is simply a matter of creating one of these XML block definition files. A few caveats:

The block should be accessible from the python path. Meaning that the block can be accessed via an import statement.

The block follows the block diagram model: it has parameters, inputs, and outputs. If the block requires some kind of listening thread, or special callback methods to move the data (as in the blks2 packet stuff), it cannot be used in GRC (unless this "special" functionality can be encapsulated into a block that is block-diagram-safe).

If GRC is missing a block definition for a block that is currently in the trunk, or one of the block definitions is missing functionality, please mail the list. The block definitions in the GRC trunk must stay in sync with the actual GNU Radio blocks.

XML 功能块定义文件的生成 - Creating the XML Block Definition

The best way to learn how to create the xml file is to learn by example. See the block definitions (source:grc/blocks) packaged with GRC, and read through a few files. Essentially, all block definitions are structured as follows:

<?xml version="1.0"?>
<block>
    <name>My Block Name</name>
    <key>my_package_my_block_ff</key>
        <category>Filters</category>
    <import>from gnuradio import my_package</import>
    <make>my_package.my_block_ff($param1, $param2)</make>
        <callback>set_param1($param1)</callback>
    <param>
        <name>Parameter 1</name>
        <key>param1</key>
        <type>real</type>
    </param>
    <param>
        <name>Parameter 2</name>
        <key>param2</key>
        <value>1</value>
        <type>int</type>
    </param>
    <sink>
        <name>in</name>
        <type>float</type>
    </sink>
    <source>
        <name>out</name>
        <type>float</type>
    </source>
        <source>
        <name>out</name>
        <type>float</type>
    </source>
</block>

• The example above will make a block with 2 parameters, 1 input, and 2 outputs.
• The ordering of the tags is important, if tags are not ordered properly, the block will fail validation. See [/trac/browser/gnuradio/trunk/grc/data/platforms/python/block.dtd block.dtd] for specifics.
• The name tags dictate the label text for the block, parameters, and ports.
• The key tags are unique identifiers, they may not contain spaces. The block key must be globally unique among all blocks in GRC. The parameter keys must be unique only within the block.
• The category tag is a unix-style path that represents the location of the block inside the block selection window. The path can be a new category (Custom), or represent a sub-category (Filters/Custom). To put a block into the root category, just use a single slash (/) for the root path.
• The import tag (there can be multiple) must be a valid python import statement to the module containing your block.
• The make tag contains the code necessary to construct your block. This code is essentially a cheetah template nested inside an xml tag. Upon code generation, the template performs a text substitution on the "quot; parameters. For more advanced capabilities, see thecheetah template documentation.
• The callback tag registers a set-method from your custom block. Once the set-method is registered, the set-method can be called at runtime when a variable is changed. There can be any number of callback tags, one for each set-method of your block. Or no callback tags if this is not applicable.
• For the param tags, the commonly used values for the type tags are: complex, real, int, complex_vector, real_vector, int_vector, string, and raw. The raw type allows any value to be used without performing type checking. The real type should be used for single and double precision floating point numbers. The int type should be used for longs, ints, shorts, and chars.
• The sink tag represents an input port, and the source tag represents an output port. The allowed values for the type tags are: complex, float, int, short, and byte. For ports with a vector length, specify a vlen tag after the type tag.

一些定义文件的例子 - Some Example Definitions

• Simple Example: "Complex to Real"source:grc/blocks/gr_complex_to_real.xml
• Multiple Callbacks: "Costas Loop"source:grc/blocks/gr_costas_loop_cc.xml
• Vlen Example: "Throttle"source:grc/blocks/gr_throttle.xml
• Advanced Make: "FFT"source:grc/blocks/gr_fft_vxx.xml

安装 XML 功能定义文件 - Installing the XML Block Definition

有诸多方式可以让 GRC 知悉最新生成的 xml 文件。下面是一些可选的途径之一 ...

方法1: Default Hier Block Location

Create the .xml file inside *~/.grc_gnuradio/ where ~ is your home directory. If the directory does not exist, create it: mkdir ~/.grc_gnuradio/

方法2: 配置文件

构建或者编辑 ~/.gnuradio/config.conf 然后添加下面内容：

[grc]
local_blocks_path=/path/to/my/blocks

The local_blocks_path can contain multiple paths separated by colons: local_blocks_path=/path/to/blocks1:/path/to/blocks2

方法 3: 环境变量

配置

Set the GRC_BLOCKS_PATH environment variable to a path that contains your custom block wrapper. The GRC_BLOCKS_PATH can contain multiple paths separated by colons: GRC_BLOCKS_PATH=/path/to/blocks1:/path/to/blocks2

特别感谢 - Special Thanks

• CER Technology Fellowship: initial funding
• A. Brinton Cooper: starting the project
• Patrick Mulligan: starting the project
• William R. Kenan Jr. Fund: usrp & computers
• Patrick Strasser: the GRC icon

截图 - Screen Shots

Screen Shots

Feel free to submit your own screen shots or flow graphs.

注：GNU Radio Companion（原文出处，翻译整理仅供参考!）