channels: new block documentation/grc cleanup, dynamic fading model AWGN ampl bug fix

author: Tim O'Shea <tim.oshea753@gmail.com> 2013-11-08 12:44:37 -0500
committer: Tim O'Shea <tim.oshea753@gmail.com> 2013-11-08 12:44:37 -0500
commit: 917fb98fdd6f706a58dae515fc0e28fa5ac3b906 (patch)
tree: 77c476257f7387b4a4b8b32ae0b061b43801aa4d
parent: 173b9fc9785cc2f8d11bbd965ca56e05e4e4e3e0 (diff)
6 files changed, 58 insertions, 56 deletions
diff --git a/gr-channels/grc/channels_block_tree.xml b/gr-channels/grc/channels_block_tree.xml
index 154e9204d1..66053f717d 100644
--- a/gr-channels/grc/channels_block_tree.xml
+++ b/gr-channels/grc/channels_block_tree.xml
@@ -32,6 +32,7 @@
     <name>Channel Models</name>
     <block>channels_channel_model</block>
     <block>channels_fading_model</block>
+    <block>channels_dynamic_channel_model</block>
   </cat>
   <cat>
     <name>Impairment Models</name>
@@ -43,5 +44,7 @@
     <block>channels_distortion_3_gen</block>
     <block>channels_amp_bal</block>
     <block>channels_phase_bal</block>
+    <block>channels_cfo_model</block>
+    <block>channels_sro_model</block>
   </cat>
 </cat>
diff --git a/gr-channels/grc/channels_dynamic_channel_model.xml b/gr-channels/grc/channels_dynamic_channel_model.xml
index b87b40da11..b54256c864 100644
--- a/gr-channels/grc/channels_dynamic_channel_model.xml
+++ b/gr-channels/grc/channels_dynamic_channel_model.xml
@@ -118,32 +118,12 @@
 		<type>complex</type>
 	</source>
     <doc>
-    int d_N=8;          // number of sinusoids used to simulate gain on each ray
-    float d_fDTs=0.01   // normalized maximum doppler frequency (f_doppler / f_samprate) 
-    float d_K=4;        // Rician factor (ratio of the specular power to the scattered power)
-    bool d_LOS=true;    // LOS path exists? chooses Rician (LOS) vs Rayleigh (NLOS) model.
-    int seed=0;         // noise seed
-    int ntaps;          // Number of FIR taps to use in selective fading model
-      
-      These two vectors comprise the Power Delay Profile of the signal
-    float_vector delays   // Time delay in the fir filter (in samples) for each arriving WSSUS Ray
-    float_vector mags     // Magnitude corresponding to each WSSUS Ray 
+    The dynamic channel model is a hier block consisting of the following effects:
+        - Dynamic Frequency Selective Fading Channel
+        - Dynamic Center Frequency Offset Model
+        - Dynamic Sample Rate Offset Model
+        - Additive White Gaussian Noise 
 
-    If using a LOS model, the first delay and mag should correspond with the LOS component
-  
-  References:
-
-  The flat-fading portion of the algorithm implements the following
-   Compact Rayleigh and Rician fading simulator based on random walk processes
-   A. Alimohammad S.F. Fard B.F. Cockburn C. Schlegel
-   26th November 2008
-
-  The frequency selective extension of the block roughly implements 
-   A Low-Complexity Hardware Implementation of Discrete-Time
-   Frequency-Selective Rayleigh Fading Channels
-   F. Ren and Y. Zheng
-   24-27 May 2009
-
-  Implementation by Tim O'Shea
+    The desired power delay profile and max doppler frequency may be provided to achieve the desired Ricean or Rayleigh fading scenario.   For center frequency and sample rate offset models, a gaussian random walk process is conducted for each.   The single sample step variance and maximum deviation for these two processes is specified and may be modified to simulate various desired stability effects.  Lastly AWGN is added to simulate a typical receiver/thermal noise floor after propagation, and the variance may be modified here as desired.
     </doc>
 </block>
