portapack-mayhem/firmware/baseband/clock_recovery.hpp

/*
 * Copyright (C) 2014 Jared Boone, ShareBrained Technology, Inc.
 *
 * This file is part of PortaPack.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; see the file COPYING.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street,
 * Boston, MA 02110-1301, USA.
 */

#ifndef __CLOCK_RECOVERY_H__
#define __CLOCK_RECOVERY_H__

#include <cstddef>
#include <array>
#include <functional>

#include "linear_resampler.hpp"

namespace clock_recovery {

class GardnerTimingErrorDetector {
   public:
    static constexpr size_t samples_per_symbol{2};

    /*
        Expects retimed samples at a rate of twice the expected symbol rate.
        Calculates timing error, sends symbol and error to handler.
        */
    template <typename SymbolHandler>
    void operator()(
        const float in,
        SymbolHandler symbol_handler) {
        /* NOTE: Algorithm is sensitive to input magnitude. Timing error value
         * will scale proportionally. Best practice is to use error sign only.
         */
        t[2] = t[1];
        t[1] = t[0];
        t[0] = in;

        if (symbol_phase == 0) {
            const auto symbol = t[0];
            const float lateness = (t[0] - t[2]) * t[1];
            symbol_handler(symbol, lateness);
        }

        symbol_phase = (symbol_phase + 1) % samples_per_symbol;
    }

   private:
    std::array<float, 3> t{};
    size_t symbol_phase{0};
};

class LinearErrorFilter {
   public:
    LinearErrorFilter(
        const float filter_alpha = 0.95f,
        const float error_weight = -1.0f)
        : filter_alpha{filter_alpha},
          error_weight{error_weight} {
    }

    float operator()(
        const float error) {
        error_filtered = filter_alpha * error_filtered + (1.0f - filter_alpha) * error;
        return error_filtered * error_weight;
    }

   private:
    const float filter_alpha;
    const float error_weight;
    float error_filtered{0.0f};
};

class FixedErrorFilter {
   public:
    FixedErrorFilter() {
    }

    FixedErrorFilter(
        const float weight)
        : weight_{weight} {
    }

    float operator()(
        const float lateness) const {
        return (lateness < 0.0f) ? weight() : -weight();
    }

    float weight() const {
        return weight_;
    }

   private:
    float weight_{1.0f / 16.0f};
};

template <typename ErrorFilter>
class ClockRecovery {
   public:
    using SymbolHandler = std::function<void(const float)>;

    ClockRecovery(
        const float sampling_rate,
        const float symbol_rate,
        ErrorFilter error_filter,
        SymbolHandler symbol_handler)
        : symbol_handler{std::move(symbol_handler)} {
        configure(sampling_rate, symbol_rate, error_filter);
    }

    ClockRecovery(
        SymbolHandler symbol_handler)
        : symbol_handler{std::move(symbol_handler)} {
    }

    void configure(
        const float sampling_rate,
        const float symbol_rate,
        ErrorFilter error_filter) {
        resampler.configure(sampling_rate, symbol_rate * timing_error_detector.samples_per_symbol);
        error_filter = error_filter;
    }

    void operator()(
        const float baseband_sample) {
        resampler(baseband_sample,
                  [this](const float interpolated_sample) {
                      this->resampler_callback(interpolated_sample);
                  });
    }

   private:
    dsp::interpolation::LinearResampler resampler{};
    GardnerTimingErrorDetector timing_error_detector{};
    ErrorFilter error_filter{};
    const SymbolHandler symbol_handler;

    void resampler_callback(const float interpolated_sample) {
        timing_error_detector(interpolated_sample,
                              [this](const float symbol, const float lateness) {
                                  this->symbol_callback(symbol, lateness);
                              });
    }

    void symbol_callback(const float symbol, const float lateness) {
        // NOTE: This check is to avoid std::function nullptr check, which
        // brings in "_ZSt25__throw_bad_function_callv" and a lot of extra code.
        // TODO: Make symbol_handler known at compile time.
        if (symbol_handler) {
            symbol_handler(symbol);
        }

        const float adjustment = error_filter(lateness);
        resampler.advance(adjustment);
    }
};

} /* namespace clock_recovery */

#endif /*__CLOCK_RECOVERY_H__*/