iqtlabs_retune_fft.block.yml

---
id: iqtlabs_retune_fft
label: retune_fft
category: '[iqtlabs]'
flags: [python, cpp]
documentation: |-
  This block commands a radio source block to scan across a frequency range,
  while annotating the output of a FFT block, outputing JSON objects
  (see https://github.com/iqtlabs/gamutRF for an example use case). Scanning
  is driven by counting FFT samples to decide when to retune by configurable
  increments. If the radio does not accurately annotate samples with frequencies
  and times, this block can gate on low power holddown (see below). If
  the radio does accurately annotate, use the pre_retune block and
  pre_fft = True.

  input:
    vector of floats, representing FFT bucket values,
    tagged with center frequency.
      cmd:
        connection from retune_pre_fft to control tuning (optional).
  output:
      fft_output:
        fft points gated on minimum power.
      tune:
        connect to radio command port, generally "cmd".
      json:
        output buckets as zstd compressed JSON object (optional).

  parameters:
    tag: expected PMT tag containing center frequency
         (generally "rx_freq" for Soapy or UHD sources).
    nfft: number of FFT points.
    samp_rate: sample rate.
    tune_jitter_hz: if > 0, jitter tune interval.
    freq_start: frequency to start scan at in Hz (overridden by tuning_ranges).
    freq_end: frequency to end scan at in Hz (overridden by tuning_ranges).
    tune_step_hz: increment frequency by this value each retuning step.
    tune_step_fft: count at least this many FFT vectors between retuning steps.
    skip_tune_step_fft: discard this many FFT vectors before counting
                        (to allow for radio to stabilize after retuning)
    fft_min: clip FFT values to this minimum.
    fft_max: clip FFT values to this maximum.
    sdir: directory to write raw FFT points to.
    write_step_fft: if > 0, write N vectors of FFT points at each retune step.
    bucket_range: proportion of buckets to write out, at center frequency.
    tuning_ranges: if not empty, a comma separated list of tuning ranges
                   in ascending order (non-linear scan), e.g.
                   "2.2e9-2.4e9,5.1e9-5.9e9".
    description: a string description to be included with each update.
    rotate_secs: if > 0, use a new epoch timestamped directory every N seconds.
    pre_fft: if True, tuning is controlled by the retune_pre_fft block.
    tag_now: if True, send "tag:now" tag along with tuning message.
    low_power_hold_down: if True, suppress samples between sending a retune
                         message and observing low power (Ettus retune delay
                         workaround).
    slew_rx_time: if True and low_power_hold down, slew rx_time based on
                  sample count.
    peak_fft_range: if > 0, calculate FFT peak of averages over this many
                    windows, if 0 calculate average over whole bucket.

  example JSON output:
    { "ts": <epoch time>, "sweep start": <epoch time>,
      "config": { "description": "...", "freq_start": 10e6,
      "freq_end": 20e6, ... }, "buckets": { "10e6": 1, "10.1e6", ... } }

    if tuning_ranges is used, freq_start and freq_end will be the
    minimum and maximum of all ranges.


templates:
  imports: from gnuradio import iqtlabs
  make: >
    iqtlabs.retune_fft(
    ${tag}, ${nfft}, ${samp_rate}, ${tune_jitter_hz},
    ${freq_start}, ${freq_end}, ${tune_step_hz}, ${tune_step_fft},
    ${skip_tune_step_fft}, ${fft_min}, ${fft_max}, ${sdir}, ${write_step_fft},
    ${bucket_range}, ${tuning_ranges}, ${description}, ${rotate_secs},
    ${pre_fft}, ${tag_now}, ${low_power_hold_down), ${slew_rx_time},
    ${peak_fft_range})

cpp_templates:
  includes: ['#include <gnuradio/iqtlabs/retune_fft.h>']
  declarations: 'gr::iqtlabs::retune_fft::sptr ${id};'
  make: >
    this->${id} = gr::iqtlabs::retune_fft::make(
    ${tag}, ${nfft}, ${samp_rate}, ${tune_jitter_hz},
    ${freq_start}, ${freq_end}, ${tune_step_hz}, ${tune_step_fft},
    ${skip_tune_step_fft}, ${fft_min}, ${fft_max}, ${sdir}, ${write_step_fft},
    ${bucket_range}, ${tuning_ranges}, ${description}, ${rotate_secs},
    ${pre_fft}, ${tag_now}, ${low_power_hold_down), ${slew_rx_time},
    ${peak_fft_range});
  link: ['libgnuradio-iqtlabs.so']

asserts:
  - ${ tag != "" }
  - ${ nfft > 0 }
  - ${ samp_rate > 0 }
  - ${ freq_end > freq_start }
  - ${ (tune_step_hz > 0) or (tune_step_fft > 0) }

parameters:
  - id: tag
    dtype: string
    default: 'rx_freq'
  - id: nfft
    dtype: int
  - id: samp_rate
    dtype: int
  - id: tune_jitter_hz
    dtype: int
  - id: freq_start
    dtype: raw
  - id: freq_end
    dtype: raw
  - id: tune_step_hz
    dtype: int
  - id: tune_step_fft
    dtype: int
  - id: skip_tune_step_fft
    dtype: int
  - id: fft_min
    dtype: raw
  - id: fft_max
    dtype: raw
  - id: sdir
    dtype: string
  - id: write_step_fft
    dtype: int
  - id: bucket_range
    dtype: float
  - id: tuning_ranges
    dtype: string
  - id: description
    dtype: string
  - id: rotate_secs
    dtype: int
  - id: tag_now
    dtype: bool
  - id: low_power_hold_down
    dtype: bool
  - id: slew_rx_time
    dtype: bool
  - id: peak_fft_range
    dtype: int

inputs:
  - label: input
    domain: stream
    dtype: float
    vlen: ${ nfft }
  - label: cmd
    domain: message

outputs:
  - label: fft_output
    domain: stream
    dtype: float
    vlen: ${ nfft }
    optional: 1
  - label: tune
    domain: message
  - label: json
    domain: message


file_format: 1