GNU Radio 3.7.2.2 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 <
gnuradio/blocks/api.h
>
27
28
namespace
gr {
29
namespace
blocks {
30
31
/*!
32
* \brief A second-order control loop implementation class.
33
*
34
* \details
35
* This class implements a second order control loop and is
36
* inteded to act as a parent class to blocks which need a control
37
* loop (e.g., gr::digital::costas_loop_cc,
38
* gr::analog::pll_refout_cc, etc.). It takes in a loop bandwidth
39
* as well as a max and min frequency and provides the functions
40
* that control the update of the loop.
41
*
42
* The loop works of alpha and beta gains. These gains are
43
* calculated using the input loop bandwidth and a pre-set damping
44
* factor. The damping factor can be changed using the
45
* #set_damping_factor after the block is
46
* constructed. The alpha and beta values can be set using their
47
* respective #set_alpha or #set_beta functions if very precise
48
* control over these is required.
49
*
50
* The class tracks both phase and frequency of a signal based on
51
* an error signal. The error calculation is unique for each
52
* algorithm and is calculated externally and passed to the
53
* advance_loop function, which uses this to update its phase and
54
* frequency estimates.
55
*
56
* This class also provides the functions #phase_wrap and
57
* #frequency_limit to easily keep the phase and frequency
58
* estimates within our set bounds (phase_wrap keeps it within
59
* +/-2pi).
60
*/
61
class
BLOCKS_API
control_loop
62
{
63
protected
:
64
float
d_phase
, d_freq;
65
float
d_max_freq,
d_min_freq
;
66
float
d_damping,
d_loop_bw
;
67
float
d_alpha,
d_beta
;
68
69
public
:
70
control_loop
(
void
) {}
71
control_loop
(
float
loop_bw,
float
max_freq,
float
min_freq);
72
virtual
~
control_loop
();
73
74
/*! \brief Update the system gains from the loop bandwidth and damping factor.
75
*
76
* \details
77
* This function updates the system gains based on the loop
78
* bandwidth and damping factor of the system. These two
79
* factors can be set separately through their own set
80
* functions.
81
*/
82
void
update_gains();
83
84
/*! \brief Advance the control loop based on the current gain
85
* settings and the inputted error signal.
86
*/
87
void
advance_loop(
float
error);
88
89
/*! \brief Keep the phase between -2pi and 2pi.
90
*
91
* \details
92
* This function keeps the phase between -2pi and 2pi. If the
93
* phase is greater than 2pi by d, it wraps around to be -2pi+d;
94
* similarly if it is less than -2pi by d, it wraps around to
95
* 2pi-d.
96
*
97
* This function should be called after advance_loop to keep the
98
* phase in a good operating region. It is set as a separate
99
* method in case another way is desired as this is fairly
100
* heavy-handed.
101
*/
102
void
phase_wrap();
103
104
/*! \brief Keep the frequency between d_min_freq and d_max_freq.
105
*
106
* \details
107
* This function keeps the frequency between d_min_freq and
108
* d_max_freq. If the frequency is greater than d_max_freq, it
109
* is set to d_max_freq. If the frequency is less than
110
* d_min_freq, it is set to d_min_freq.
111
*
112
* This function should be called after advance_loop to keep the
113
* frequency in the specified region. It is set as a separate
114
* method in case another way is desired as this is fairly
115
* heavy-handed.
116
*/
117
void
frequency_limit();
118
119
/*******************************************************************
120
* SET FUNCTIONS
121
*******************************************************************/
122
123
/*!
124
* \brief Set the loop bandwidth.
125
*
126
* \details
127
* Set the loop filter's bandwidth to \p bw. This should be
128
* between 2*pi/200 and 2*pi/100 (in rads/samp). It must also be
129
* a positive number.
130
*
131
* When a new damping factor is set, the gains, alpha and beta,
132
* of the loop are recalculated by a call to update_gains().
133
*
134
* \param bw (float) new bandwidth
135
*/
136
virtual
void
set_loop_bandwidth(
float
bw);
137
138
/*!
139
* \brief Set the loop damping factor.
140
*
141
* \details
142
* Set the loop filter's damping factor to \p df. The damping
143
* factor should be sqrt(2)/2.0 for critically damped systems.
144
* Set it to anything else only if you know what you are
145
* doing. It must be a number between 0 and 1.
146
*
147
* When a new damping factor is set, the gains, alpha and beta,
148
* of the loop are recalculated by a call to update_gains().
149
*
150
* \param df (float) new damping factor
151
*/
152
void
set_damping_factor(
float
df);
153
154
/*!
155
* \brief Set the loop gain alpha.
156
*
157
* \details
158
* Sets the loop filter's alpha gain parameter.
159
*
160
* This value should really only be set by adjusting the loop
161
* bandwidth and damping factor.
162
*
163
* \param alpha (float) new alpha gain
164
*/
165
void
set_alpha(
float
alpha);
166
167
/*!
168
* \brief Set the loop gain beta.
169
*
170
* \details
171
* Sets the loop filter's beta gain parameter.
172
*
173
* This value should really only be set by adjusting the loop
174
* bandwidth and damping factor.
175
*
176
* \param beta (float) new beta gain
177
*/
178
void
set_beta(
float
beta);
179
180
/*!
181
* \brief Set the control loop's frequency.
182
*
183
* \details
184
* Sets the control loop's frequency. While this is normally
185
* updated by the inner loop of the algorithm, it could be
186
* useful to manually initialize, set, or reset this under
187
* certain circumstances.
188
*
189
* \param freq (float) new frequency
190
*/
191
void
set_frequency(
float
freq);
192
193
/*!
194
* \brief Set the control loop's phase.
195
*
196
* \details
197
* Sets the control loop's phase. While this is normally
198
* updated by the inner loop of the algorithm, it could be
199
* useful to manually initialize, set, or reset this under
200
* certain circumstances.
201
*
202
* \param phase (float) new phase
203
*/
204
void
set_phase(
float
phase);
205
206
/*!
207
* \brief Set the control loop's maximum frequency.
208
*
209
* \details
210
* Set the maximum frequency the control loop can track.
211
*
212
* \param freq (float) new max frequency
213
*/
214
void
set_max_freq(
float
freq);
215
216
/*!
217
* \brief Set the control loop's minimum frequency.
218
*
219
* \details
220
* Set the minimum frequency the control loop can track.
221
*
222
* \param freq (float) new min frequency
223
*/
224
void
set_min_freq(
float
freq);
225
226
/*******************************************************************
227
* GET FUNCTIONS
228
*******************************************************************/
229
230
/*!
231
* \brief Returns the loop bandwidth.
232
*/
233
float
get_loop_bandwidth()
const
;
234
235
/*!
236
* \brief Returns the loop damping factor.
237
*/
238
float
get_damping_factor()
const
;
239
240
/*!
241
* \brief Returns the loop gain alpha.
242
*/
243
float
get_alpha()
const
;
244
245
/*!
246
* \brief Returns the loop gain beta.
247
*/
248
float
get_beta()
const
;
249
250
/*!
251
* \brief Get the control loop's frequency estimate.
252
*/
253
float
get_frequency()
const
;
254
255
/*!
256
* \brief Get the control loop's phase estimate.
257
*/
258
float
get_phase()
const
;
259
260
/*!
261
* \brief Get the control loop's maximum frequency.
262
*/
263
float
get_max_freq()
const
;
264
265
/*!
266
* \brief Get the control loop's minimum frequency.
267
*/
268
float
get_min_freq()
const
;
269
};
270
271
}
/* namespace blocks */
272
}
/* namespace gr */
273
274
#endif
/* GR_BLOCKS_CONTROL_LOOP */
gnuradio
gr-blocks
include
gnuradio
blocks
control_loop.h
Generated by
1.8.3.1