diff --git a/gr-channels/include/gnuradio/channels/cfo_model.h b/gr-channels/include/gnuradio/channels/cfo_model.h
index 8ebf54ab3f..bb23a8e9f2 100644
--- a/gr-channels/include/gnuradio/channels/cfo_model.h
+++ b/gr-channels/include/gnuradio/channels/cfo_model.h
@@ -35,15 +35,11 @@ namespace gr {
      * \ingroup channel_models_blk
      *
      * \details
-     * This block implements a basic channel model simulator that can
-     * be used to help evaluate, design, and test various signals,
-     * waveforms, and algorithms. This model allows the user to set
-     * the voltage of an AWGN noise source, a (normalized) frequency
-     * offset, a sample timing offset, and a noise seed to randomize
-     * the AWGN noise source.
-     *
-     * Multipath can be approximated in this model by using a FIR
-     * filter representation of a multipath delay profile..
+     * This block implements a carrier frequency offset model that
+     * can be used to simulate carrier frequency drift typically from
+     * mixer LO drift on either transmit or receive hardware.
+     * 
+     * A clipped gaussian random walk process is used.
      */
     class CHANNELS_API cfo_model : virtual public sync_block
     {
@@ -51,6 +47,14 @@ namespace gr {
       // gr::channels::cfo_model::sptr
       typedef boost::shared_ptr<cfo_model> sptr;
 
+      /*! \brief Build the carrier frequency offset model
+       *
+       * \param sample_rate_hz Sample rate of the input signal in Hz
+       * \param std_dev_hz  Desired standard deviation of the random walk
+                            process every sample in Hz
+       * \param max_dev_hz Maximum carrier frequency deviation in Hz.
+       * \param noise_seed A random number generator seed for the noise source.
+       */
       static sptr make(
                 double sample_rate_hz,
                 double std_dev_hz,
diff --git a/gr-channels/include/gnuradio/channels/dynamic_channel_model.h b/gr-channels/include/gnuradio/channels/dynamic_channel_model.h
index 0223b14962..7b23a4144d 100644
--- a/gr-channels/include/gnuradio/channels/dynamic_channel_model.h
+++ b/gr-channels/include/gnuradio/channels/dynamic_channel_model.h
@@ -31,19 +31,19 @@ namespace gr {
   namespace channels {
     
     /*!
-     * \brief channel simulator
+     * \brief dynamic channel simulator
      * \ingroup dynamic_channel_models_blk
      *
      * \details
-     * This block implements a basic channel model simulator that can
+     * This block implements a dynamic channel model simulator that can
      * be used to help evaluate, design, and test various signals,
-     * waveforms, and algorithms. This model allows the user to set
-     * the voltage of an AWGN noise source, a (normalized) frequency
-     * offset, a sample timing offset, and a noise seed to randomize
-     * the AWGN noise source.
+     * waveforms, and algorithms. 
      *
-     * Multipath can be approximated in this model by using a FIR
-     * filter representation of a multipath delay profile..
+     * This model allows the user to set up an AWGN noise cource, a 
+     * random walk process to simulate carrier frequency drift, a random
+     * walk process to simulate sample rate offset drive, and a frequency
+     * selective fading channel response that is either Rayleigh or Ricean
+     * for a user specified power delay profile.
      */
     class CHANNELS_API dynamic_channel_model : virtual public hier_block2
     {
@@ -51,18 +51,25 @@ namespace gr {
       // gr::channels::dynamic_channel_model::sptr
       typedef boost::shared_ptr<dynamic_channel_model> sptr;
 
-      /*! \brief Build the channel simulator.
+      /*! \brief Build the dynamic channel simulator.
        *
-       * \param noise_voltage The AWGN noise level as a voltage (to be
-       *                      calculated externally to meet, say, a
-       *                      desired SNR).
-       * \param frequency_offset The normalized frequency offset. 0 is
-       *                         no offset; 0.25 would be, for a digital
-       *                         modem, one quarter of the symbol rate.
-       * \param epsilon The sample timing offset to emulate the
-       *                different rates between the sample clocks of
-       *                the transmitter and receiver. 1.0 is no difference.
-       * \param taps Taps of a FIR filter to emulate a multipath delay profile.
+       * \param samp_rate   Input sample rate in Hz
+       * \param sro_std_dev  sample rate drift process standard deviation per sample in Hz
+       * \param sro_max_dev  maximum sample rate offset in Hz
+       * \param cfo_std_dev  carrier frequnecy drift process standard deviation per sample in Hz
+       * \param cfo_max_dev  maximum carrier frequency offset in Hz
+
+       * \param N   number of sinusoids used in frequency selective fading simulation
+       * \param doppler_freq    maximum doppler frequency used in fading simulation in Hz
+       * \param LOS_model   defines whether the fading model should include a line of site
+                            component. LOS->Rician, NLOS->Rayleigh
+       * \param K Rician K-factor, the ratio of specular to diffuse power in the model
+       * \param delays  A list of fractional sample delays making up the power delay profile
+       * \param mags    A list of magnitudes corresponding to each delay time in the power delay profile
+       * \param ntaps_mpath The length of the filter to interpolate the power delay profile over. 
+                            Delays in the PDP must lie between 0 and ntaps_mpath, fractional delays
+                            will be sinc-interpolated only to the width of this filter.
+       * \param noise_amp Specifies the standard deviation of the AWGN process
        * \param noise_seed A random number generator seed for the noise source.
        */
       static sptr make(
diff --git a/gr-channels/include/gnuradio/channels/sro_model.h b/gr-channels/include/gnuradio/channels/sro_model.h
index 68eaabee83..7eadc5a796 100644
--- a/gr-channels/include/gnuradio/channels/sro_model.h
+++ b/gr-channels/include/gnuradio/channels/sro_model.h
@@ -35,7 +35,7 @@ namespace gr {
      * \ingroup channel_models_blk
      *
      * \details
-     * This block implements a model that varries sample rate offset
+     * This block implements a model that varies sample rate offset
      * with respect to time by performing a random walk on the 
      * interpolation rate.
      */
@@ -45,6 +45,14 @@ namespace gr {
       // gr::channels::sro_model::sptr
       typedef boost::shared_ptr<sro_model> sptr;
 
+      /*! \brief Build the sample rate offset model
+       *
+       * \param sample_rate_hz Sample rate of the input signal in Hz
+       * \param std_dev_hz  Desired standard deviation of the random walk
+                            process every sample in Hz
+       * \param max_dev_hz Maximum sample rate deviation from zero in Hz.
+       * \param noise_seed A random number generator seed for the noise source.
+       */
       static sptr make(
                 double sample_rate_hz,
                 double std_dev_hz,
diff --git a/gr-channels/lib/dynamic_channel_model_impl.cc b/gr-channels/lib/dynamic_channel_model_impl.cc
index d07a0f9454..7c2044570a 100644
--- a/gr-channels/lib/dynamic_channel_model_impl.cc
+++ b/gr-channels/lib/dynamic_channel_model_impl.cc
@@ -73,7 +73,7 @@ namespace gr {
     {
       d_noise_adder = blocks::add_cc::make();
       d_noise = analog::fastnoise_source_c::make(analog::GR_GAUSSIAN,
-						 1.0, noise_seed, 1024*8);
+						 noise_amp, noise_seed, 1024*8);
       d_sro_model = channels::sro_model::make(samp_rate, sro_std_dev, sro_max_dev, noise_seed);
       d_cfo_model = channels::cfo_model::make(samp_rate, cfo_std_dev, cfo_max_dev, noise_seed);
       d_fader = channels::selective_fading_model::make(N, doppler_freq / samp_rate, LOS_model, K, noise_seed, delays, mags, ntaps_mpath);
author	Tim O'Shea <tim.oshea753@gmail.com>	2013-11-08 12:44:37 -0500
committer	Tim O'Shea <tim.oshea753@gmail.com>	2013-11-08 12:44:37 -0500
commit	917fb98fdd6f706a58dae515fc0e28fa5ac3b906 (patch)
tree	77c476257f7387b4a4b8b32ae0b061b43801aa4d
parent	173b9fc9785cc2f8d11bbd965ca56e05e4e4e3e0 (diff)