Merged upstream from next

9 files changed, 476 insertions, 2 deletions

diff --git a/gnuradio-examples/Makefile.am b/gnuradio-examples/Makefile.am
index 9ea890c12..e0c1b1d15 100644
--- a/gnuradio-examples/Makefile.am
+++ b/gnuradio-examples/Makefile.am
@@ -25,3 +25,6 @@ SUBDIRS = c++
 if PYTHON
 SUBDIRS += python grc
 endif
+if GUILE
+SUBDIRS += waveforms
+endif
diff --git a/gnuradio-examples/python/apps/Makefile.am b/gnuradio-examples/python/apps/Makefile.am
index 620b9fd29..50fe75151 100644
--- a/gnuradio-examples/python/apps/Makefile.am
+++ b/gnuradio-examples/python/apps/Makefile.am
@@ -19,6 +19,8 @@
 # Boston, MA 02110-1301, USA.
 # 
 
+include $(top_srcdir)/Makefile.common
+
 SUBDIRS = hf_explorer hf_radio
-EXTRA_DIST = README
+EXTRA_DIST += README
 
diff --git a/gnuradio-examples/python/pfb/channelize.py b/gnuradio-examples/python/pfb/channelize.py
index 27d87e558..f845c05c6 100755
--- a/gnuradio-examples/python/pfb/channelize.py
+++ b/gnuradio-examples/python/pfb/channelize.py
@@ -36,7 +36,7 @@ class pfb_top_block(gr.top_block):
 
         # Create a set of taps for the PFB channelizer
         self._taps = gr.firdes.low_pass_2(1, self._fs, 475.50, 50, 
-                                          attenuation_dB=10, window=gr.firdes.WIN_BLACKMAN_hARRIS)
+                                          attenuation_dB=100, window=gr.firdes.WIN_BLACKMAN_hARRIS)
 
         # Calculate the number of taps per channel for our own information
         tpc = scipy.ceil(float(len(self._taps)) /  float(self._M))
