How to Write a Signal Processing Block

Example 1. qa_howto.py (first version)

  1  #!/usr/bin/env python
  2  
  3  from gnuradio import gr, gr_unittest
  4  import howto
  5  
  6  class qa_howto (gr_unittest.TestCase):
  7  
  8      def setUp (self):
  9          self.fg = gr.flow_graph ()
 10  
 11      def tearDown (self):
 12          self.fg = None
 13  
 14      def test_001_square_ff (self):
 15          src_data = (-3, 4, -5.5, 2, 3)
 16          expected_result = (9, 16, 30.25, 4, 9)
 17          src = gr.vector_source_f (src_data)
 18          sqr = howto.square_ff ()
 19          dst = gr.vector_sink_f ()
 20          self.fg.connect (src, sqr)
 21          self.fg.connect (sqr, dst)
 22          self.fg.run ()
 23          result_data = dst.data ()
 24          self.assertFloatTuplesAlmostEqual (expected_result, result_data, 6)
 25          
 26  if __name__ == '__main__':
 27      gr_unittest.main ()

Example 2. gr_block.h

  1  /* -*- c++ -*- */
  2  /*
  3   * Copyright 2004 Free Software Foundation, Inc.
  4   * 
  5   * This file is part of GNU Radio
  6   * 
  7   * GNU Radio is free software; you can redistribute it and/or modify
  8   * it under the terms of the GNU General Public License as published by
  9   * the Free Software Foundation; either version 2, or (at your option)
 10   * any later version.
 11   * 
 12   * GNU Radio is distributed in the hope that it will be useful,
 13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
 14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 15   * GNU General Public License for more details.
 16   * 
 17   * You should have received a copy of the GNU General Public License
 18   * along with GNU Radio; see the file COPYING.  If not, write to
 19   * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 20   * Boston, MA 02111-1307, USA.
 21   */
 22  
 23  #ifndef INCLUDED_GR_BLOCK_H
 24  #define INCLUDED_GR_BLOCK_H
 25  
 26  #include <gr_runtime.h>
 27  #include <string>
 28  
 29  /*!
 30   * \brief The abstract base class for all signal processing blocks.
 31   * \ingroup block
 32   *
 33   * Blocks have a set of input streams and output streams.  The
 34   * input_signature and output_signature define the number of input
 35   * streams and output streams respectively, and the type of the data
 36   * items in each stream.
 37   *
 38   * Although blocks may consume data on each input stream at a
 39   * different rate, all outputs streams must produce data at the same
 40   * rate.  That rate may be different from any of the input rates.
 41   *
 42   * User derived blocks override two methods, forecast and general_work,
 43   * to implement their signal processing behavior. forecast is called
 44   * by the system scheduler to determine how many items are required on
 45   * each input stream in order to produce a given number of output
 46   * items.
 47   *
 48   * general_work is called to perform the signal processing in the block.
 49   * It reads the input items and writes the output items.
 50   */
 51  
 52  class gr_block {
 53  
 54   public:
 55    
 56    virtual ~gr_block ();
 57    
 58    std::string name () const { return d_name; }
 59    gr_io_signature_sptr input_signature () const  { return d_input_signature; }
 60    gr_io_signature_sptr output_signature () const { return d_output_signature; }
 61    long unique_id () const { return d_unique_id; }
 62  
 63    /*!
 64     * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)
 65     * History is the number of x_i's that are examined to produce one y_i.
 66     * This comes in handy for FIR filters, where we use history to
 67     * ensure that our input contains the appropriate "history" for the
 68     * filter.   History should be equal to the number of filter taps.
 69     */
 70    unsigned history () const { return d_history; }
 71    void  set_history (unsigned history) { d_history = history; }
 72    
 73    /*!
 74     * \brief return true if this block has a fixed input to output rate
 75     *
 76     * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
 77     */
 78    bool fixed_rate() const { return d_fixed_rate; }
 79  
 80    // ----------------------------------------------------------------
 81    //            override these to define your behavior
 82    // ----------------------------------------------------------------
 83  
 84    /*!
 85     * \brief  Estimate input requirements given output request
 86     *
 87     * \param noutput_items           number of output items to produce
 88     * \param ninput_items_required   number of input items required on each input stream
 89     *
 90     * Given a request to product \p noutput_items, estimate the number of
 91     * data items required on each input stream.  The estimate doesn't have
 92     * to be exact, but should be close.
 93     */
 94    virtual void forecast (int noutput_items,
 95                           gr_vector_int &ninput_items_required);
 96  
 97    /*!
 98     * \brief compute output items from input items
 99     *
100     * \param noutput_items       number of output items to write on each output stream
101     * \param ninput_items        number of input items available on each input stream
102     * \param input_items         vector of pointers to the input items, one entry per input stream
103     * \param output_items        vector of pointers to the output items, one entry per output stream
104     *
105     * \returns number of items actually written to each output stream, or -1 on EOF.
106     * It is OK to return a value less than noutput_items.  -1 <= return value <= noutput_items
107     *
108     * general_work must call consume or consume_each to indicate how many items
109     * were consumed on each input stream.
110     */
111    virtual int general_work (int noutput_items,
112                              gr_vector_int &ninput_items,
113                              gr_vector_const_void_star &input_items,
114                              gr_vector_void_star &output_items) = 0;
115  
116    /*!
117     * \brief Confirm that ninputs and noutputs is an acceptable combination.
118     *
119     * \param ninputs     number of input streams connected
120     * \param noutputs    number of output streams connected
121     *
122     * \returns true if this is a valid configuration for this block.
123     *
124     * This function is called by the runtime system whenever the
125     * topology changes.  Most classes do not need to override this.
126     * This check is in addition to the constraints specified by the input
127     * and output gr_io_signatures.
128     */
129    virtual bool check_topology (int ninputs, int noutputs);
130  
131    /*!
132     * \brief Called to enable drivers, etc for i/o devices.
133     *
134     * This allows a block to enable an associated driver to begin
135     * transfering data just before we start to execute the scheduler.
136     * The end result is that this reduces latency in the pipeline when
137     * dealing with audio devices, usrps, etc.
138     */
139    virtual bool start();
140  
141    /*!
142     * \brief Called to disable drivers, etc for i/o devices.
143     */
144    virtual bool stop();
145  
146    // ----------------------------------------------------------------
147  
148    /*!
149     * \brief Constrain the noutput_items argument passed to forecast and general_work
150     *
151     * set_output_multiple causes the scheduler to ensure that the noutput_items
152     * argument passed to forecast and general_work will be an integer multiple
153     * of \param multiple  The default value of output multiple is 1.
154     */
155    void set_output_multiple (int multiple);
156    int  output_multiple () const { return d_output_multiple; }
157  
158    /*!
159     * \brief Tell the scheduler \p how_many_items of input stream \p which_input were consumed.
160     */
161    void consume (int which_input, int how_many_items);
162  
163    /*!
164     * \brief Tell the scheduler \p how_many_items were consumed on each input stream.
165     */
166    void consume_each (int how_many_items);
167  
168    /*!
169     * \brief Set the approximate output rate / input rate
170     *
171     * Provide a hint to the buffer allocator and scheduler.
172     * The default relative_rate is 1.0
173     *
174     * decimators have relative_rates < 1.0
175     * interpolators have relative_rates > 1.0
176     */
177    void  set_relative_rate (double relative_rate);
178  
179    /*!
180     * \brief return the approximate output rate / input rate
181     */
182    double relative_rate () const { return d_relative_rate; }
183  
184    /*
185     * The following two methods provide special case info to the
186     * scheduler in the event that a block has a fixed input to output
187     * ratio.  gr_sync_block, gr_sync_decimator and gr_sync_interpolator
188     * override these.  If you're fixed rate, subclass one of those.
189     */
190    /*!
191     * \brief Given ninput samples, return number of output samples that will be produced.
192     * N.B. this is only defined if fixed_rate returns true.
193     * Generally speaking, you don't need to override this.
194     */
195    virtual int fixed_rate_ninput_to_noutput(int ninput);
196  
197    /*!
198     * \brief Given noutput samples, return number of input samples required to produce noutput.
199     * N.B. this is only defined if fixed_rate returns true.
200     * Generally speaking, you don't need to override this.
201     */
202    virtual int fixed_rate_noutput_to_ninput(int noutput);
203  
204    // ----------------------------------------------------------------------------
205  
206   private:
207  
208    std::string           d_name;
209    gr_io_signature_sptr  d_input_signature;
210    gr_io_signature_sptr  d_output_signature;
211    int                   d_output_multiple;
212    double                d_relative_rate;        // approx output_rate / input_rate
213    gr_block_detail_sptr  d_detail;               // implementation details
214    long                  d_unique_id;            // convenient for debugging
215    unsigned              d_history;
216    bool                  d_fixed_rate;
217  
218    
219   protected:
220  
221    gr_block (const std::string &name,
222              gr_io_signature_sptr input_signature,
223              gr_io_signature_sptr output_signature);
224  
225    //! may only be called during constructor
226    void set_input_signature (gr_io_signature_sptr iosig){
227      d_input_signature = iosig;
228    }
229  
230    //! may only be called during constructor
231    void set_output_signature (gr_io_signature_sptr iosig){
232      d_output_signature = iosig;
233    }
234  
235    void set_fixed_rate(bool fixed_rate){ d_fixed_rate = fixed_rate; }
236  
237    // These are really only for internal use, but leaving them public avoids
238    // having to work up an ever-varying list of friends
239  
240   public:
241    gr_block_detail_sptr detail () const { return d_detail; }
242    void set_detail (gr_block_detail_sptr detail) { d_detail = detail; }
243  };
244  
245  long gr_block_ncurrently_allocated ();
246  
247  #endif /* INCLUDED_GR_BLOCK_H */

