input.hpp

Go to the documentation of this file.

/**
 * @file input.hpp
 * @brief CV Input component — smoothed ADC reading with su output (FDP-072)
 * @ingroup components
 *
 * CvInput is a source adapter (L1/L2): it takes raw ADC counts, applies EWMA
 * smoothing in the raw domain, and emits normalized signal units at its
 * output — the transport contract of ADR-011 D2. The jack's musical role
 * (unipolar / bipolar / V/Oct) is a structural parameter with a sensible
 * default; conditioning constants live in one code-owned struct with named
 * presets. Per-mode runtime remapping is a first-class pattern.
 *
 * Acquisition is owned by the component: feed values with update(), or read
 * straight from a DMA scan buffer with update_dma() (ISR-safe).
 *
 * Usage:
 *   sbl::components::cv::CvInput jack{sbl::components::cv::Smoothing::Light};
 *   jack.set_conditioning(CvConditioning::from(sbl::hw::electrical::cv_5));  // Board::init() does this for you
 *   jack.set_mapping(CvMapping::VOct);
 *   jack.update_dma(adc_buf, 4);
 *   float pitch_offset = jack.value();   // su
 */
 
#ifndef SBL_HW_COMPONENTS_CV_INPUT_HPP_
#define SBL_HW_COMPONENTS_CV_INPUT_HPP_
 
#include <cstdint>
#include <sbl/hw/util/ewma.hpp>
#include <sbl/hw/hal/adc/electrical.hpp>
 
namespace sbl {
namespace components {
namespace cv {
 
/**
 * @brief Smoothing presets for the raw-domain EWMA filter
 *
 * Values are the EWMA shift exponent (alpha = 1/2^shift).
 */
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)
};
 
/**
 * @brief Musical interpretation of the jack — a structural parameter
 *
 * Runtime-settable; remapping per mode is supported. Mapping applies at the
 * output stage, so remaps are glitch-free with respect to filter state.
 * su-domain state derived from the old mapping (pickup targets, stored
 * positions) must be re-armed by the app on remap.
 */
enum class CvMapping : uint8_t {
    Unipolar,  ///< [0, 1] — full ADC span (default)
    Bipolar,   ///< [-1, 1] — around the conditioned midpoint
    VOct,      ///< su pitch offset — 1 V/oct, 8 octaves per 1.0 su, unclamped
};
 
/**
 * @brief Conditioning constants — one code-owned home (ADR-011 D2)
 *
 * Describes the analog front end between the jack and the ADC. Defaults
 * describe a plain 16-bit unipolar input; use a named preset (or set your
 * own values once at init) when your hardware differs. This replaces the
 * scattered app-side magic numbers that drifted apart (RPT-026).
 */
struct CvConditioning {
    float counts_max      = 65535.0f;  ///< Full-scale ADC count
    float midpoint        = 32768.0f;  ///< Count at 0 V (bipolar conditioning)
    bool  inverted        = false;     ///< Conditioning op-amp inverts (+V → lower count)
    float counts_per_volt = 6553.5f;   ///< Counts per volt (16-bit over ±5 V)
 
    /// Derive from a port's electrical description (generated by sloth into
    /// sbl::hw::electrical from the hardware manifest — the one owner of these facts).
    static constexpr CvConditioning from(const sbl::hal::adc::Electrical& e) {
        return {e.counts_max(), static_cast<float>(e.midpoint()), e.inverted, e.counts_per_volt()};
    }
};
 
struct CvInputConfig {
    Smoothing smoothing = Smoothing::Medium;
};
 
/**
 * @brief Smoothed CV input emitting normalized signal units
 *
 * @note update()/update_dma() are ISR-safe (pure state machine, atomic
 *       32-bit EWMA state on Cortex-M). Call update from exactly one
 *       context; getters are safe from another.
 */
class CvInput {
public:
    /// Pitch-su convention: 1.0 su spans 8 octaves (MIDI 24–120), 1 V/oct.
    static constexpr float kSuPerVolt = 0.125f;
 
    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 Read one channel from a DMA scan buffer and update
     *
     * Volatile cast forces a real memory read — DMA updates the buffer
     * asynchronously. ISR-safe, non-blocking.
     */
    void update_dma(const uint16_t* buffer, uint8_t channel_index) {
        update(static_cast<const volatile uint16_t*>(buffer)[channel_index]);
    }
 
    /** @brief Last raw (unfiltered) ADC count — for calibration routines */
    uint16_t raw() const { return raw_; }
 
    /** @brief Smoothed output in signal units, per the configured mapping */
    float value() const { return map(filter_.value()); }
 
    /** @brief Set the jack's musical role (structural; runtime-remappable) */
    void set_mapping(CvMapping mapping) { mapping_ = mapping; }
 
    CvMapping mapping() const { return mapping_; }
 
    /** @brief Set the analog front-end description (once at init, typically) */
    void set_conditioning(const CvConditioning& cond) { cond_ = cond; }
 
    const CvConditioning& conditioning() const { return cond_; }
 
    /** @brief Change smoothing level without resetting filter state */
    void set_smoothing(Smoothing smoothing) {
        filter_.set_shift(static_cast<uint8_t>(smoothing));
    }
 
    /** @brief Reset filter state */
    void reset() {
        filter_.reset();
        raw_ = 0;
    }
 
private:
    float map(uint16_t counts) const {
        float c = static_cast<float>(counts);
        switch (mapping_) {
        case CvMapping::Unipolar: {
            float t = c / cond_.counts_max;
            if (cond_.inverted) t = 1.0f - t;
            return (t < 0.0f) ? 0.0f : (t > 1.0f) ? 1.0f : t;
        }
        case CvMapping::Bipolar: {
            float b = (c - cond_.midpoint) / cond_.midpoint;
            if (cond_.inverted) b = -b;
            return (b < -1.0f) ? -1.0f : (b > 1.0f) ? 1.0f : b;
        }
        case CvMapping::VOct: {
            // Offset semantics: unclamped — the receiving port clamps.
            float volts = (c - cond_.midpoint) / cond_.counts_per_volt;
            if (cond_.inverted) volts = -volts;
            return volts * kSuPerVolt;
        }
        }
        return 0.0f;
    }
 
    primitives::math::Ewma filter_;
    uint16_t raw_;
    CvMapping mapping_ = CvMapping::Unipolar;
    CvConditioning cond_{};
};
 
} // namespace cv
} // namespace components
} // namespace sbl
 
#endif // SBL_HW_COMPONENTS_CV_INPUT_HPP_