calibration.hpp

Go to the documentation of this file.

// sbl/control/calibration.hpp — Source calibration: fit, standard, routine (AP-033)
//
// A source reads a little off: a CV jack's divider is 2% high, its op-amp
// offset puts 0 V at 0.003 su. Calibration measures the source against known
// references and stores the correction as a line — scale and offset — that
// the app applies to every later reading.
//
//   LinearFit          the correction: apply(measured) = measured * scale + offset
//   fit_points()       least squares over 2..N captured points
//   VOctStandard       what a reference means in su (1 V per octave)
//   PointCalibration   the routine: begin, capture, capture, done
//
// One shape drives every calibration an app runs — a button calls advance(),
// another cancel(), and the UI slot polls state() for the LED. The library
// holds no storage: fit() is POD, and the app writes it wherever it keeps
// its calibration (CAL.BIN today).
//
// Usage — two-point V/Oct on a 1 V and 3 V reference:
//   constexpr float kRefs[] = {1.0f, 3.0f};            // volts
//   sbl::control::PointCalibration<2> cal{kRefs};
//
//   cal.begin();                                        // button: start
//   cal.capture(jack.value());                          // button: patch 1 V, capture
//   cal.capture(jack.value());                          // button: patch 3 V, capture → Done
//   float pitch = cal.apply(jack.value());              // corrected, from now on
//
// Loading a stored fit skips the routine entirely: cal.set_fit(saved).
 
#ifndef SBL_CONTROL_CALIBRATION_HPP_
#define SBL_CONTROL_CALIBRATION_HPP_
 
#include <cstdint>
 
namespace sbl::control {
 
// ─── The correction ──────────────────────────────────────────────────
 
/// measured su → corrected su. Identity until a fit is computed or loaded.
struct LinearFit {
    float scale = 1.0f;
    float offset = 0.0f;
 
    constexpr float apply(float measured_su) const { return measured_su * scale + offset; }
};
 
/**
 * @brief Least-squares line through captured points
 *
 * @param measured  what the source read at each reference
 * @param expected  what it should have read (the standard's answer)
 * @param n         2 or more
 * @param out       the fit, untouched when the points are degenerate
 * @return false if n < 2 or every measurement is the same value
 */
inline bool fit_points(const float* measured, const float* expected, uint8_t n,
                       LinearFit& out) {
    if (n < 2) return false;
 
    float sum_x = 0.0f, sum_y = 0.0f;
    for (uint8_t i = 0; i < n; ++i) {
        sum_x += measured[i];
        sum_y += expected[i];
    }
    const float inv_n = 1.0f / static_cast<float>(n);
    const float mean_x = sum_x * inv_n;
    const float mean_y = sum_y * inv_n;
 
    float cov = 0.0f, var = 0.0f;
    for (uint8_t i = 0; i < n; ++i) {
        const float dx = measured[i] - mean_x;
        cov += dx * (expected[i] - mean_y);
        var += dx * dx;
    }
    if (var <= 1e-12f) return false;   // every point read the same: no line
 
    out.scale = cov / var;
    out.offset = mean_y - out.scale * mean_x;
    return true;
}
 
// ─── What a reference means ──────────────────────────────────────────
 
/**
 * @brief 1 V per octave in SBL pitch su (1.0 su spans 8 octaves)
 *
 * References are volts. A standard with a different law — 1.2 V per octave,
 * or a Hz-per-volt input — supplies its own `expected_su`.
 */
struct VOctStandard {
    static constexpr float kSuPerVolt = 0.125f;
    static constexpr float expected_su(float volts) { return volts * kSuPerVolt; }
};
 
// ─── The routine ─────────────────────────────────────────────────────
 
enum class CalState : uint8_t {
    Idle,       ///< not calibrating; fit() is whatever was loaded or measured
    Capturing,  ///< waiting for the next reference point
    Done,       ///< a fit was computed; accept() or cancel()
    Failed,     ///< the points were degenerate; cancel() to restore
};
 
/**
 * @brief Capture N reference points, then fit
 *
 * The app decides when a reading has settled and calls capture() with the
 * source's current su. The last capture computes the fit. cancel() restores
 * the fit that was in force when begin() was called, so an abandoned
 * calibration costs nothing.
 */
template<uint8_t N, typename Standard = VOctStandard>
class PointCalibration {
    static_assert(N >= 2, "a line needs two points");
 
public:
    /// @param references the reference values, in the standard's units
    explicit PointCalibration(const float (&references)[N]) {
        for (uint8_t i = 0; i < N; ++i) references_[i] = references[i];
    }
 
    /// Start capturing at point 0, remembering the current fit.
    void begin() {
        backup_ = fit_;
        point_ = 0;
        state_ = CalState::Capturing;
    }
 
    /**
     * @brief Record the source's reading for the current reference
     * @return true when this capture completed the calibration
     */
    bool capture(float measured_su) {
        if (state_ != CalState::Capturing) return false;
        measured_[point_] = measured_su;
        ++point_;
        if (point_ < N) return false;
 
        float expected[N];
        for (uint8_t i = 0; i < N; ++i) expected[i] = Standard::expected_su(references_[i]);
 
        LinearFit fitted;
        if (fit_points(measured_, expected, N, fitted)) {
            fit_ = fitted;
            state_ = CalState::Done;
        } else {
            state_ = CalState::Failed;
        }
        return true;
    }
 
    /// Leave the routine, keeping the new fit (the app persists it).
    void accept() {
        if (state_ == CalState::Done) state_ = CalState::Idle;
    }
 
    /// Abandon: restore the fit from before begin().
    void cancel() {
        fit_ = backup_;
        state_ = CalState::Idle;
        point_ = 0;
    }
 
    /// Correct a reading. Identity until a fit is computed or loaded.
    float apply(float measured_su) const { return fit_.apply(measured_su); }
 
    CalState state() const { return state_; }
    bool active() const { return state_ == CalState::Capturing; }
 
    /// Points captured so far — the reference to patch next, for the UI.
    uint8_t point() const { return point_; }
    static constexpr uint8_t points() { return N; }
 
    /// The reference the app should patch for the current point.
    float reference() const { return references_[point_ < N ? point_ : N - 1]; }
 
    const LinearFit& fit() const { return fit_; }
 
    /// Load a stored fit (boot) or install one by hand.
    void set_fit(const LinearFit& fit) { fit_ = fit; }
 
private:
    float references_[N]{};
    float measured_[N]{};
    LinearFit fit_{};
    LinearFit backup_{};
    uint8_t point_ = 0;
    CalState state_ = CalState::Idle;
};
 
} // namespace sbl::control
 
#endif // SBL_CONTROL_CALIBRATION_HPP_