GNU Radio Manual and C++ API Reference  3.7.13.4
The Free & Open Software Radio Ecosystem
corr_est_cc.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2015 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_CORR_EST_CC_CC_H
24 #define INCLUDED_DIGITAL_CORR_EST_CC_CC_H
25 
26 #include <gnuradio/digital/api.h>
27 #include <gnuradio/sync_block.h>
28 
29 namespace gr {
30  namespace digital {
31 
32  /*!
33  * \brief Correlate stream with a pre-defined sequence and estimate peak
34  * \ingroup synchronizers_blk
35  *
36  * \details
37  * Input:
38  * \li Stream of complex samples.
39  *
40  * Output:
41  * \li Output stream that just passes the input complex samples
42  * \li tag 'phase_est': estimate of phase offset
43  * \li tag 'time_est': estimate of symbol timing offset
44  * \li tag 'corr_est': the correlation value of the estimates
45  * \li tag 'amp_est': 1 over the estimated amplitude
46  * \li tag 'corr_start': the start sample of the correlation and the value
47  *
48  * \li Optional 2nd output stream providing the advanced correlator output
49  *
50  * This block is designed to search for a sync word by correlation
51  * and uses the results of the correlation to get a time and phase
52  * offset estimate. These estimates are passed downstream as
53  * stream tags for use by follow-on synchronization blocks.
54  *
55  * The sync word is provided as a set of symbols after being
56  * filtered by a baseband matched filter.
57  *
58  * The phase_est tag can be used by downstream blocks to adjust
59  * their phase estimator/correction loops, and is currently
60  * implemented by the gr::digital::costas_loop_cc block.
61  *
62  * The time_est tag can be used to adjust the sampling timing
63  * estimate of any downstream synchronization blocks and is
64  * currently implemented by the gr::digital::pfb_clock_sync_ccf
65  * block.
66  *
67  * The caller must provide a "time_est" and "phase_est" tag
68  * marking delay from the start of the correlated signal segment,
69  * in order to mark the proper point in the sync word for
70  * downstream synchronization blocks. Generally this block cannot
71  * know where the actual sync word symbols are located relative to
72  * "corr_start", given that some modulations have pulses with
73  * intentional ISI. The user should manually examine the primary
74  * output and the "corr_start" tag postition to determine the
75  * required tag delay settings for the particular modulation,
76  * sync word, and downstream blocks used.
77  *
78  * For a discussion of the properties of complex correlations,
79  * with respect to signal processing, see:
80  * Marple, Jr., S. L., "Estimating Group Delay and Phase Delay
81  * via Discrete-Time 'Analytic' Cross-Correlation, _IEEE_Transcations_
82  * _on_Signal_Processing_, Volume 47, No. 9, September 1999
83  *
84  */
85  class DIGITAL_API corr_est_cc : virtual public sync_block
86  {
87  public:
88  typedef boost::shared_ptr<corr_est_cc> sptr;
89 
90  /*!
91  * Make a block that correlates against the \p symbols vector
92  * and outputs a phase and symbol timing estimate.
93  *
94  * \param symbols Set of symbols to correlate against (e.g., a
95  * sync word).
96  * \param sps Samples per symbol
97  * \param mark_delay tag marking delay in samples after the
98  * corr_start tag
99  * \param threshold Threshold of correlator, relative to a 100%
100  * correlation (1.0). Default is 0.9.
101  */
102  static sptr make(const std::vector<gr_complex> &symbols,
103  float sps, unsigned int mark_delay, float threshold=0.9);
104 
105  virtual std::vector<gr_complex> symbols() const = 0;
106  virtual void set_symbols(const std::vector<gr_complex> &symbols) = 0;
107 
108  virtual unsigned int mark_delay() const = 0;
109  virtual void set_mark_delay(unsigned int mark_delay) = 0;
110 
111  virtual float threshold() const = 0;
112  virtual void set_threshold(float threshold) = 0;
113  };
114 
115  } // namespace digital
116 } // namespace gr
117 
118 #endif /* INCLUDED_DIGITAL_CORR_EST_CC_H */
#define DIGITAL_API
Definition: gr-digital/include/gnuradio/digital/api.h:30
boost::shared_ptr< corr_est_cc > sptr
Definition: corr_est_cc.h:88
Include this header to use the message passing features.
Definition: logger.h:695
Correlate stream with a pre-defined sequence and estimate peak.
Definition: corr_est_cc.h:85
synchronous 1:1 input to output with historyOverride work to provide the signal processing implementa...
Definition: sync_block.h:37