GNU Radio 3.5.3.2 C++ API
gr_pfb_clock_sync_ccf.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2009,2010 Free Software Foundation, Inc.
00004  * 
00005  * This file is part of GNU Radio
00006  * 
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  * 
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  * 
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 
00024 #ifndef INCLUDED_GR_PFB_CLOCK_SYNC_CCF_H
00025 #define INCLUDED_GR_PFB_CLOCK_SYNC_CCF_H
00026 
00027 #include <gr_core_api.h>
00028 #include <gr_block.h>
00029 
00030 class gr_pfb_clock_sync_ccf;
00031 typedef boost::shared_ptr<gr_pfb_clock_sync_ccf> gr_pfb_clock_sync_ccf_sptr;
00032 GR_CORE_API gr_pfb_clock_sync_ccf_sptr gr_make_pfb_clock_sync_ccf (double sps, float loop_bw,
00033                                                        const std::vector<float> &taps,
00034                                                        unsigned int filter_size=32,
00035                                                        float init_phase=0,
00036                                                        float max_rate_deviation=1.5,
00037                                                        int osps=1);
00038 
00039 class gr_fir_ccf;
00040 
00041 /*!
00042  * \class gr_pfb_clock_sync_ccf
00043  *
00044  * \brief Timing synchronizer using polyphase filterbanks
00045  *
00046  * \ingroup filter_blk
00047  * \ingroup pfb_blk
00048  * 
00049  * This block performs timing synchronization for PAM signals by
00050  * minimizing the derivative of the filtered signal, which in turn
00051  * maximizes the SNR and minimizes ISI.
00052  *
00053  * This approach works by setting up two filterbanks; one filterbank
00054  * contains the signal's pulse shaping matched filter (such as a root
00055  * raised cosine filter), where each branch of the filterbank contains
00056  * a different phase of the filter.  The second filterbank contains
00057  * the derivatives of the filters in the first filterbank. Thinking of
00058  * this in the time domain, the first filterbank contains filters that
00059  * have a sinc shape to them. We want to align the output signal to be
00060  * sampled at exactly the peak of the sinc shape. The derivative of
00061  * the sinc contains a zero at the maximum point of the sinc (sinc(0)
00062  * = 1, sinc(0)' = 0).  Furthermore, the region around the zero point
00063  * is relatively linear. We make use of this fact to generate the
00064  * error signal.
00065  *
00066  * If the signal out of the derivative filters is d_i[n] for the ith
00067  * filter, and the output of the matched filter is x_i[n], we
00068  * calculate the error as: e[n] = (Re{x_i[n]} * Re{d_i[n]} +
00069  * Im{x_i[n]} * Im{d_i[n]}) / 2.0 This equation averages the error in
00070  * the real and imaginary parts. There are two reasons we multiply by
00071  * the signal itself. First, if the symbol could be positive or
00072  * negative going, but we want the error term to always tell us to go
00073  * in the same direction depending on which side of the zero point we
00074  * are on. The sign of x_i[n] adjusts the error term to do
00075  * this. Second, the magnitude of x_i[n] scales the error term
00076  * depending on the symbol's amplitude, so larger signals give us a
00077  * stronger error term because we have more confidence in that
00078  * symbol's value.  Using the magnitude of x_i[n] instead of just the
00079  * sign is especially good for signals with low SNR.
00080  *
00081  * The error signal, e[n], gives us a value proportional to how far
00082  * away from the zero point we are in the derivative signal. We want
00083  * to drive this value to zero, so we set up a second order loop. We
00084  * have two variables for this loop; d_k is the filter number in the
00085  * filterbank we are on and d_rate is the rate which we travel through
00086  * the filters in the steady state. That is, due to the natural clock
00087  * differences between the transmitter and receiver, d_rate represents
00088  * that difference and would traverse the filter phase paths to keep
00089  * the receiver locked. Thinking of this as a second-order PLL, the
00090  * d_rate is the frequency and d_k is the phase. So we update d_rate
00091  * and d_k using the standard loop equations based on two error
00092  * signals, d_alpha and d_beta.  We have these two values set based on
00093  * each other for a critically damped system, so in the block
00094  * constructor, we just ask for "gain," which is d_alpha while d_beta
00095  * is equal to (gain^2)/4.
00096  *
00097  * The block's parameters are:
00098  *
00099  * \li \p sps: The clock sync block needs to know the number of samples per
00100  * symbol, because it defaults to return a single point representing
00101  * the symbol. The sps can be any positive real number and does not
00102  * need to be an integer.
00103  *
00104  * \li \p loop_bw: The loop bandwidth is used to set the gain of the
00105  * inner control loop (see:
00106  * http://gnuradio.squarespace.com/blog/2011/8/13/control-loop-gain-values.html).
00107  * This should be set small (a value of around 2pi/100 is suggested in
00108  * that blog post as the step size for the number of radians around
00109  * the unit circle to move relative to the error).
00110  *
00111  * \li \p taps: One of the most important parameters for this block is
00112  * the taps of the filter. One of the benefits of this algorithm is
00113  * that you can put the matched filter in here as the taps, so you get
00114  * both the matched filter and sample timing correction in one go. So
00115  * create your normal matched filter. For a typical digital
00116  * modulation, this is a root raised cosine filter. The number of taps
00117  * of this filter is based on how long you expect the channel to be;
00118  * that is, how many symbols do you want to combine to get the current
00119  * symbols energy back (there's probably a better way of stating
00120  * that). It's usually 5 to 10 or so. That gives you your filter, but
00121  * now we need to think about it as a filter with different phase
00122  * profiles in each filter. So take this number of taps and multiply
00123  * it by the number of filters. This is the number you would use to
00124  * create your prototype filter. When you use this in the PFB
00125  * filerbank, it segments these taps into the filterbanks in such a
00126  * way that each bank now represents the filter at different phases,
00127  * equally spaced at 2pi/N, where N is the number of filters.
00128  *
00129  * \li \p filter_size (default=32): The number of filters can also be
00130  * set and defaults to 32. With 32 filters, you get a good enough
00131  * resolution in the phase to produce very small, almost unnoticeable,
00132  * ISI.  Going to 64 filters can reduce this more, but after that
00133  * there is very little gained for the extra complexity.
00134  *
00135  * \li \p init_phase (default=0): The initial phase is another
00136  * settable parameter and refers to the filter path the algorithm
00137  * initially looks at (i.e., d_k starts at init_phase). This value
00138  * defaults to zero, but it might be useful to start at a different
00139  * phase offset, such as the mid-point of the filters.
00140  *
00141  * \li \p max_rate_deviation (default=1.5): The next parameter is the
00142  * max_rate_devitation, which defaults to 1.5. This is how far we
00143  * allow d_rate to swing, positive or negative, from 0. Constraining
00144  * the rate can help keep the algorithm from walking too far away to
00145  * lock during times when there is no signal.
00146  *
00147  * \li \p osps (default=1): The osps is the number of output samples per symbol. By default,
00148  * the algorithm produces 1 sample per symbol, sampled at the exact
00149  * sample value. This osps value was added to better work with
00150  * equalizers, which do a better job of modeling the channel if they
00151  * have 2 samps/sym.
00152  */
00153 
00154 class GR_CORE_API gr_pfb_clock_sync_ccf : public gr_block
00155 {
00156  private:
00157   /*!
00158    * Build the polyphase filterbank timing synchronizer.
00159    * \param sps (double) The number of samples per symbol in the incoming signal
00160    * \param loop_bw (float) The bandwidth of the control loop; set's alpha and beta.
00161    * \param taps (vector<int>) The filter taps.
00162    * \param filter_size (uint) The number of filters in the filterbank (default = 32).
00163    * \param init_phase (float) The initial phase to look at, or which filter to start 
00164    *                           with (default = 0).
00165    * \param max_rate_deviation (float) Distance from 0 d_rate can get (default = 1.5).
00166    * \param osps (int) The number of output samples per symbol (default=1).
00167    *
00168    */
00169 
00170   friend GR_CORE_API gr_pfb_clock_sync_ccf_sptr gr_make_pfb_clock_sync_ccf (double sps, float loop_bw,
00171                                                                 const std::vector<float> &taps,
00172                                                                 unsigned int filter_size,
00173                                                                 float init_phase,
00174                                                                 float max_rate_deviation,
00175                                                                 int osps);
00176 
00177   bool                              d_updated;
00178   double                            d_sps;
00179   double                            d_sample_num;
00180   float                             d_loop_bw;
00181   float                             d_damping;
00182   float                             d_alpha;
00183   float                             d_beta;
00184 
00185   int                               d_nfilters;
00186   int                               d_taps_per_filter;
00187   std::vector<gr_fir_ccf*>          d_filters;
00188   std::vector<gr_fir_ccf*>          d_diff_filters;
00189   std::vector< std::vector<float> > d_taps;
00190   std::vector< std::vector<float> > d_dtaps;
00191 
00192   float                             d_k;
00193   float                             d_rate;
00194   float                             d_rate_i;
00195   float                             d_rate_f;
00196   float                             d_max_dev;
00197   int                               d_filtnum;
00198   int                               d_osps;
00199   float                             d_error;
00200   int                               d_out_idx;
00201   
00202   /*!
00203    * Build the polyphase filterbank timing synchronizer.
00204    */
00205   gr_pfb_clock_sync_ccf (double sps, float loop_bw,
00206                          const std::vector<float> &taps,
00207                          unsigned int filter_size,
00208                          float init_phase,
00209                          float max_rate_deviation,
00210                          int osps);
00211   
00212   void create_diff_taps(const std::vector<float> &newtaps,
00213                         std::vector<float> &difftaps);
00214 
00215 public:
00216   ~gr_pfb_clock_sync_ccf ();
00217 
00218   /*! \brief update the system gains from omega and eta
00219    *
00220    *  This function updates the system gains based on the loop
00221    *  bandwidth and damping factor of the system.
00222    *  These two factors can be set separately through their own
00223    *  set functions.
00224    */
00225   void update_gains();
00226   
00227   /*!
00228    * Resets the filterbank's filter taps with the new prototype filter
00229    */
00230   void set_taps (const std::vector<float> &taps,
00231                  std::vector< std::vector<float> > &ourtaps,
00232                  std::vector<gr_fir_ccf*> &ourfilter);
00233 
00234   /*!
00235    * Returns all of the taps of the matched filter
00236    */
00237   std::vector< std::vector<float> > get_taps();
00238 
00239   /*!
00240    * Returns all of the taps of the derivative filter
00241    */
00242   std::vector< std::vector<float> > get_diff_taps();
00243 
00244   /*!
00245    * Returns the taps of the matched filter for a particular channel
00246    */
00247   std::vector<float> get_channel_taps(int channel);
00248 
00249   /*!
00250    * Returns the taps in the derivative filter for a particular channel
00251    */
00252   std::vector<float> get_diff_channel_taps(int channel);
00253 
00254   /*!
00255    * Return the taps as a formatted string for printing
00256    */
00257   std::string get_taps_as_string();
00258 
00259   /*!
00260    * Return the derivative filter taps as a formatted string for printing
00261    */
00262   std::string get_diff_taps_as_string();
00263 
00264 
00265   /*******************************************************************
00266     SET FUNCTIONS
00267   *******************************************************************/
00268   
00269 
00270   /*!
00271    * \brief Set the loop bandwidth
00272    *
00273    * Set the loop filter's bandwidth to \p bw. This should be between 
00274    * 2*pi/200 and 2*pi/100  (in rads/samp). It must also be a positive
00275    * number.
00276    *
00277    * When a new damping factor is set, the gains, alpha and beta, of the loop
00278    * are recalculated by a call to update_gains().
00279    *
00280    * \param bw    (float) new bandwidth
00281    *
00282    */
00283   void set_loop_bandwidth(float bw);
00284 
00285   /*!
00286    * \brief Set the loop damping factor
00287    *
00288    * Set the loop filter's damping factor to \p df. The damping factor
00289    * should be sqrt(2)/2.0 for critically damped systems.
00290    * Set it to anything else only if you know what you are doing. It must
00291    * be a number between 0 and 1.
00292    *
00293    * When a new damping factor is set, the gains, alpha and beta, of the loop
00294    * are recalculated by a call to update_gains().
00295    *
00296    * \param df    (float) new damping factor
00297    *
00298    */
00299   void set_damping_factor(float df);
00300 
00301   /*!
00302    * \brief Set the loop gain alpha
00303    *
00304    * Set's the loop filter's alpha gain parameter.
00305    *
00306    * This value should really only be set by adjusting the loop bandwidth
00307    * and damping factor.
00308    *
00309    * \param alpha    (float) new alpha gain
00310    *
00311    */
00312   void set_alpha(float alpha);
00313 
00314   /*!
00315    * \brief Set the loop gain beta
00316    *
00317    * Set's the loop filter's beta gain parameter.
00318    *
00319    * This value should really only be set by adjusting the loop bandwidth
00320    * and damping factor.
00321    *
00322    * \param beta    (float) new beta gain
00323    *
00324    */
00325   void set_beta(float beta);
00326 
00327   /*!
00328    * Set the maximum deviation from 0 d_rate can have
00329    */  
00330   void set_max_rate_deviation(float m)
00331   {
00332     d_max_dev = m;
00333   }
00334   
00335   /*******************************************************************
00336     GET FUNCTIONS
00337   *******************************************************************/
00338 
00339   /*!
00340    * \brief Returns the loop bandwidth
00341    */
00342   float get_loop_bandwidth() const;
00343 
00344   /*!
00345    * \brief Returns the loop damping factor
00346    */
00347   float get_damping_factor() const;
00348 
00349   /*!
00350    * \brief Returns the loop gain alpha
00351    */
00352   float get_alpha() const;
00353 
00354   /*!
00355    * \brief Returns the loop gain beta
00356    */
00357   float get_beta() const;
00358 
00359   /*!
00360    * \brief Returns the current clock rate
00361    */
00362   float get_clock_rate() const;
00363 
00364   /*******************************************************************
00365   *******************************************************************/
00366 
00367   bool check_topology(int ninputs, int noutputs);
00368 
00369   int general_work (int noutput_items,
00370                     gr_vector_int &ninput_items,
00371                     gr_vector_const_void_star &input_items,
00372                     gr_vector_void_star &output_items);
00373 };
00374 
00375 #endif