GNU Radio Manual and C++ API Reference 3.8.5.0
The Free & Open Software Radio Ecosystem
 
Loading...
Searching...
No Matches
symbol_sync_cc.h
Go to the documentation of this file.
1/* -*- c++ -*- */
2/*
3 * Copyright (C) 2017 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_SYMBOL_SYNC_CC_H
24#define INCLUDED_DIGITAL_SYMBOL_SYNC_CC_H
25
26#include <gnuradio/block.h>
31
32namespace gr {
33namespace digital {
34
35/*!
36 * \brief Symbol Synchronizer block with complex input, complex output.
37 * \ingroup synchronizers_blk
38 *
39 * \details
40 * This implements a discrete-time error-tracking synchronizer.
41 *
42 * For this block to work properly, the input stream must meet the
43 * following requirements:
44 *
45 * 1. if not using the PFB Matched Filter interpolator, and using
46 * a non-CPM timing error detector, the input pulses must have peaks
47 * (not flat), which usually can be implemented by using a matched
48 * filter before this block.
49 *
50 * 2. for decision directed timing error detectors, the input pulses
51 * should nominally match the normalized slicer constellation, which
52 * is normalized to an average symbol magnitude of 1.0 over the entire
53 * constellation.
54 */
55class DIGITAL_API symbol_sync_cc : virtual public block
56{
57public:
58 // gr::digital::symbol_sync_cc::sptr
59 typedef boost::shared_ptr<symbol_sync_cc> sptr;
60
61 /*!
62 * Make a Symbol Synchronizer block.
63 *
64 * \details
65 * This implements a discrete-time error-tracking synchronizer.
66 *
67 * For this block to work properly, the input stream must meet the
68 * following requirements:
69 *
70 * 1. if not using the PFB Matched Filter interpolator, and using
71 * a non-CPM timing error detector, the input pulses must have peaks
72 * (not flat), which usually can be implemented by using a matched
73 * filter before this block.
74 *
75 * 2. for decision directed timing error detectors, the input pulses
76 * should nominally match the normalized slicer constellation, which
77 * is normalized to an average symbol magnitude of 1.0 over the entire
78 * constellation.
79 *
80 * \param detector_type
81 * The enumerated type of timing error detector to use.
82 * See enum ted_type for a list of possible types.
83 *
84 * \param sps
85 * User specified nominal clock period in samples per symbol.
86 *
87 * \param loop_bw
88 * Approximate normailzed loop bandwidth of the symbol clock tracking
89 * loop. It should nominally be close to 0, but greater than 0. If
90 * unsure, start with a number around 2*pi*0.040, and experiment to find
91 * the value that works best for your situation.
92 *
93 * \param damping_factor
94 * Damping factor of the symbol clock tracking loop.
95 * Damping < 1.0f is an under-damped loop.
96 * Damping = 1.0f/sqrt(2.0f) is a maximally flat loop response.
97 * Damping = 1.0f is a critically-damped loop.
98 * Damping > 1.0f is an over-damped loop.
99 *
100 * \param ted_gain
101 * Expected gain of the timing error detector, given the TED in use
102 * and the anticipated input amplitude, pulse shape, and Es/No.
103 * This value is the slope of the TED's S-curve at timing offset tau = 0.
104 * This value is normally computed by the user analytically or by
105 * simulation in a tool outside of GNURadio.
106 * This value must be correct for the loop filter gains to be computed
107 * properly from the desired input loop bandwidth and damping factor.
108 *
109 * \param max_deviation
110 * Maximum absolute deviation of the average clock period estimate
111 * from the user specified nominal clock period in samples per symbol.
112 *
113 * \param osps
114 * The number of output samples per symbol (default=1).
115 *
116 * \param slicer
117 * A constellation obj shared pointer that will be used by
118 * decision directed timing error detectors to make decisions.
119 * I.e. the timing error detector will use this constellation
120 * as a slicer, if the particular algorithm needs sliced
121 * symbols.
122 *
123 * \param interp_type
124 * The enumerated type of interpolating resampler to use.
125 * See the interpolating resampler type enum for a list of possible types.
126 *
127 * \param n_filters
128 * The number of arms in the polyphase filterbank of the interpolating
129 * resampler, if using an interpolating resampler that uses a PFB.
130 *
131 * \param taps
132 * The prototype filter for the polyphase filterbank of the interpolating
133 * resampler, if using an interpolating resampler that uses a PFB.
134 */
135 static sptr make(enum ted_type detector_type,
136 float sps,
137 float loop_bw,
138 float damping_factor = 1.0f,
139 float ted_gain = 1.0f,
140 float max_deviation = 1.5f,
141 int osps = 1,
142 constellation_sptr slicer = constellation_sptr(),
143 ir_type interp_type = IR_MMSE_8TAP,
144 int n_filters = 128,
145 const std::vector<float>& taps = std::vector<float>());
146
147 /*!
148 * \brief Returns the normalized approximate loop bandwidth.
149 *
150 * \details
151 * See the documentation for set_loop_bandwidth() for more details.
152 *
153 * Note that if set_alpha() or set_beta() were called to directly
154 * set gains, the value returned by this method will be inaccurate/stale.
155 */
156 virtual float loop_bandwidth() const = 0;
157
158 /*!
159 * \brief Returns the loop damping factor.
160 *
161 * \details
162 * See the documentation for set_damping_factor() for more details.
163 *
164 * Note that if set_alpha() or set_beta() were called to directly
165 * set gains, the value returned by this method will be inaccurate/stale.
166 */
167 virtual float damping_factor() const = 0;
168
169 /*!
170 * \brief Returns the user provided expected gain of the Timing Error
171 * Detector.
172 *
173 * \details
174 * See the documentation for set_ted_gain() for more details.
175 */
176 virtual float ted_gain() const = 0;
177
178 /*!
179 * \brief Returns the PI filter proportional gain, alpha.
180 *
181 * \details
182 * See the documentation for set_alpha() for more details.
183 */
184 virtual float alpha() const = 0;
185
186 /*!
187 * \brief Returns the PI filter integral gain, beta.
188 *
189 * \details
190 * See the documentation for set_beta() for more details.
191 */
192 virtual float beta() const = 0;
193
194 /*!
195 * \brief Set the normalized approximate loop bandwidth.
196 *
197 * \details
198 * Set the normalized approximate loop bandwidth.
199 * Useful values are usually close to 0.0, e.g. 2*pi*0.045.
200 *
201 * It should be a small positive number, corresponding to the normalized
202 * natural radian frequency of the loop as digital low-pass filter that is
203 * filtering the clock phase/timing error.
204 *
205 * Technically this parameter corresponds to the natural radian frequency
206 * of the 2nd order loop transfer function (scaled by Fs),
207 * which is the radius of the pole locations in the s-plane of an
208 * underdamped analog 2nd order system.
209 *
210 * The input parameter corresponds to omega_n_norm in the following
211 * relation:
212 *
213 * omega_n_norm = omega_n*T = 2*pi*f_n*T = 2*pi*f_n_norm
214 *
215 * where T is the period of the clock being estimated by this
216 * clock tracking loop, and omega_n is the natural radian frequency
217 * of the 2nd order loop transfer function.
218 *
219 * When a new loop bandwidth is set, the gains, alpha and beta,
220 * of the loop are automatically recalculated.
221 *
222 * \param omega_n_norm normalized approximate loop bandwidth
223 */
224 virtual void set_loop_bandwidth(float omega_n_norm) = 0;
225
226 /*!
227 * \brief Set the loop damping factor.
228 *
229 * \details
230 * Set the damping factor of the loop.
231 * Damping in the range (0.0, 1.0) yields an under-damped loop.
232 * Damping in the range (1.0, Inf) yields an over-damped loop.
233 * Damping equal to 1.0 yields a crtically-damped loop.
234 * Damping equal to 1.0/sqrt(2.0) yields a maximally flat
235 * loop filter response.
236 *
237 * Damping factor of the 2nd order loop transfer function.
238 * When a new damping factor is set, the gains, alpha and beta,
239 * of the loop are automatically recalculated.
240 *
241 * \param zeta loop damping factor
242 */
243 virtual void set_damping_factor(float zeta) = 0;
244
245 /*!
246 * \brief Set the expected gain of the Timing Error Detector.
247 *
248 * \details
249 * Sets the expected gain of the timing error detector, given the TED in
250 * use and the anticipated input amplitude, pulse shape, and Es/No.
251 * This value is the slope of the TED's S-curve at timing offset tau = 0.
252 * This value is normally computed by the user analytically or by
253 * simulation in a tool outside of GNURadio.
254 * This value must be correct for the loop filter gains to be computed
255 * properly from the desired input loop bandwidth and damping factor.
256 *
257 * When a new ted_gain is set, the gains, alpha and beta,
258 * of the loop are automatically recalculated.
259 *
260 * \param ted_gain expected gain of the timing error detector
261 */
262 virtual void set_ted_gain(float ted_gain) = 0;
263
264 /*!
265 * \brief Set the PI filter proportional gain, alpha.
266 *
267 * \details
268 * Sets the PI filter proportional gain, alpha.
269 * This gain directly mutliplies the clock phase/timing error
270 * term in the PI filter when advancing the loop.
271 * It most directly affects the instantaneous clock period estimate,
272 * T_inst, and instantaneous clock phase estimate, tau.
273 *
274 * This value would normally be adjusted by setting the loop
275 * bandwidth and damping factor. However,
276 * it can be set here directly if desired.
277 *
278 * Setting this parameter directly is probably only feasible if
279 * the user is directly observing the estimates of average clock
280 * period and instantaneous clock period over time in response to
281 * an impulsive change in the input stream (i.e. watching the loop
282 * transient behavior at the start of a data burst).
283 *
284 * \param alpha PI filter proportional gain
285 */
286 virtual void set_alpha(float alpha) = 0;
287
288 /*!
289 * \brief Set the PI filter integral gain, beta.
290 *
291 * \details
292 * Sets the PI filter integral gain, beta.
293 * This gain is used when integrating the clock phase/timing error
294 * term in the PI filter when advancing the loop.
295 * It most directly affects the average clock period estimate,
296 * T_avg.
297 *
298 * This value would normally be adjusted by setting the loop
299 * bandwidth and damping factor. However,
300 * it can be set here directly if desired.
301 *
302 * Setting this parameter directly is probably only feasible if
303 * the user is directly observing the estimates of average clock
304 * period and instantaneous clock period over time in response to
305 * an impulsive change in the input stream (i.e. watching the loop
306 * transient behavior at the start of a data burst).
307 *
308 * \param beta PI filter integral gain
309 */
310 virtual void set_beta(float beta) = 0;
311};
312
313} /* namespace digital */
314} /* namespace gr */
315
316#endif /* INCLUDED_DIGITAL_SYMBOL_SYNC_CC_H */
The abstract base class for all 'terminal' processing blocks.
Definition block.h:72
Symbol Synchronizer block with complex input, complex output.
Definition symbol_sync_cc.h:56
static sptr make(enum ted_type detector_type, float sps, float loop_bw, float damping_factor=1.0f, float ted_gain=1.0f, float max_deviation=1.5f, int osps=1, constellation_sptr slicer=constellation_sptr(), ir_type interp_type=IR_MMSE_8TAP, int n_filters=128, const std::vector< float > &taps=std::vector< float >())
virtual void set_damping_factor(float zeta)=0
Set the loop damping factor.
virtual float loop_bandwidth() const =0
Returns the normalized approximate loop bandwidth.
virtual void set_alpha(float alpha)=0
Set the PI filter proportional gain, alpha.
virtual float damping_factor() const =0
Returns the loop damping factor.
virtual void set_ted_gain(float ted_gain)=0
Set the expected gain of the Timing Error Detector.
virtual float beta() const =0
Returns the PI filter integral gain, beta.
virtual void set_beta(float beta)=0
Set the PI filter integral gain, beta.
virtual void set_loop_bandwidth(float omega_n_norm)=0
Set the normalized approximate loop bandwidth.
virtual float alpha() const =0
Returns the PI filter proportional gain, alpha.
virtual float ted_gain() const =0
Returns the user provided expected gain of the Timing Error Detector.
boost::shared_ptr< symbol_sync_cc > sptr
Definition symbol_sync_cc.h:59
#define DIGITAL_API
Definition gr-digital/include/gnuradio/digital/api.h:30
static const float taps[NSTEPS+1][NTAPS]
Definition interpolator_taps.h:9
ted_type
Definition timing_error_detector_type.h:30
ir_type
Definition interpolating_resampler_type.h:30
GNU Radio logging wrapper for log4cpp library (C++ port of log4j)
Definition basic_block.h:46