pot.hpp

Go to the documentation of this file.

/**
 * @file pot.hpp
 * @brief Potentiometer component — smoothed, calibrated ADC with su output
 * @ingroup components
 *
 * Pot is a source adapter (L1/L2, FDP-072): raw ADC counts in, normalized
 * signal units out. Pipeline: raw → EWMA (raw domain) → two-point
 * calibration → su [0, 1]. Deadband operates in su.
 *
 * 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::input::Pot knob;
 *   knob.update_dma(adc_buf, 0);
 *   if (knob.changed()) { apply(knob.value()); }   // deadbanded su
 *   widget.set_cutoff_su(knob.smoothed());         // full-resolution su
 */
 
#ifndef SBL_HW_COMPONENTS_INPUT_POT_HPP_
#define SBL_HW_COMPONENTS_INPUT_POT_HPP_
 
#include <cstdint>
#include <sbl/hw/util/ewma.hpp>
#include <sbl/hw/components/cv/input.hpp>
#include <sbl/hw/components/input/pot_calibration.hpp>
 
namespace sbl {
namespace components {
namespace input {
 
struct PotConfig {
    cv::Smoothing smoothing = cv::Smoothing::Medium;
    float deadband = 0.001f;   ///< su — ~64 counts of a 16-bit span
};
 
/**
 * @brief Potentiometer with EWMA smoothing, calibration and deadband
 *
 * @note All public methods are ISR-safe — pure state machine, no hardware
 *       I/O; 32-bit stores are atomic on Cortex-M. Call update from exactly
 *       one context.
 */
class Pot {
public:
    explicit Pot(const PotConfig& config = {})
        : filter_(static_cast<uint8_t>(config.smoothing)),
          deadband_(config.deadband) {}
 
    /** @brief Feed a new raw ADC sample through EWMA → calibration → deadband */
    void update(uint16_t raw) {
        raw_ = raw;
        filter_.update(raw);
        float s = smoothed();
 
        float delta = s - stable_value_;
        if (delta < 0.0f) delta = -delta;
        if (delta >= deadband_) {
            stable_value_ = s;
            changed_ = true;
        }
    }
 
    /** @brief Read one channel from a DMA scan buffer and update (ISR-safe) */
    void update_dma(const uint16_t* buffer, uint8_t channel_index) {
        update(static_cast<const volatile uint16_t*>(buffer)[channel_index]);
    }
 
    /** @brief Stable (deadbanded) value in su [0, 1] */
    float value() const { return stable_value_; }
 
    /**
     * @brief Calibrated, smoothed value in su [0, 1] — no deadband
     *
     * Use for parameters driven unconditionally (no changed() gate):
     * full resolution, no deadband quantization steps.
     */
    float smoothed() const {
        return static_cast<float>(calibration_.normalize(filter_.value())) *
               (1.0f / static_cast<float>(PotCalibration::kOutputMax));
    }
 
    /** @brief Last raw (unfiltered) ADC count — for calibration routines */
    uint16_t raw() const { return raw_; }
 
    /** @brief Apply two-point calibration */
    void set_calibration(PotCalibration cal) { calibration_ = cal; }
 
    /**
     * @brief True if value moved past deadband since last check
     *
     * Resets the flag on read — call once per update cycle.
     */
    bool changed() {
        bool c = changed_;
        changed_ = false;
        return c;
    }
 
    /** @brief Override deadband threshold in su (default: 0.001) */
    void set_deadband(float deadband_su) { deadband_ = deadband_su; }
 
    /** @brief Reset all state (filter, stable value, changed flag) */
    void reset() {
        filter_.reset();
        raw_ = 0;
        stable_value_ = 0.0f;
        changed_ = false;
    }
 
private:
    primitives::math::Ewma filter_;
    PotCalibration calibration_;
    uint16_t raw_ = 0;
    float deadband_;
    float stable_value_ = 0.0f;
    bool changed_ = false;
};
 
} // namespace input
} // namespace components
} // namespace sbl
 
#endif // SBL_HW_COMPONENTS_INPUT_POT_HPP_