other changes

4 files changed, 142 insertions, 127 deletions

diff --git a/src/lib/Assert.h b/src/lib/Assert.h
index dd222b0..acfb3f7 100644
--- a/src/lib/Assert.h
+++ b/src/lib/Assert.h
@@ -26,7 +26,7 @@
 #include "stdio.h"
 #include <iostream>
 
-// #define NDEBUG
+#define NDEBUG
 
 /**@name Macros for standard messages. */
 //@{
diff --git a/src/lib/gsm.i b/src/lib/gsm.i
index dc0be34..9a9e8ea 100644
--- a/src/lib/gsm.i
+++ b/src/lib/gsm.i
@@ -36,13 +36,6 @@
 
 // ----------------------------------------------------------------
 
-/*
- * First arg is the package prefix.
- * Second arg is the name of the class minus the prefix.
- *
- * This does some behind-the-scenes magic so we can
- * access howto_square_ff from python as howto.square_ff
- */
 GR_SWIG_BLOCK_MAGIC(gsm,receiver_cf);
 
 gsm_receiver_cf_sptr gsm_make_receiver_cf ( gr_feval_dd *tuner, int osr);
diff --git a/src/lib/gsm_constants.h b/src/lib/gsm_constants.h
index bc16902..cf9f059 100644
--- a/src/lib/gsm_constants.h
+++ b/src/lib/gsm_constants.h
@@ -23,7 +23,7 @@
 #define FCCH_POS          TAIL_BITS
 #define SYNC_POS          39
 #define TRAIN_POS         ( TAIL_BITS + DATA_BITS + 5) //first 5 bits of a training sequence
-//aren't used for channel impulse response estimation
+                                                       //aren't used for channel impulse response estimation
 #define TRAIN_BEGINNING   5
 #define SAFETY_MARGIN     6   //
 
@@ -41,11 +41,11 @@ static const unsigned char SYNC_BITS[] = {
 };
 
 const unsigned FCCH_FRAMES[] = {0, 10, 20, 30, 40};
-const unsigned SCH_FRAMES[] = {1,11,21,31,41};
+const unsigned SCH_FRAMES[] = {1, 11, 21, 31, 41};
 
-const unsigned BCCH_FRAMES[] = {2,3,4,5};             //!!the receiver shouldn't care about logical 
-const unsigned TRAFFIC_CHANNEL_F[] = {0,1,2,3,4,5,6,7,8,9,10,11,13,14,15,16,17,18,19,20,21,22,23,24};
-                                                      //!!channels so this will be removed from this header
+const unsigned BCCH_FRAMES[] = {2, 3, 4, 5};          //!!the receiver shouldn't care about logical
+const unsigned TRAFFIC_CHANNEL_F[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24};
+//!!channels so this will be removed from this header
 const unsigned TEST[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50};
 // Sync             : .+...++.+..+++.++++++.++++++....++.+..+.+.+++.+.+...+..++++..+..
 // Diff Encoded Sync: .++..+.+++.+..++.....++.....+...+.+++.+++++..+++++..++.+...+.++.
@@ -106,8 +106,8 @@ static const unsigned char dummy_burst[] = {
  * COMPACT) the center frequency.  One can use this spike with a narrow
  * band filter to accurately determine the center of the channel.
  */