Example 3. howto_square_ff.h

  1  /* -*- c++ -*- */
  2  /*
  3   * Copyright 2004 Free Software Foundation, Inc.
  4   * 
  5   * This file is part of GNU Radio
  6   * 
  7   * GNU Radio is free software; you can redistribute it and/or modify
  8   * it under the terms of the GNU General Public License as published by
  9   * the Free Software Foundation; either version 2, or (at your option)
 10   * any later version.
 11   * 
 12   * GNU Radio is distributed in the hope that it will be useful,
 13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
 14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 15   * GNU General Public License for more details.
 16   * 
 17   * You should have received a copy of the GNU General Public License
 18   * along with GNU Radio; see the file COPYING.  If not, write to
 19   * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 20   * Boston, MA 02111-1307, USA.
 21   */
 22  #ifndef INCLUDED_HOWTO_SQUARE_FF_H
 23  #define INCLUDED_HOWTO_SQUARE_FF_H
 24  
 25  #include <gr_block.h>
 26  
 27  class howto_square_ff;
 28  
 29  /*
 30   * We use boost::shared_ptr's instead of raw pointers for all access
 31   * to gr_blocks (and many other data structures).  The shared_ptr gets
 32   * us transparent reference counting, which greatly simplifies storage
 33   * management issues.  This is especially helpful in our hybrid
 34   * C++ / Python system.
 35   *
 36   * See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
 37   *
 38   * As a convention, the _sptr suffix indicates a boost::shared_ptr
 39   */
 40  typedef boost::shared_ptr<howto_square_ff> howto_square_ff_sptr;
 41  
 42  /*!
 43   * \brief Return a shared_ptr to a new instance of howto_square_ff.
 44   *
 45   * To avoid accidental use of raw pointers, howto_square_ff's
 46   * constructor is private.  howto_make_square_ff is the public
 47   * interface for creating new instances.
 48   */
 49  howto_square_ff_sptr howto_make_square_ff ();
 50  
 51  /*!
 52   * \brief square a stream of floats.
 53   * \ingroup block
 54   *
 55   * \sa howto_square2_ff for a version that subclasses gr_sync_block.
 56   */
 57  class howto_square_ff : public gr_block
 58  {
 59  private:
 60    // The friend declaration allows howto_make_square_ff to
 61    // access the private constructor.
 62  
 63    friend howto_square_ff_sptr howto_make_square_ff ();
 64  
 65    howto_square_ff ();   // private constructor
 66  
 67   public:
 68    ~howto_square_ff ();  // public destructor
 69  
 70    // Where all the action really happens
 71  
 72    int general_work (int noutput_items,
 73                      gr_vector_int &ninput_items,
 74                      gr_vector_const_void_star &input_items,
 75                      gr_vector_void_star &output_items);
 76  };
 77  
 78  #endif /* INCLUDED_HOWTO_SQUARE_FF_H */