diff --git a/gnuradio-examples/python/tags/test_file_tags.py b/gnuradio-examples/python/tags/test_file_tags.py
new file mode 100755
index 000000000..4ff4549ef
--- /dev/null
+++ b/gnuradio-examples/python/tags/test_file_tags.py
@@ -0,0 +1,29 @@
+#!/usr/bin/env python
+
+from gnuradio import gr
+import scipy
+
+def main():
+    data = scipy.arange(0, 32000, 1).tolist()
+    trig = 100*[0,] + 100*[1,]
+
+    src = gr.vector_source_s(data, True)
+    trigger = gr.vector_source_s(trig, True)
+
+    thr = gr.throttle(gr.sizeof_short, 10e3)
+    ann = gr.annotator_alltoall(1000000, gr.sizeof_short)
+    tagger = gr.burst_tagger(gr.sizeof_short)
+
+    fsnk = gr.tagged_file_sink(gr.sizeof_short, 1)
+
+    tb = gr.top_block()
+    tb.connect(src, thr, (tagger, 0))
+    tb.connect(trigger, (tagger, 1))
+    tb.connect(tagger, fsnk)
+
+    tb.run()
+
+if __name__ == "__main__":
+    main()
+
+    
diff --git a/gnuradio-examples/python/tags/uhd_burst_detector.py b/gnuradio-examples/python/tags/uhd_burst_detector.py
new file mode 100755
index 000000000..f8ebbe66a
--- /dev/null
+++ b/gnuradio-examples/python/tags/uhd_burst_detector.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python
+
+from gnuradio import eng_notation
+from gnuradio import gr
+from gnuradio import uhd
+from gnuradio import window
+from gnuradio.eng_option import eng_option
+from gnuradio.gr import firdes
+from optparse import OptionParser
+
+class uhd_burst_detector(gr.top_block):
+    def __init__(self, frequency, sample_rate,
+                 uhd_address="192.168.10.2", trigger=False):
+
+        gr.top_block.__init__(self)
+
+        self.freq = frequency
+        self.samp_rate = sample_rate
+        self.uhd_addr = uhd_address
+        self.gain = 32
+        self.trigger = trigger
+        
+        self.uhd_src = uhd.single_usrp_source(
+            device_addr=self.uhd_addr,
+            io_type=uhd.io_type_t.COMPLEX_FLOAT32,
+            num_channels=1,
+            )
+        
+        self.uhd_src.set_samp_rate(self.samp_rate)
+        self.uhd_src.set_center_freq(self.freq, 0)
+        self.uhd_src.set_gain(self.gain, 0)
+
+        taps = firdes.low_pass_2(1, 1, 0.4, 0.1, 60)
+        self.chanfilt = gr.fir_filter_ccc(10, taps)
+        self.ann0 = gr.annotator_alltoall(100000, gr.sizeof_gr_complex)
+        self.tagger = gr.burst_tagger(gr.sizeof_gr_complex)
+
+        # Dummy signaler to collect a burst on known periods
+        data = 1000*[0,] + 1000*[1,]
+        self.signal = gr.vector_source_s(data, True)
+
+        # Energy detector to get signal burst
+        self.c2m = gr.complex_to_mag_squared()
+        self.iir = gr.single_pole_iir_filter_ff(0.0001)
+        self.sub = gr.sub_ff()
+        self.mult = gr.multiply_const_ff(32768)
+        self.f2s = gr.float_to_short()
+        self.fsnk = gr.tagged_file_sink(gr.sizeof_gr_complex, self.samp_rate)
+        
+
+        ##################################################
+        # Connections
+        ##################################################
+        self.connect((self.uhd_src, 0), (self.tagger, 0))
+        self.connect((self.tagger, 0), (self.fsnk, 0))
+
+        if self.trigger:
+            # Connect a dummy signaler to the burst tagger
+            self.connect((self.signal, 0), (self.tagger, 1))
+
+        else:
+            # Connect an energy detector signaler to the burst tagger
+            self.connect((self.uhd_src, 0), (self.c2m, 0))
+            self.connect((self.c2m, 0), (self.sub, 0))
+            self.connect((self.c2m, 0), (self.iir, 0))
+            self.connect((self.iir, 0), (self.sub, 1))
+            self.connect((self.sub, 0), (self.mult,0))
+            self.connect((self.mult, 0), (self.f2s, 0))
+            self.connect((self.f2s, 0), (self.tagger, 1))
+        
+    def set_samp_rate(self, samp_rate):
+        self.samp_rate = samp_rate
+        self.wxgui_fftsink2_0.set_sample_rate(self.samp_rate/10)
+        self.uhd_src_0.set_samp_rate(self.samp_rate)
+            
+if __name__ == '__main__':
+    parser = OptionParser(option_class=eng_option, usage="%prog: [options]")
+    parser.add_option("-a", "--address", type="string", default="addr=192.168.10.2",
+                      help="select address of the device [default=%default]")
+    #parser.add_option("-A", "--antenna", default=None,
+    #                  help="select Rx Antenna (only on RFX-series boards)")
+    parser.add_option("-f", "--freq", type="eng_float", default=450e6,
+                      help="set frequency to FREQ", metavar="FREQ")
+    parser.add_option("-g", "--gain", type="eng_float", default=0,
+                      help="set gain in dB [default=%default]")
+    parser.add_option("-R", "--rate", type="eng_float", default=200000,
+                      help="set USRP sample rate [default=%default]")
+    parser.add_option("-T", "--trigger", action="store_true", default=False,
+                      help="Use internal trigger instead of detector [default=%default]")
+    (options, args) = parser.parse_args()
+    
+    frequency = options.freq
+    samp_rate = samp_rate = options.rate
+    uhd_addr = options.address
+    trigger = options.trigger
+
+    tb = uhd_burst_detector(frequency, samp_rate, uhd_addr, trigger)
+    tb.run()
diff --git a/gnuradio-examples/waveforms/.gitignore b/gnuradio-examples/waveforms/.gitignore
new file mode 100644
index 000000000..16c984055
--- /dev/null
+++ b/gnuradio-examples/waveforms/.gitignore
@@ -0,0 +1,6 @@
+/Makefile
+/Makefile.in
+/.deps
+/.libs
+/*.la
+/*.lo
diff --git a/gnuradio-examples/waveforms/Makefile.am b/gnuradio-examples/waveforms/Makefile.am
new file mode 100644
index 000000000..c07020a5c
--- /dev/null
+++ b/gnuradio-examples/waveforms/Makefile.am
@@ -0,0 +1,26 @@
+#
+# Copyright 2010 Free Software Foundation, Inc.
+#
+# This file is part of GNU Radio
+#
+# GNU Radio is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# GNU Radio is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+include $(top_srcdir)/Makefile.common
+
+ourdatadir = $(exampledir)/waveforms
+
+dist_ourdata_DATA = \
+	README \
+	dial-tone.wfd
diff --git a/gnuradio-examples/waveforms/README b/gnuradio-examples/waveforms/README
new file mode 100644
index 000000000..afaf1db73
--- /dev/null
+++ b/gnuradio-examples/waveforms/README
@@ -0,0 +1,270 @@
+#
+# Copyright 2010 Free Software Foundation, Inc.
+#
+# This file is part of GNU Radio
+#
+# GNU Radio is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# GNU Radio is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+Introduction
+------------
+
+This directory contains example "Waveform Description Files" that are
+designed to be loaded and run using the gr-run-waveform command.
+
+"Waveform Description Files" are written in an extended dialect of the
+Scheme language.  The dialect is "The Revised^5 Report on the
+Algorithmic Language Scheme" (R5RS)[1] as implemented and extended by
+Guile 1.8 [2], extended with the GNU Radio specific "define-waveform"
+macro and "gr-run-waveform" command.
+
+For those of you who may be unfamiliar with the Scheme language,
+it's a very simple high-level language defined by a brief 50 page
+specification[1].  Those 50 pages define the language, standard
+libraries and the formal semantics!
+
+For a quick tutorial introduction see the first 30 pages of "How to
+Teach Yourself Scheme in Fixnum Days"[3] (This covers a different
+Scheme dialect, but the first 30 pages or so are valid for Guile too.)
+
+Another text worth mentioning is "How To Design Programs"[4], a book
+on the systematic design of computer programs which utilizes Scheme.
+
+
+A Quick Walk-Through
+--------------------
+
+We'll use dial-tone.wfd as our example.
+
+Assuming that you've already built and installed GNU Radio, you can
+run dial-tone.wfd using:
+
+  $ gr-run-waveform <prefix>/share/gnuradio/examples/waveforms/dial-tone.wfd
+
+where <prefix> is the location where GNU Radio is installed, typically /usr/local.
+
+
+Here is dial-tone.wfd in its entirety:
+
+;; Start of dial-tone.wfd
+
+(use-modules (gnuradio audio_alsa))
+
+(define-waveform (dial-tone cmd-line-args)
+  (vars
+   (sample-rate 48000)
+   (ampl 0.1))
+
+  (blocks
+   (src0 (gr:sig-source-f sample-rate gr:GR-SIN-WAVE 350 ampl))
+   (src1 (gr:sig-source-f sample-rate gr:GR-SIN-WAVE 440 ampl))
+   (sink (gr:audio-alsa-sink sample-rate "plughw:0,0")))
+
+  (connections
+   (src0 (list sink 0))         ; src0 to left input
+   (src1 (list sink 1))))       ; src1 to right input
+
+;; End of dial-tone.wfd
+
+
+By default, waveforms have all of gnuradio-core available for their
+use.  This line:
+
+  (use-modules (gnuradio audio_alsa))
+
+imports the audio_alsa module, which we need for the audio sink.
+Unlike python, there's no gr.<foo> notation.  All names exported by
+the (gnuradio audio_alsa) module are made available in the current
+module.
+
+
+"define-waveform" is where the real work gets done.
+It has this general structure:
+
+(define-waveform (<waveform-name> cmd-line-args)
+  (vars
+   (<variable-name-1> <variable-value-1>)
+   ...)
+
+  (blocks
+   (<block-variable-name-1> <block-value-1>)
+   ...)
+
+  (connections
+   (<endpoint-1> ...)
+   ...))
+
+
+<waveform-name> is an identifier that names the waveform.
+
+Identifiers are similar to identifiers in other programming languages.
+They are a sequence of letters, digits and "extended alphabetic
+characters" that begins with a character that cannot begin a number.
+"extended alphabetic characters" include:
+
+          ! $ % & * + - . / : < = > ? @ ^ _ -
+
+By convention in Scheme and LISP, '-' is used in preference to '_' in identifiers.
+
+<variable-names> and <block-variable-names> name variables that store
+associated values, which may be any Scheme value.  (<block-variables>
+should contain only instances of GNU Radio blocks.)
+
+
+<variable-value-*> and <block-value-*> may be any valid Scheme expression.
+E.g., constants, nested function calls, bindings using "let", or
+lambda expressions.
+
+
+The (connections ...) section contains 0 or more lists of endpoints,
+specifying which endpoints are to be connected together.  In the
+general case, endpoints have both a block and a port number, though
+the port number defaults to zero if not specified.
+
+To specify a port number, create a two element list of the block and
+port number as illustrated above.
+
+Like the python implementation, more than a pair of endpoints can be
+strung together.   Assuming blk0, blk1 and blk2 are block variables,
+this would connect blk0, output 0, to blk1, input 0; blk1, output 0 to
+blk2, input 0:
+
+  (connect
+    (blk0 blk1 blk2))
+
+It could also be written like this:
+
+  (connect
+    (blk0 blk1)
+    (blk1 blk2))
+
+Or even more verbosely as:
+
+  (connect
+    ((list blk0 0) (list blk1 0))
+    ((list blk1 0) (list blk2 0)))
+
+And finally, using Scheme's quasiquote mechanism, this works too:
+
+  (connect
+    (`(,blk0 0) (,blk1 0))
+    (`(,blk1 0) (,blk2 0)))
+
+
+When gr-run-waveform loads the waveform file, it expands the
+define-waveform section into code that creates a GNU Radio top block,
+creates and initializes all variables and blocks specified in the
+respective sections and connects them together according the
+connections specifications.  Finally it runs the resulting GNU Radio
+flowgraph.
+
+
+Naming conventions (or what's my block called???!!!)
+----------------------------------------------------
+
+All GNU Radio block constructors as well as everything else wrapped
+for export by SWIG starts with a "gr:" prefix.  This is to avoid
+collisions with any built in Scheme procedures.
+
+All blocks contained in gnuradio-core are named like this:
+
+  C++ name           Python name         Guile name
+  --------           -----------         ----------
+  gr_head            gr.head             gr:head
+  gr_add_const_ff    gr.add_const_ff     gr:add-const-ff
+
+
+GNU Radio blocks in any other component besides gnuradio-core use a
+slightly different convention.  They also start with gr: but in
+addition include the component name after the gr:.  This is because
+Scheme implements its namespace differently than Python does.
+Thus:
+
+  C++ name           Python name         Guile name
+  --------           -----------         ----------
+  audio_alsa_sink    audio_alsa.sink     gr:audio-alsa-sink
+  audio_jack_sink    audio_jack.sink     gr:audio-jack-sink
+  usrp2_sink_32fc    usrp2.sink_32fc     gr:usrp2-sink-32fc
+
+
+Now, because we're working in Scheme and not C++ or Python, the
+calling of class methods (member functions) is different too.  SWIG
+converts C++ member functions into what are called "generic functions"
+using GOOPS[5], Guile's object oriented extension.  (For those familar
+with Common Lisp, GOOPS is very close in spirit to CLOS, the Common
+Lisp Object System, but adapted for the Scheme language.)
+
+Assuming "u2" is a variable holding an instance of a usrp2 sink,
+these all retrieve the current interpolation value:
+
+  C++                Python              Guile
+  --------           -----------         ----------
+  u2->interp()       u2.interp()         (gr:interp u2)
+
+
+Mapping of Guile types to/from C++
+----------------------------------
+
+The mapping is similar in flavor to the Python <-> C++ mapping
+
+  C++                Python              Guile
+  --------           -----------         ----------
+  true               True                #t
+  false              False               #f
+  "a string"         "a string"          "a string"
+  3.14159            3.14159             3.14159
+  gr_complex(1,-1)   1-1j                1-1i
+  vector<int>        (1, 2, 3)           #(1 2 3)
+  vector<float>      (1.0, 2.0, 3.0)     #(1.0 2.0 3.0)
+
+
+You can find examples of each block constructor being called by
+looking in the guile QA code contained in gnuradio-core/src/guile/tests/*.test
+The types and values passed are syntactically correct, but don't
+necessarily doing anything meaningful.
+
+
+gr-run-waveform vs gr-run-waveform-script vs gr-run-waveform-binary
+-------------------------------------------------------------------
+
+There are two implementations of gr-run-waveform:
+gr-run-waveform-script and gr-run-waveform-binary.  gr-run-waveform is
+symlinked to one of them, with preference to gr-run-waveform-binary if
+the gr-run-waveform component was built and installed.
+
+gr-run-waveform-script is contained in gnuradio-core and uses the
+system's Guile interpreter and assocated files to implement this
+functionality.
+
+gr-run-waveform-binary is built by the optional standalone component
+gr-run-waveform.  gr-run-waveform-binary is a C binary that requires
+only handful of shared libraries and a single data file.  To function
+it requires the main program: gr-run-waveform-binary; the GNU Radio
+C++ libraries: libgnuradio-*.so; the SWIG generated wrapper libraries:
+libguile-gnuradio-*.so; and one additional file:
+<prefix>/share/gnuradio/gr-run-waveform/filesystem.dat.
+
+The two programs run waveform files identically.  They differ only in
+the details of how they are implemented.
+
+
+References
+----------
+
+[1] http://www.schemers.org/Documents/Standards/R5RS/r5rs.pdf
+[2] http://www.gnu.org/software/guile/guile.html
+[3] html: http://www.ccs.neu.edu/home/dorai/t-y-scheme/t-y-scheme.html
+    pdf:  http://download.plt-scheme.org/doc/205/pdf/t-y-scheme.pdf
+[4] http://www.htdp.org/2003-09-26
+[5] http://www.gnu.org/software/guile/docs/goops/index.html
diff --git a/gnuradio-examples/waveforms/dial-tone.wfd b/gnuradio-examples/waveforms/dial-tone.wfd
new file mode 100644
index 000000000..5ab60075a
--- /dev/null
+++ b/gnuradio-examples/waveforms/dial-tone.wfd
@@ -0,0 +1,40 @@
+;;; Emacs, format this using -*-scheme-*- mode.
+;;;
+;;; Copyright 2010 Free Software Foundation, Inc.
+;;;
+;;; This file is part of GNU Radio
+;;;
+;;; GNU Radio is free software; you can redistribute it and/or modify
+;;; it under the terms of the GNU General Public License as published by
+;;; the Free Software Foundation; either version 3, or (at your option)
+;;; any later version.
+;;;
+;;; GNU Radio is distributed in the hope that it will be useful,
+;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;;; GNU General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+;;;
+
+;;; This example waveform outputs a signal to an audio_alsa_sink
+;;; that sounds like North American dial tone.
+
+(use-modules (gnuradio audio_alsa))
+
+
+(define-waveform (dial-tone cmd-line-args)
+  (vars
+   (sample-rate 48000)
+   (ampl 0.1))
+
+  (blocks
+   (src0 (gr:sig-source-f sample-rate gr:GR-SIN-WAVE 350 ampl))
+   (src1 (gr:sig-source-f sample-rate gr:GR-SIN-WAVE 440 ampl))
+   (sink (gr:audio-alsa-sink sample-rate "plughw:0,0"))
+   )
+
+  (connections
+   (src0 (list sink 0))		; src0 to left input
+   (src1 (list sink 1))))	; src1 to right input