comments, extra retune step.

README.md

@@ -18,8 +18,7 @@ Command a source block with PMT tuning messages to sweep over a set of frequency
 
 ### [retune_fft](grc/iqtlabs_retune_fft.block.yml)
 
-Command a source block with PMT tuning messages to sweep over a set of frequency ranges, retuning after a configurable nunber of FFT points are received over a configurable threshold
-(while validating power values are in a valid range).
+Command a source block with PMT tuning messages to sweep over a set of frequency ranges, retuning after a configurable nunber of FFT points are received over a configurable threshold (while validating power values are in a valid range).
 
 ### [tuneable_test_source](grc/iqtlabs_tuneable_test_source.block.yml)
 

lib/retune_fft_impl.cc

@@ -353,9 +353,14 @@ void retune_fft_impl::process_items_(size_t c, const input_type *&in,
       slew_samples_ += nfft_;
       continue;
     }
-    // Discard windows where max power, is less than requested minimum.
-    // Ettus radios periodically output low power after retuning. This
-    // avoids having to use a static skip_fft_count setting.
+    // Implement the low power hold down workaround (typically for Ettus).
+    // When retuning the radio, typically the radio responds relatively quickly
+    // with new rx_time and rx_freq tags acknowledging the request. However,
+    // we continue to observe samples for the previous frequency for some time.
+    // Then, we receive all complex 0's for a time, and then we receive samples
+    // for actual frequency requested. We detect the all-zeros condition (by
+    // observing implausibly low power) condition and move the rx_time and
+    // rx_freq tags to this position.
     volk_32f_index_max_16u(in_max_pos_.get(), in, nfft_);
     float in_max = in[*in_max_pos_];
     if (in_max < fft_min_) {

lib/retune_pre_fft_impl.cc

@@ -275,6 +275,13 @@ void retune_pre_fft_impl::process_items_(size_t c, const block_type *&in,
         continue;
       }
       bool all_zeros = all_zeros_(in);
+      // Implement the low power hold down workaround (typically for Ettus).
+      // When retuning the radio, typically the radio responds relatively
+      // quickly with new rx_time and rx_freq tags acknowledging the request.
+      // However, we continue to observe samples for the previous frequency for
+      // some time. Then, we receive all complex 0's for a time, and then we
+      // receive samples for actual frequency requested. We detect the all-zeros
+      // condition and move the rx_time and rx_freq tags to this position.
       if (in_hold_down_) {
         if (all_zeros) {
           in_hold_down_ = false;

lib/retuner_impl.cc

@@ -325,6 +325,12 @@ void retuner_impl::next_retune_(TIME_T host_now) {
   slew_samples_ = 0;
 }
 
+// Attempt to account for elapsed time since tuning tag was received,
+// but before samples are passed on to subsequent blocks. The accuracy
+// of the timestamp itself is not known, since it is the host's gnuradio
+// driver that adds the tag and some number of samples may have been in
+// flight from the radio
+// (https://github.com/gnuradio/gnuradio/blob/fe048a9874d2604d48d396d2b39925a0cf2c3c70/gr-uhd/lib/usrp_source_impl.cc#L636).
 TIME_T retuner_impl::apply_rx_time_slew_(TIME_T rx_time) {
   if (slew_rx_time_) {
     TIME_T slew_time = slew_samples_ / TIME_T(samp_rate_);