Example 4. howto_square_ff.cc

  1  /* -*- c++ -*- */
  2  /*
  3   * Copyright 2004 Free Software Foundation, Inc.
  4   * 
  5   * This file is part of GNU Radio
  6   * 
  7   * GNU Radio is free software; you can redistribute it and/or modify
  8   * it under the terms of the GNU General Public License as published by
  9   * the Free Software Foundation; either version 2, or (at your option)
 10   * any later version.
 11   * 
 12   * GNU Radio is distributed in the hope that it will be useful,
 13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
 14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 15   * GNU General Public License for more details.
 16   * 
 17   * You should have received a copy of the GNU General Public License
 18   * along with GNU Radio; see the file COPYING.  If not, write to
 19   * the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 20   * Boston, MA 02111-1307, USA.
 21   */
 22  
 23  /*
 24   * config.h is generated by configure.  It contains the results
 25   * of probing for features, options etc.  It should be the first
 26   * file included in your .cc file.
 27   */
 28  #ifdef HAVE_CONFIG_H
 29  #include "config.h"
 30  #endif
 31  
 32  #include <howto_square_ff.h>
 33  #include <gr_io_signature.h>
 34  
 35  /*
 36   * Create a new instance of howto_square_ff and return
 37   * a boost shared_ptr.  This is effectively the public constructor.
 38   */
 39  howto_square_ff_sptr 
 40  howto_make_square_ff ()
 41  {
 42    return howto_square_ff_sptr (new howto_square_ff ());
 43  }
 44  
 45  /*
 46   * Specify constraints on number of input and output streams.
 47   * This info is used to construct the input and output signatures
 48   * (2nd & 3rd args to gr_block's constructor).  The input and
 49   * output signatures are used by the runtime system to
 50   * check that a valid number and type of inputs and outputs
 51   * are connected to this block.  In this case, we accept
 52   * only 1 input and 1 output.
 53   */
 54  static const int MIN_IN = 1;    // mininum number of input streams
 55  static const int MAX_IN = 1;    // maximum number of input streams
 56  static const int MIN_OUT = 1;   // minimum number of output streams
 57  static const int MAX_OUT = 1;   // maximum number of output streams
 58  
 59  /*
 60   * The private constructor
 61   */
 62  howto_square_ff::howto_square_ff ()
 63    : gr_block ("square_ff",
 64                gr_make_io_signature (MIN_IN, MAX_IN, sizeof (float)),
 65                gr_make_io_signature (MIN_OUT, MAX_OUT, sizeof (float)))
 66  {
 67    // nothing else required in this example
 68  }
 69  
 70  /*
 71   * Our virtual destructor.
 72   */
 73  howto_square_ff::~howto_square_ff ()
 74  {
 75    // nothing else required in this example
 76  }
 77  
 78  int 
 79  howto_square_ff::general_work (int noutput_items,
 80                                 gr_vector_int &ninput_items,
 81                                 gr_vector_const_void_star &input_items,
 82                                 gr_vector_void_star &output_items)
 83  {
 84    const float *in = (const float *) input_items[0];
 85    float *out = (float *) output_items[0];
 86  
 87    for (int i = 0; i < noutput_items; i++){
 88      out[i] = in[i] * in[i];
 89    }
 90  
 91    // Tell runtime system how many input items we consumed on
 92    // each input stream.
 93  
 94    consume_each (noutput_items);
 95  
 96    // Tell runtime system how many output items we produced.
 97    return noutput_items;
 98  }