-static const unsigned char fc_fb[] = {               //I don't use this tables, 
-  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,    //I copied this here from burst_types.h because 
+static const unsigned char fc_fb[] = {               //I don't use this tables,
+  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,    //I copied this here from burst_types.h because
   0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,    //the description is very informative - p.krysik
   0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
   0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
diff --git a/src/lib/gsm_receiver_cf.h b/src/lib/gsm_receiver_cf.h
index d35e4da..b937f76 100644
--- a/src/lib/gsm_receiver_cf.h
+++ b/src/lib/gsm_receiver_cf.h
@@ -37,8 +37,9 @@ typedef std::vector<gr_complex> vector_complex;
 gsm_receiver_cf_sptr gsm_make_receiver_cf(gr_feval_dd *tuner, int osr);
 
 /** GSM Receiver GNU Radio block
+ *
  * GSM Receiver class supports frequency correction, synchronisation and
- * MLSE (Maximum Likelihood Sequence Estimation) estimation of synchronisation 
+ * MLSE (Maximum Likelihood Sequence Estimation) estimation of synchronisation
  * bursts and normal bursts.
  * \ingroup block
  */
@@ -46,148 +47,169 @@ gsm_receiver_cf_sptr gsm_make_receiver_cf(gr_feval_dd *tuner, int osr);
 class gsm_receiver_cf : public gr_block
 {
   private:
-    
-    const int d_OSR;
-    const int d_chan_imp_length;
+
+    /**@name Configuration of the receiver */
+    //@{
+    const int d_OSR; ///< oversampling ratio
+    const int d_chan_imp_length; ///< channel impulse length
+    //@}
 
     gr_complex d_sch_training_seq[N_SYNC_BITS]; ///<encoded training sequence of a SCH burst
     gr_complex d_norm_training_seq[TRAIN_SEQ_NUM][N_TRAIN_BITS]; ///<encoded training sequences of a normal bursts and dummy bursts
 
     gr_feval_dd *d_tuner; ///<callback to a python object which is used for frequency tunning
-    unsigned d_samples_counter; ///<samples counter - this is used in beetween find_fcch_burst and find_sch_burst
-
-    //variables used to store result of the find_fcch_burst fuction
-//     unsigned d_fcch_start_pos; 
-    float d_freq_offset;
-
-    burst_counter d_burst_nr;
-    channel_configuration d_channel_conf;
-
-    vector_complex d_channel_imp_resp;
-
-    int d_ncc;
-    int d_bcc;
 
+    /** Countes samples consumed by the receiver
+     *
+     * It is used in beetween find_fcch_burst and find_sch_burst calls.
+     * My intention was to synchronize this counter with some internal sample
+     * counter of the USRP. Simple access to such USRP's counter isn't possible
+     * so this variable isn't used in the "synchronized" state of the receiver yet.
+     */
+    unsigned d_counter;
+
+    /**@name Variables used to store result of the find_fcch_burst fuction */
+    //@{
+    unsigned d_fcch_start_pos; ///< position of the first sample of the fcch burst
+    float d_freq_offset; ///< frequency offset of the received signal
+    //@}
+
+    /**@name Identifiers of the BTS extracted from the SCH burst */
+    //@{
+    int d_ncc; ///< network color code
+    int d_bcc; ///< base station color code
+    //@}
+
+    /**@name Internal state of the gsm receiver */
+    //@{
     enum states {
-      first_fcch_search, next_fcch_search, sch_search, //synchronization search part
-      synchronized //receiver is synchronized in this state
+      first_fcch_search, next_fcch_search, sch_search, // synchronization search part
+      synchronized // receiver is synchronized in this state
     } d_state;
+    //@}
+
+    /**@name Variables which make internal state in the "synchronized" state */
+    //@{
+    burst_counter d_burst_nr; ///< frame number and timeslot number
+    channel_configuration d_channel_conf; ///< mapping of burst_counter to burst_type
+    //@}
 
     friend gsm_receiver_cf_sptr gsm_make_receiver_cf(gr_feval_dd *tuner, int osr);
     gsm_receiver_cf(gr_feval_dd *tuner, int osr);
 
-    
-    /**
-     * 
-     * @param in 
-     * @param nitems 
-     * @return 
+    /** Function whis is used to search a FCCH burst and to compute frequency offset before
+     * "synchronized" state of the receiver
+     *
+     * TODO: Describe the FCCH search algorithm in the documentation
+     * @param input vector with input signal
+     * @param nitems number of samples in the input vector
+     * @return
      */
-    bool find_fcch_burst(const gr_complex *in, const int nitems);
-    
-    /**
-     * 
-     * @param best_sum 
-     * @param denominator 
-     * @return 
+    bool find_fcch_burst(const gr_complex *input, const int nitems);
+
+    /** Computes frequency offset from FCCH burst samples
+     *
+     * @param input vector with input samples
+     * @param first_sample number of the first sample of the FCCH busrt
+     * @param last_sample number of the last sample of the FCCH busrt
+     * @return frequency offset
      */
-    double compute_freq_offset(double best_sum, unsigned denominator);
-    
-    /**
-     * 
-     * @param freq_offset 
+    double compute_freq_offset(const gr_complex * input, unsigned first_sample, unsigned last_sample);
+
+    /** Calls d_tuner's method to set frequency offset from Python level
+     *
+     * @param freq_offset absolute frequency offset of the received signal
      */
     void set_frequency(double freq_offset);
-    
-    /**
-     * 
-     * @param val1 
-     * @param val2 
-     * @return 
+
+    /** Computes angle between two complex numbers
+     *
+     * @param val1 first complex number
+     * @param val2 second complex number
+     * @return
      */
     inline float compute_phase_diff(gr_complex val1, gr_complex val2);
 
-    /**
-     * 
-     * @param in 
-     * @param nitems 
-     * @param out 
-     * @return 
+    /** Function whis is used to get near to SCH burst
+     *
+     * @param nitems number of samples in the gsm_receiver's buffer
+     * @return true if SCH burst is near, false otherwise
      */
-    bool find_sch_burst(const gr_complex *in, const int nitems , float *out);
-    
-    /**
-     * 
-     * @param in 
-     * @param chan_imp_resp 
-     * @return 
+    bool find_sch_burst(const int nitems);
+
+    /** Extracts channel impulse response from a SCH burst and computes first sample number of this burst
+     *
+     * @param input vector with input samples
+     * @param chan_imp_resp complex vector where channel impulse response will be stored
+     * @return number of first sample of the burst
      */
-    int get_sch_chan_imp_resp(const gr_complex *in, gr_complex * chan_imp_resp);
-    
-    /**
-     * 
-     * @param in 
-     * @param chan_imp_resp 
-     * @param burst_start 
-     * @param output_binary 
+    int get_sch_chan_imp_resp(const gr_complex *input, gr_complex * chan_imp_resp);
+
+    /** MLSE detection of a burst bits
+     *
+     * Detects bits of burst using viterbi algorithm.
+     * @param input vector with input samples
+     * @param chan_imp_resp vector with the channel impulse response
+     * @param burst_start number of the first sample of the burst
+     * @param output_binary vector with output bits
      */
-    void detect_burst(const gr_complex * in, gr_complex * chan_imp_resp, int burst_start, unsigned char * output_binary);
-    
-    /**
-     * 
-     * @param input 
-     * @param ninput 
-     * @param gmsk_output 
-     * @param start_point 
+    void detect_burst(const gr_complex * input, gr_complex * chan_imp_resp, int burst_start, unsigned char * output_binary);
+
+    /** Encodes differentially input bits and maps them into MSK states
+     *
+     * @param input vector with input bits
+     * @param nitems number of samples in the "input" vector
+     * @param gmsk_output bits mapped into MSK states
+     * @param start_point first state
      */
-    void gmsk_mapper(const unsigned char * input, int ninput, gr_complex * gmsk_output, gr_complex start_point);
-    
-    /**
-     * 
-     * @param sequence 
-     * @param input_signal 
-     * @param ninput 
-     * @return 
+    void gmsk_mapper(const unsigned char * input, int nitems, gr_complex * gmsk_output, gr_complex start_point);
+
+    /** Correlates MSK mapped sequence with input signal
+     *
+     * @param sequence MKS mapped sequence
+     * @param length length of the sequence
+     * @param input_signal vector with input samples
+     * @return correlation value
      */
-    gr_complex correlate_sequence(const gr_complex * sequence, const gr_complex * input_signal, int ninput);
-    
-    /**
-     * 
-     * @param input 
-     * @param out 
-     * @param length 
+    gr_complex correlate_sequence(const gr_complex * sequence, int length, const gr_complex * input);
+
+    /** Computes autocorrelation of input vector for positive arguments
+     *
+     * @param input vector with input samples
+     * @param out output vector
+     * @param nitems length of the input vector
      */
-    inline void autocorrelation(const gr_complex * input, gr_complex * out, int length);
-    
-    /**
-     * 
-     * @param input 
-     * @param input_length 
-     * @param filter 
-     * @param filter_length 
-     * @param output 
+    inline void autocorrelation(const gr_complex * input, gr_complex * out, int nitems);
+
+    /** Filters input signal through channel impulse response
+     *
+     * @param input vector with input samples
+     * @param nitems number of samples to pass through filter
+     * @param filter filter taps - channel impulse response
+     * @param filter_length nember of filter taps
+     * @param output vector with filtered samples
      */
-    inline void mafi(const gr_complex * input, int input_length, gr_complex * filter, int filter_length, gr_complex * output);
-    
-    /**
-     * 
-     * @param in 
-     * @param chan_imp_resp 
-     * @param search_range 
-     * @param bcc 
-     * @return 
+    inline void mafi(const gr_complex * input, int nitems, gr_complex * filter, int filter_length, gr_complex * output);
+
+    /**  Extracts channel impulse response from a normal burst and computes first sample number of this burst
+     *
+     * @param input vector with input samples
+     * @param chan_imp_resp complex vector where channel impulse response will be stored
+     * @param search_range possible absolute offset of a channel impulse response start
+     * @param bcc base station color code - number of a training sequence
+     * @return first sample number of normal burst
      */
-    int get_norm_chan_imp_resp(const gr_complex *in, gr_complex * chan_imp_resp, unsigned search_range, int bcc);
-    
+    int get_norm_chan_imp_resp(const gr_complex * input, gr_complex * chan_imp_resp, unsigned search_range, int bcc);
+
     /**
-     * 
-     * @param burst_nr 
-     * @param pakiet 
+     *
+     * @param burst_nr
+     * @param pakiet
      */
     void przetwarzaj_normalny_pakiet(burst_counter burst_nr, unsigned char * pakiet);
-    
+
     /**
-     * 
+     *
      */
     void konfiguruj_odbiornik();