GNU Radio 3.6.5.1 C++ API
control_loop.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2011,2013 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 GR_BLOCKS_CONTROL_LOOP
24 #define GR_BLOCKS_CONTROL_LOOP
25 
26 #include <blocks/api.h>
27 
28 namespace gr {
29  namespace blocks {
30 
32  {
33  protected:
34  float d_phase, d_freq;
35  float d_max_freq, d_min_freq;
36  float d_damping, d_loop_bw;
37  float d_alpha, d_beta;
38 
39  public:
40  control_loop(float loop_bw, float max_freq, float min_freq);
41  virtual ~control_loop();
42 
43  /*! \brief update the system gains from the loop bandwidth and damping factor
44  *
45  * This function updates the system gains based on the loop
46  * bandwidth and damping factor of the system. These two
47  * factors can be set separately through their own set
48  * functions.
49  */
50  void update_gains();
51 
52  /*! \brief Advance the control loop based on the current gain
53  * settings and the inputted error signal.
54  */
55  void advance_loop(float error);
56 
57  /*! \brief Keep the phase between -2pi and 2pi
58  *
59  * This function keeps the phase between -2pi and 2pi. If the
60  * phase is greater than 2pi by d, it wraps around to be -2pi+d;
61  * similarly if it is less than -2pi by d, it wraps around to
62  * 2pi-d.
63  *
64  * This function should be called after advance_loop to keep the
65  * phase in a good operating region. It is set as a separate
66  * method in case another way is desired as this is fairly
67  * heavy-handed.
68  */
69  void phase_wrap();
70 
71  /*! \brief Keep the frequency between d_min_freq and d_max_freq
72  *
73  * This function keeps the frequency between d_min_freq and
74  * d_max_freq. If the frequency is greater than d_max_freq, it
75  * is set to d_max_freq. If the frequency is less than
76  * d_min_freq, it is set to d_min_freq.
77  *
78  * This function should be called after advance_loop to keep the
79  * frequency in the specified region. It is set as a separate
80  * method in case another way is desired as this is fairly
81  * heavy-handed.
82  */
83  void frequency_limit();
84 
85  /*******************************************************************
86  * SET FUNCTIONS
87  *******************************************************************/
88 
89  /*!
90  * \brief Set the loop bandwidth
91  *
92  * Set the loop filter's bandwidth to \p bw. This should be
93  * between 2*pi/200 and 2*pi/100 (in rads/samp). It must also be
94  * a positive number.
95  *
96  * When a new damping factor is set, the gains, alpha and beta,
97  * of the loop are recalculated by a call to update_gains().
98  *
99  * \param bw (float) new bandwidth
100  */
101  void set_loop_bandwidth(float bw);
102 
103  /*!
104  * \brief Set the loop damping factor
105  *
106  * Set the loop filter's damping factor to \p df. The damping
107  * factor should be sqrt(2)/2.0 for critically damped systems.
108  * Set it to anything else only if you know what you are
109  * doing. It must be a number between 0 and 1.
110  *
111  * When a new damping factor is set, the gains, alpha and beta,
112  * of the loop are recalculated by a call to update_gains().
113  *
114  * \param df (float) new damping factor
115  */
116  void set_damping_factor(float df);
117 
118  /*!
119  * \brief Set the loop gain alpha
120  *
121  * Set's the loop filter's alpha gain parameter.
122  *
123  * This value should really only be set by adjusting the loop
124  * bandwidth and damping factor.
125  *
126  * \param alpha (float) new alpha gain
127  *
128  */
129  void set_alpha(float alpha);
130 
131  /*!
132  * \brief Set the loop gain beta
133  *
134  * Set's the loop filter's beta gain parameter.
135  *
136  * This value should really only be set by adjusting the loop
137  * bandwidth and damping factor.
138  *
139  * \param beta (float) new beta gain
140  */
141  void set_beta(float beta);
142 
143  /*!
144  * \brief Set the control loop's frequency.
145  *
146  * Set's the control loop's frequency. While this is normally
147  * updated by the inner loop of the algorithm, it could be
148  * useful to manually initialize, set, or reset this under
149  * certain circumstances.
150  *
151  * \param freq (float) new frequency
152  */
153  void set_frequency(float freq);
154 
155  /*!
156  * \brief Set the control loop's phase.
157  *
158  * Set's the control loop's phase. While this is normally
159  * updated by the inner loop of the algorithm, it could be
160  * useful to manually initialize, set, or reset this under
161  * certain circumstances.
162  *
163  * \param phase (float) new phase
164  */
165  void set_phase(float phase);
166 
167  /*!
168  * \brief Set the control loop's maximum frequency.
169  *
170  * Set the maximum frequency the control loop can track.
171  *
172  * \param freq (float) new max frequency
173  */
174  void set_max_freq(float freq);
175 
176  /*!
177  * \brief Set the control loop's minimum frequency.
178  *
179  * Set the minimum frequency the control loop can track.
180  *
181  * \param freq (float) new min frequency
182  */
183  void set_min_freq(float freq);
184 
185  /*******************************************************************
186  * GET FUNCTIONS
187  *******************************************************************/
188 
189  /*!
190  * \brief Returns the loop bandwidth
191  */
192  float get_loop_bandwidth() const;
193 
194  /*!
195  * \brief Returns the loop damping factor
196  */
197  float get_damping_factor() const;
198 
199  /*!
200  * \brief Returns the loop gain alpha
201  */
202  float get_alpha() const;
203 
204  /*!
205  * \brief Returns the loop gain beta
206  */
207  float get_beta() const;
208 
209  /*!
210  * \brief Get the control loop's frequency estimate
211  */
212  float get_frequency() const;
213 
214  /*!
215  * \brief Get the control loop's phase estimate
216  */
217  float get_phase() const;
218 
219  /*!
220  * \brief Get the control loop's maximum frequency.
221  */
222  float get_max_freq() const;
223 
224  /*!
225  * \brief Get the control loop's minimum frequency.
226  */
227  float get_min_freq() const;
228  };
229 
230  } /* namespace blocks */
231 } /* namespace gr */
232 
233 #endif /* GR_BLOCKS_CONTROL_LOOP */