Example 5. src/lib/Makefile.am (no SWIG)

  1  include $(top_srcdir)/Makefile.common
  2  
  3  # Install this stuff so that it ends up as the gnuradio.howto module
  4  # This usually ends up at:
  5  #   ${prefix}/lib/python${python_version}/site-packages/gnuradio
  6  
  7  ourpythondir = $(grpythondir)
  8  ourlibdir    = $(grpyexecdir)
  9  
 10  INCLUDES = $(STD_DEFINES_AND_INCLUDES) $(PYTHON_CPPFLAGS)
 11  
 12  ourlib_LTLIBRARIES = _howto.la
 13  
 14  # These are the source files that go into the shared library
 15  _howto_la_SOURCES =                     \
 16          howto_square_ff.cc              
 17  
 18  # magic flags
 19  _howto_la_LDFLAGS = -module -avoid-version
 20  
 21  # These headers get installed in ${prefix}/include/gnuradio
 22  grinclude_HEADERS =                     \
 23          howto_square_ff.h               
 24  
 25  MOSTLYCLEANFILES = $(BUILT_SOURCES) *.pyc

Example 6. src/lib/Makefile.am (with SWIG)

  1  #
  2  # Copyright 2004 Free Software Foundation, Inc.
  3  # 
  4  # This file is part of GNU Radio
  5  # 
  6  # GNU Radio is free software; you can redistribute it and/or modify
  7  # it under the terms of the GNU General Public License as published by
  8  # the Free Software Foundation; either version 2, or (at your option)
  9  # any later version.
 10  # 
 11  # GNU Radio is distributed in the hope that it will be useful,
 12  # but WITHOUT ANY WARRANTY; without even the implied warranty of
 13  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 14  # GNU General Public License for more details.
 15  # 
 16  # You should have received a copy of the GNU General Public License
 17  # along with GNU Radio; see the file COPYING.  If not, write to
 18  # the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 19  # Boston, MA 02111-1307, USA.
 20  # 
 21  
 22  include $(top_srcdir)/Makefile.common
 23  
 24  # Install this stuff so that it ends up as the gnuradio.howto module
 25  # This usually ends up at:
 26  #   ${prefix}/lib/python${python_version}/site-packages/gnuradio
 27  
 28  ourpythondir = $(grpythondir)
 29  ourlibdir    = $(grpyexecdir)
 30  
 31  INCLUDES = $(STD_DEFINES_AND_INCLUDES) $(PYTHON_CPPFLAGS)
 32  
 33  SWIGCPPPYTHONARGS = -noruntime -c++ -python $(PYTHON_CPPFLAGS) \
 34          -I$(swigincludedir) -I$(grincludedir)
 35  
 36  ALL_IFILES =                            \
 37          $(LOCAL_IFILES)                 \
 38          $(NON_LOCAL_IFILES)             
 39  
 40  NON_LOCAL_IFILES =                      \
 41          $(GNURADIO_CORE_INCLUDEDIR)/swig/gnuradio.i
 42  
 43  
 44  LOCAL_IFILES =                          \
 45          howto.i                         
 46  
 47  # These files are built by SWIG.  The first is the C++ glue.
 48  # The second is the python wrapper that loads the _howto shared library
 49  # and knows how to call our extensions.
 50  
 51  BUILT_SOURCES =                         \
 52          howto.cc                        \
 53          howto.py                                
 54  
 55  # This gets howto.py installed in the right place
 56  ourpython_PYTHON =                      \
 57          howto.py
 58  
 59  ourlib_LTLIBRARIES = _howto.la
 60  
 61  # These are the source files that go into the shared library
 62  _howto_la_SOURCES =                     \
 63          howto.cc                        \
 64          howto_square_ff.cc              
 65  
 66  # magic flags
 67  _howto_la_LDFLAGS = -module -avoid-version
 68  
 69  # link the library against some comon swig runtime code and the 
 70  # c++ standard library
 71  _howto_la_LIBADD =                      \
 72          -lgrswigrunpy                   \
 73          -lstdc++                        
 74  
 75  howto.cc howto.py: howto.i $(ALL_IFILES)
 76          $(SWIG) $(SWIGCPPPYTHONARGS) -module howto -o howto.cc $<
 77  
 78  # These headers get installed in ${prefix}/include/gnuradio
 79  grinclude_HEADERS =                     \
 80          howto_square_ff.h               
 81  
 82  # These swig headers get installed in ${prefix}/include/gnuradio/swig
 83  swiginclude_HEADERS =                   \
 84          $(LOCAL_IFILES)
 85  
 86  MOSTLYCLEANFILES = $(BUILT_SOURCES) *.pyc