input.hpp

Go to the documentation of this file.

/**
 * @file input.hpp
 * @brief CV Input component — smoothed ADC reading with range scaling
 * @ingroup components
 *
 * CvInput is a pure signal-processing component (I/O Stack). It takes raw
 * ADC values, applies EWMA smoothing, and provides scaled output. It does
 * NOT call the ADC driver — the application feeds it values, making it
 * agnostic to the acquisition strategy (polling, DMA, etc.).
 *
 * Usage:
 *   sbl::components::cv::CvInput knob;
 *   knob.update(raw_adc_value);
 *   uint16_t smooth = knob.value();             // 0–65535
 *   int32_t  param  = knob.scaled(50, 500);     // map to parameter range
 */
 
#ifndef SBL_COMPONENTS_CV_INPUT_HPP_
#define SBL_COMPONENTS_CV_INPUT_HPP_
 
#include <cstdint>
#include <sbl/primitives/math/ewma.hpp>
#include <sbl/dsp/warp.hpp>
 
namespace sbl {
namespace components {
namespace cv {
 
/**
 * @brief Smoothing presets for CvInput EWMA filter
 *
 * Values are the EWMA shift exponent (alpha = 1/2^shift).
 * Higher values = more smoothing, slower response.
 */
enum class Smoothing : uint8_t {
    None   = 0,  ///< Raw passthrough (no filtering)
    Light  = 1,  ///< alpha=1/2, settles in ~4 samples (pitch, fast CV)
    Medium = 3,  ///< alpha=1/8, settles in ~24 samples (pots, knobs)
    Heavy  = 5,  ///< alpha=1/32, settles in ~96 samples (noisy sources)
};
 
struct CvInputConfig {
    Smoothing smoothing = Smoothing::Medium;
};
 
/**
 * @brief Smoothed CV input with EWMA filtering and range scaling
 *
 * @note All public methods are ISR-safe — pure state machine with no hardware I/O.
 */
class CvInput {
public:
    explicit CvInput(const CvInputConfig& config = {})
        : filter_(static_cast<uint8_t>(config.smoothing)), raw_(0) {}
 
    explicit CvInput(Smoothing smoothing)
        : filter_(static_cast<uint8_t>(smoothing)), raw_(0) {}
 
    /** @brief Feed a new raw ADC sample */
    void update(uint16_t raw) {
        raw_ = raw;
        filter_.update(raw);
    }
 
    /** @brief Last raw (unfiltered) value */
    uint16_t raw() const { return raw_; }
 
    /** @brief Current smoothed value (0–65535) */
    uint16_t value() const { return filter_.value(); }
 
    /**
     * @brief Map smoothed value to an output range (linear)
     *
     * Linear interpolation from [0, 65535] → [min, max].
     * Uses int64_t intermediate to avoid overflow.
     * For non-linear mapping (frequency, filter cutoff), see scaled_curved().
     *
     * @param min Output minimum (inclusive)
     * @param max Output maximum (inclusive)
     * @return Scaled value in [min, max]
     */
    int32_t scaled(int32_t min, int32_t max) const {
        int64_t v = filter_.value();
        return static_cast<int32_t>(min + (v * (max - min)) / 65535);
    }
 
    /**
     * @brief Map smoothed value with curve shaping
     *
     * Applies ExpCurveWarp::warp() before scaling, useful for knob-friendly
     * non-linear mapping (frequency, filter cutoff, gain).
     *
     * @param min Output minimum (inclusive)
     * @param max Output maximum (inclusive)
     * @param curve Shape preset or arbitrary value (see sbl::dsp::curve)
     * @return Scaled value in [min, max]
     */
    int32_t scaled_curved(int32_t min, int32_t max,
                          uint16_t curve = dsp::curve::Log) const {
        uint16_t warped = dsp::ExpCurveWarp::warp(filter_.value(), curve);
        int64_t v = warped;
        return static_cast<int32_t>(min + (v * (max - min)) / 65535);
    }
 
    /** @brief Reset filter state */
    void reset() {
        filter_.reset();
        raw_ = 0;
    }
 
private:
    primitives::math::Ewma filter_;
    uint16_t raw_;
};
 
} // namespace cv
} // namespace components
} // namespace sbl
 
#endif // SBL_COMPONENTS_CV_INPUT_HPP_