GNU Radio 3.5.1 C++ API
gri_control_loop.h
Go to the documentation of this file.
00001 /* -*- c++ -*- */
00002 /*
00003  * Copyright 2011 Free Software Foundation, Inc.
00004  * 
00005  * This file is part of GNU Radio
00006  * 
00007  * GNU Radio is free software; you can redistribute it and/or modify
00008  * it under the terms of the GNU General Public License as published by
00009  * the Free Software Foundation; either version 3, or (at your option)
00010  * any later version.
00011  * 
00012  * GNU Radio is distributed in the hope that it will be useful,
00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00015  * GNU General Public License for more details.
00016  * 
00017  * You should have received a copy of the GNU General Public License
00018  * along with GNU Radio; see the file COPYING.  If not, write to
00019  * the Free Software Foundation, Inc., 51 Franklin Street,
00020  * Boston, MA 02110-1301, USA.
00021  */
00022 
00023 #ifndef GRI_CONTROL_LOOP
00024 #define GRI_CONTROL_LOOP
00025 
00026 #include <gr_core_api.h>
00027 
00028 class GR_CORE_API gri_control_loop
00029 {
00030  protected:
00031   float d_phase, d_freq;
00032   float d_max_freq, d_min_freq;
00033   float d_damping, d_loop_bw;
00034   float d_alpha, d_beta;
00035 
00036  public:
00037   gri_control_loop(float loop_bw, float max_freq, float min_freq);
00038   virtual ~gri_control_loop();
00039 
00040   /*! \brief update the system gains from the loop bandwidth and damping factor
00041    *
00042    *  This function updates the system gains based on the loop
00043    *  bandwidth and damping factor of the system.
00044    *  These two factors can be set separately through their own
00045    *  set functions.
00046    */
00047   void update_gains();
00048 
00049   /*! \brief update the system gains from the loop bandwidth and damping factor
00050    *
00051    *  This function updates the system gains based on the loop
00052    *  bandwidth and damping factor of the system.
00053    *  These two factors can be set separately through their own
00054    *  set functions.
00055    */
00056   void advance_loop(float error);
00057 
00058   /*! \brief Keep the phase between -2pi and 2pi
00059    *
00060    * This function keeps the phase between -2pi and 2pi. If the phase
00061    * is greater than 2pi by d, it wraps around to be -2pi+d; similarly if
00062    * it is less than -2pi by d, it wraps around to 2pi-d.
00063    *
00064    * This function should be called after advance_loop to keep the phase
00065    * in a good operating region. It is set as a separate method in case
00066    * another way is desired as this is fairly heavy-handed.
00067    */
00068   void phase_wrap();
00069 
00070   /*! \brief Keep the frequency between d_min_freq and d_max_freq
00071    *
00072    * This function keeps the frequency between d_min_freq and d_max_freq.
00073    * If the frequency is greater than d_max_freq, it is set to d_max_freq.
00074    * If the frequency is less than d_min_freq, it is set to d_min_freq.
00075    *
00076    * This function should be called after advance_loop to keep the frequency
00077    * in the specified region. It is set as a separate method in case
00078    * another way is desired as this is fairly heavy-handed.
00079    */
00080   void frequency_limit();
00081 
00082   /*******************************************************************
00083     SET FUNCTIONS
00084   *******************************************************************/
00085 
00086   /*!
00087    * \brief Set the loop bandwidth
00088    *
00089    * Set the loop filter's bandwidth to \p bw. This should be between 
00090    * 2*pi/200 and 2*pi/100  (in rads/samp). It must also be a positive
00091    * number.
00092    *
00093    * When a new damping factor is set, the gains, alpha and beta, of the loop
00094    * are recalculated by a call to update_gains().
00095    *
00096    * \param bw    (float) new bandwidth
00097    *
00098    */
00099   void set_loop_bandwidth(float bw);
00100 
00101   /*!
00102    * \brief Set the loop damping factor
00103    *
00104    * Set the loop filter's damping factor to \p df. The damping factor
00105    * should be sqrt(2)/2.0 for critically damped systems.
00106    * Set it to anything else only if you know what you are doing. It must
00107    * be a number between 0 and 1.
00108    *
00109    * When a new damping factor is set, the gains, alpha and beta, of the loop
00110    * are recalculated by a call to update_gains().
00111    *
00112    * \param df    (float) new damping factor
00113    *
00114    */
00115   void set_damping_factor(float df);
00116 
00117   /*!
00118    * \brief Set the loop gain alpha
00119    *
00120    * Set's the loop filter's alpha gain parameter.
00121    *
00122    * This value should really only be set by adjusting the loop bandwidth
00123    * and damping factor.
00124    *
00125    * \param alpha    (float) new alpha gain
00126    *
00127    */
00128   void set_alpha(float alpha);
00129 
00130   /*!
00131    * \brief Set the loop gain beta
00132    *
00133    * Set's the loop filter's beta gain parameter.
00134    *
00135    * This value should really only be set by adjusting the loop bandwidth
00136    * and damping factor.
00137    *
00138    * \param beta    (float) new beta gain
00139    *
00140    */
00141   void set_beta(float beta);
00142 
00143   /*!
00144    * \brief Set the Costas loop's frequency.
00145    *
00146    * Set's the Costas Loop's frequency. While this is normally updated by the
00147    * inner loop of the algorithm, it could be useful to manually initialize,
00148    * set, or reset this under certain circumstances.
00149    *
00150    * \param freq    (float) new frequency
00151    *
00152    */
00153   void set_frequency(float freq);
00154 
00155   /*!
00156    * \brief Set the Costas loop's phase.
00157    *
00158    * Set's the Costas Loop's phase. While this is normally updated by the
00159    * inner loop of the algorithm, it could be useful to manually initialize,
00160    * set, or reset this under certain circumstances.
00161    *
00162    * \param phase    (float) new phase
00163    *
00164    */
00165   void set_phase(float phase);
00166 
00167    
00168   /*******************************************************************
00169     GET FUNCTIONS
00170   *******************************************************************/
00171 
00172   /*!
00173    * \brief Returns the loop bandwidth
00174    */
00175   float get_loop_bandwidth() const;
00176 
00177   /*!
00178    * \brief Returns the loop damping factor
00179    */
00180   float get_damping_factor() const;
00181 
00182   /*!
00183    * \brief Returns the loop gain alpha
00184    */
00185   float get_alpha() const;
00186 
00187   /*!
00188    * \brief Returns the loop gain beta
00189    */
00190   float get_beta() const;
00191 
00192   /*!
00193    * \brief Get the Costas loop's frequency estimate
00194    */
00195   float get_frequency() const;
00196 
00197   /*!
00198    * \brief Get the Costas loop's phase estimate
00199    */
00200   float get_phase() const;
00201 };
00202 
00203 #endif /* GRI_CONTROL_LOOP */