GNU Radio 3.6.3 C++ API
gri_control_loop.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2011 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 GRI_CONTROL_LOOP
24 #define GRI_CONTROL_LOOP
25 
26 #include <gr_core_api.h>
27 
29 {
30  protected:
31  float d_phase, d_freq;
32  float d_max_freq, d_min_freq;
33  float d_damping, d_loop_bw;
34  float d_alpha, d_beta;
35 
36  public:
37  gri_control_loop(float loop_bw, float max_freq, float min_freq);
38  virtual ~gri_control_loop();
39 
40  /*! \brief update the system gains from the loop bandwidth and damping factor
41  *
42  * This function updates the system gains based on the loop
43  * bandwidth and damping factor of the system.
44  * These two factors can be set separately through their own
45  * set functions.
46  */
47  void update_gains();
48 
49  /*! \brief update the system gains from the loop bandwidth and damping factor
50  *
51  * This function updates the system gains based on the loop
52  * bandwidth and damping factor of the system.
53  * These two factors can be set separately through their own
54  * set functions.
55  */
56  void advance_loop(float error);
57 
58  /*! \brief Keep the phase between -2pi and 2pi
59  *
60  * This function keeps the phase between -2pi and 2pi. If the phase
61  * is greater than 2pi by d, it wraps around to be -2pi+d; similarly if
62  * it is less than -2pi by d, it wraps around to 2pi-d.
63  *
64  * This function should be called after advance_loop to keep the phase
65  * in a good operating region. It is set as a separate method in case
66  * another way is desired as this is fairly heavy-handed.
67  */
68  void phase_wrap();
69 
70  /*! \brief Keep the frequency between d_min_freq and d_max_freq
71  *
72  * This function keeps the frequency between d_min_freq and d_max_freq.
73  * If the frequency is greater than d_max_freq, it is set to d_max_freq.
74  * If the frequency is less than d_min_freq, it is set to d_min_freq.
75  *
76  * This function should be called after advance_loop to keep the frequency
77  * in the specified region. It is set as a separate method in case
78  * another way is desired as this is fairly heavy-handed.
79  */
80  void frequency_limit();
81 
82  /*******************************************************************
83  SET FUNCTIONS
84  *******************************************************************/
85 
86  /*!
87  * \brief Set the loop bandwidth
88  *
89  * Set the loop filter's bandwidth to \p bw. This should be between
90  * 2*pi/200 and 2*pi/100 (in rads/samp). It must also be a positive
91  * number.
92  *
93  * When a new damping factor is set, the gains, alpha and beta, of the loop
94  * are recalculated by a call to update_gains().
95  *
96  * \param bw (float) new bandwidth
97  *
98  */
99  void set_loop_bandwidth(float bw);
100 
101  /*!
102  * \brief Set the loop damping factor
103  *
104  * Set the loop filter's damping factor to \p df. The damping factor
105  * should be sqrt(2)/2.0 for critically damped systems.
106  * Set it to anything else only if you know what you are doing. It must
107  * be a number between 0 and 1.
108  *
109  * When a new damping factor is set, the gains, alpha and beta, of the loop
110  * are recalculated by a call to update_gains().
111  *
112  * \param df (float) new damping factor
113  *
114  */
115  void set_damping_factor(float df);
116 
117  /*!
118  * \brief Set the loop gain alpha
119  *
120  * Set's the loop filter's alpha gain parameter.
121  *
122  * This value should really only be set by adjusting the loop bandwidth
123  * and damping factor.
124  *
125  * \param alpha (float) new alpha gain
126  *
127  */
128  void set_alpha(float alpha);
129 
130  /*!
131  * \brief Set the loop gain beta
132  *
133  * Set's the loop filter's beta gain parameter.
134  *
135  * This value should really only be set by adjusting the loop bandwidth
136  * and damping factor.
137  *
138  * \param beta (float) new beta gain
139  *
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 updated by the
147  * inner loop of the algorithm, it could be useful to manually initialize,
148  * set, or reset this under certain circumstances.
149  *
150  * \param freq (float) new frequency
151  *
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 updated by the
159  * inner loop of the algorithm, it could be useful to manually initialize,
160  * set, or reset this under certain circumstances.
161  *
162  * \param phase (float) new phase
163  *
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 #endif /* GRI_CONTROL_LOOP */