GNU Radio 3.7.2 C++ API
fll_band_edge_cc.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2009,2011,2012 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 3, 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., 51 Franklin Street,
20  * Boston, MA 02110-1301, USA.
21  */
22 
23 #ifndef INCLUDED_DIGITAL_FLL_BAND_EDGE_CC_H
24 #define INCLUDED_DIGITAL_FLL_BAND_EDGE_CC_H
25 
26 #include <gnuradio/digital/api.h>
27 #include <gnuradio/sync_block.h>
29 
30 namespace gr {
31  namespace digital {
32 
33  /*!
34  * \brief Frequency Lock Loop using band-edge filters
35  * \ingroup synchronizers_blk
36  *
37  * \details
38  * The frequency lock loop derives a band-edge filter that covers
39  * the upper and lower bandwidths of a digitally-modulated
40  * signal. The bandwidth range is determined by the excess
41  * bandwidth (e.g., rolloff factor) of the modulated signal. The
42  * placement in frequency of the band-edges is determined by the
43  * oversampling ratio (number of samples per symbol) and the
44  * excess bandwidth. The size of the filters should be fairly
45  * large so as to average over a number of symbols.
46  *
47  * The FLL works by filtering the upper and lower band edges into
48  * x_u(t) and x_l(t), respectively. These are combined to form
49  * cc(t) = x_u(t) + x_l(t) and ss(t) = x_u(t) - x_l(t). Combining
50  * these to form the signal e(t) = Re{cc(t) \\times ss(t)^*}
51  * (where ^* is the complex conjugate) provides an error signal at
52  * the DC term that is directly proportional to the carrier
53  * frequency. We then make a second-order loop using the error
54  * signal that is the running average of e(t).
55  *
56  * In practice, the above equation can be simplified by just
57  * comparing the absolute value squared of the output of both
58  * filters: abs(x_l(t))^2 - abs(x_u(t))^2 = norm(x_l(t)) -
59  * norm(x_u(t)).
60  *
61  * In theory, the band-edge filter is the derivative of the
62  * matched filter in frequency, (H_be(f) = frac{H(f)}{df}). In
63  * practice, this comes down to a quarter sine wave at the point
64  * of the matched filter's rolloff (if it's a raised-cosine, the
65  * derivative of a cosine is a sine). Extend this sine by another
66  * quarter wave to make a half wave around the band-edges is
67  * equivalent in time to the sum of two sinc functions. The
68  * baseband filter fot the band edges is therefore derived from
69  * this sum of sincs. The band edge filters are then just the
70  * baseband signal modulated to the correct place in
71  * frequency. All of these calculations are done in the
72  * 'design_filter' function.
73  *
74  * Note: We use FIR filters here because the filters have to have
75  * a flat phase response over the entire frequency range to allow
76  * their comparisons to be valid.
77  *
78  * It is very important that the band edge filters be the
79  * derivatives of the pulse shaping filter, and that they be
80  * linear phase. Otherwise, the variance of the error will be very
81  * large.
82  */
84  : virtual public sync_block,
85  virtual public blocks::control_loop
86  {
87  public:
88  // gr::digital::fll_band_edge_cc::sptr
90 
91  /*!
92  * Make an FLL block.
93  *
94  * \param samps_per_sym (float) number of samples per symbol
95  * \param rolloff (float) Rolloff (excess bandwidth) of signal filter
96  * \param filter_size (int) number of filter taps to generate
97  * \param bandwidth (float) Loop bandwidth
98  */
99  static sptr make(float samps_per_sym, float rolloff,
100  int filter_size, float bandwidth);
101 
102  /*******************************************************************
103  SET FUNCTIONS
104  *******************************************************************/
105 
106  /*!
107  * \brief Set the number of samples per symbol
108  *
109  * Set's the number of samples per symbol the system should
110  * use. This value is uesd to calculate the filter taps and will
111  * force a recalculation.
112  *
113  * \param sps (float) new samples per symbol
114  */
115  virtual void set_samples_per_symbol(float sps) = 0;
116 
117  /*!
118  * \brief Set the rolloff factor of the shaping filter
119  *
120  * This sets the rolloff factor that is used in the pulse
121  * shaping filter and is used to calculate the filter
122  * taps. Changing this will force a recalculation of the filter
123  * taps.
124  *
125  * This should be the same value that is used in the
126  * transmitter's pulse shaping filter. It must be between 0 and
127  * 1 and is usually between 0.2 and 0.5 (where 0.22 and 0.35 are
128  * commonly used values).
129  *
130  * \param rolloff (float) new shaping filter rolloff factor [0,1]
131  */
132  virtual void set_rolloff(float rolloff) = 0;
133 
134  /*!
135  * \brief Set the number of taps in the filter
136  *
137  * This sets the number of taps in the band-edge
138  * filters. Setting this will force a recalculation of the
139  * filter taps.
140  *
141  * This should be about the same number of taps used in the
142  * transmitter's shaping filter and also not very large. A large
143  * number of taps will result in a large delay between input and
144  * frequency estimation, and so will not be as accurate. Between
145  * 30 and 70 taps is usual.
146  *
147  * \param filter_size (float) number of taps in the filters
148  */
149  virtual void set_filter_size(int filter_size) = 0;
150 
151  /*******************************************************************
152  GET FUNCTIONS
153  *******************************************************************/
154 
155  /*!
156  * \brief Returns the number of sampler per symbol used for the filter
157  */
158  virtual float samples_per_symbol() const = 0;
159 
160  /*!
161  * \brief Returns the rolloff factor used for the filter
162  */
163  virtual float rolloff() const = 0;
164 
165  /*!
166  * \brief Returns the number of taps of the filter
167  */
168  virtual int filter_size() const = 0;
169 
170  /*!
171  * Print the taps to screen.
172  */
173  virtual void print_taps() = 0;
174  };
175 
176  } /* namespace digital */
177 } /* namespace gr */
178 
179 #endif /* INCLUDED_DIGITAL_FLL_BAND_EDGE_CC_H */
#define DIGITAL_API
Definition: gr-digital/include/gnuradio/digital/api.h:30
shared_ptr documentation stub
Definition: shared_ptr_docstub.h:15
boost::shared_ptr< fll_band_edge_cc > sptr
Definition: fll_band_edge_cc.h:89
synchronous 1:1 input to output with historyOverride work to provide the signal processing implementa...
Definition: sync_block.h:37
Frequency Lock Loop using band-edge filters.
Definition: fll_band_edge_cc.h:83
Definition: control_loop.h:31