voct.hpp

Go to the documentation of this file.

/**
 * @file voct.hpp
 * @brief V/Oct input component — calibrated pitch CV from ADC values
 * @ingroup components
 *
 * VoctInput chains CvInput (EWMA smoothing) with a linear calibration
 * to convert raw ADC values into musical pitch. The calibration maps
 * ADC values to MIDI note numbers (semitones), then pitch tables
 * convert to frequency, ratio, or phase increment.
 *
 * Pipeline:
 *   ADC raw → CvInput (EWMA) → calibration (scale + offset) → semitones
 *                                                                  ↓
 *                        phase_increment ← frequency ← pitch tables
 *
 * Usage:
 *   sbl::components::cv::VoctInput voct;
 *   voct.update(raw_adc_value);
 *   float freq = voct.frequency();          // Hz
 *   uint32_t inc = voct.phase_increment(48000.0f);
 */
 
#ifndef SBL_COMPONENTS_CV_VOCT_HPP_
#define SBL_COMPONENTS_CV_VOCT_HPP_
 
#include <cstdint>
#include <sbl/components/cv/input.hpp>
#include <sbl/dsp/pitch.hpp>
 
namespace sbl {
namespace components {
namespace cv {
 
/**
 * @brief Linear calibration parameters for V/Oct conversion
 *
 * Maps smoothed ADC value to MIDI note number:
 *   note = adc_value * scale + offset
 */
struct VoctCalibration {
    float scale;    ///< Semitones per ADC unit
    float offset;   ///< MIDI note number at ADC=0
 
    /**
     * @brief Default calibration for 0–3.3V input, 1V/Oct, 16-bit ADC
     *
     * 3.3V × 12 semitones/V = 39.6 semitones across full ADC range.
     * Base note C1 (MIDI 24) at ADC=0.
     */
    static constexpr VoctCalibration default_3v3() {
        return { 39.6f / 65535.0f, 24.0f };
    }
 
    /**
     * @brief Compute calibration from two known points
     *
     * Apply known voltages, read the ADC values, and provide the
     * expected MIDI note at each point. Scale and offset are derived
     * from the two-point linear fit.
     *
     * @param adc_low   ADC reading at the low calibration voltage
     * @param note_low  Expected MIDI note at the low point
     * @param adc_high  ADC reading at the high calibration voltage
     * @param note_high Expected MIDI note at the high point
     */
    static constexpr VoctCalibration from_two_point(
        uint16_t adc_low, float note_low,
        uint16_t adc_high, float note_high)
    {
        float s = (note_high - note_low) /
                  static_cast<float>(adc_high - adc_low);
        float o = note_low - s * static_cast<float>(adc_low);
        return { s, o };
    }
};
 
/**
 * @brief V/Oct pitch CV input with smoothing and calibration
 *
 * Owns a CvInput for EWMA smoothing and stores calibration state.
 * Hardware-agnostic — takes raw ADC values, no driver calls.
 */
/**
 * @brief V/Oct pitch CV input with smoothing, calibration, and pitch conversion
 *
 * @note All public methods are ISR-safe — pure state machine with no hardware I/O.
 */
class VoctInput {
public:
    explicit VoctInput(VoctCalibration cal = VoctCalibration::default_3v3(),
                       Smoothing smoothing = Smoothing::Light)
        : cv_(smoothing), cal_(cal) {}
 
    /** @brief Feed a new raw ADC sample */
    void update(uint16_t raw) {
        cv_.update(raw);
    }
 
    /** @brief Replace calibration at runtime */
    void set_calibration(VoctCalibration cal) {
        cal_ = cal;
    }
 
    /** @brief Current calibration */
    const VoctCalibration& calibration() const { return cal_; }
 
    /** @brief MIDI note number (float) from calibrated input */
    float semitones() const {
        return static_cast<float>(cv_.value()) * cal_.scale + cal_.offset;
    }
 
    /** @brief Frequency in Hz (via pitch tables) */
    float frequency() const {
        return dsp::note_to_frequency(semitones());
    }
 
    /** @brief Frequency ratio relative to A4 (440 Hz) */
    float ratio() const {
        return dsp::note_to_ratio(semitones());
    }
 
    /** @brief Phase increment for wavetable oscillator */
    uint32_t phase_increment(float sample_rate) const {
        return dsp::note_to_phase_increment(semitones(), sample_rate);
    }
 
    /** @brief Last raw (unfiltered) ADC value */
    uint16_t raw() const { return cv_.raw(); }
 
    /** @brief Current smoothed ADC value (0–65535) */
    uint16_t value() const { return cv_.value(); }
 
    /** @brief Reset filter state */
    void reset() { cv_.reset(); }
 
private:
    CvInput cv_;
    VoctCalibration cal_;
};
 
} // namespace cv
} // namespace components
} // namespace sbl
 
#endif // SBL_COMPONENTS_CV_VOCT_HPP_