pot_calibration.hpp

Go to the documentation of this file.

// sbl/hw/components/input/pot_calibration.hpp — Two-point ADC calibration
//
// Maps raw ADC readings to a normalized integer range using measured endpoint
// values. Handles inverted ADC layouts (high raw = CCW) and clamps output.
// Uses uint32_t to support any ADC resolution (12-bit, 16-bit, 24-bit).
//
// The I/O stack stays integer — float conversion happens at the stack boundary.
//
// Usage:
//   auto cal = PotCalibration::from_two_point(ccw_reading, cw_reading);
//   uint32_t t = cal.normalize(raw_adc);  // [0, 65535]
//
//   // Float conversion at stack boundary
//   float su = t * (1.0f / 65535.0f);
//
// See FDP-035 for design rationale.
 
#ifndef SBL_HW_COMPONENTS_INPUT_POT_CALIBRATION_HPP_
#define SBL_HW_COMPONENTS_INPUT_POT_CALIBRATION_HPP_
 
#include <cstdint>
 
namespace sbl::components::input {
 
struct PotCalibration {
    static constexpr uint32_t kOutputMax = 65535;
 
    uint32_t raw_min = 0;       ///< ADC reading at logical minimum (CCW after inversion)
    uint32_t raw_max = 65535;   ///< ADC reading at logical maximum (CW after inversion)
    bool inverted = false;      ///< true if high ADC value = CCW (knob turned left)
 
    /// Normalize raw ADC reading to [0, kOutputMax], clamped.
    uint32_t normalize(uint32_t raw) const {
        if (raw_max <= raw_min) return 0;
        uint32_t clamped = raw;
        if (clamped < raw_min) clamped = raw_min;
        if (clamped > raw_max) clamped = raw_max;
        uint32_t val = clamped - raw_min;
        uint32_t range = raw_max - raw_min;
        uint32_t result = static_cast<uint32_t>(
            (static_cast<uint64_t>(val) * kOutputMax) / range);
        return inverted ? (kOutputMax - result) : result;
    }
 
    /// Build calibration from measured CCW and CW ADC readings.
    /// Automatically detects inversion (if CCW reading > CW reading).
    static PotCalibration from_two_point(uint32_t ccw_reading, uint32_t cw_reading) {
        bool inv = ccw_reading > cw_reading;
        return {
            inv ? cw_reading  : ccw_reading,
            inv ? ccw_reading : cw_reading,
            inv
        };
    }
 
    /// Default for Daisy Patch.init() (inverted, ~0–33000 range).
    static constexpr PotCalibration default_patch_init() {
        return { 0, 33000, true };
    }
 
    /// Default full-range (no calibration needed).
    static constexpr PotCalibration default_full_range() {
        return { 0, 65535, false };
    }
};
 
} // namespace sbl::components::input
 
#endif // SBL_HW_COMPONENTS_INPUT_POT_CALIBRATION_HPP_