pot.hpp

Go to the documentation of this file.

/**
 * @file pot.hpp
 * @brief Potentiometer component — smoothed ADC with deadband + change detection
 * @ingroup components
 *
 * Pot wraps CvInput (EWMA smoothing) and adds deadband suppression so that
 * small ADC noise doesn't register as parameter changes. After EWMA filtering,
 * the stable value only updates when the smoothed reading moves past the
 * deadband threshold.
 *
 * ## Pickup mode
 *
 * For multi-mode control mappings where the same knob controls different
 * parameters depending on held buttons, call set_pickup(target) on mode
 * switch. The output freezes at `target` until the physical knob crosses
 * that value, then resumes normal tracking. This prevents parameter jumps.
 *
 * Usage:
 *   sbl::components::control::Pot knob;
 *   knob.update(raw_adc_value);
 *   int32_t freq = knob.scaled(20, 20000);
 *   if (knob.changed()) { ... value moved past deadband ... }
 *
 *   // On mode switch:
 *   knob.set_pickup(saved_position);    // freeze until knob catches up
 *   if (!knob.picked_up()) { ... show LED feedback ... }
 */
 
#ifndef SBL_COMPONENTS_CONTROL_POT_HPP_
#define SBL_COMPONENTS_CONTROL_POT_HPP_
 
#include <cstdint>
#include <sbl/components/cv/input.hpp>
#include <sbl/dsp/warp.hpp>
 
namespace sbl {
namespace components {
namespace control {
 
struct PotConfig {
    cv::Smoothing smoothing = cv::Smoothing::Medium;
    uint16_t deadband = 64;
};
 
/**
 * @brief Potentiometer with EWMA smoothing, deadband, and change detection
 *
 * @note All public methods are ISR-safe — pure state machine with no hardware I/O.
 */
class Pot {
public:
    explicit Pot(const PotConfig& config = {})
        : input_(config.smoothing), deadband_(config.deadband),
          stable_value_(0), changed_(false) {}
 
    /**
     * @brief Feed a new raw ADC sample through EWMA → deadband check
     *
     * The EWMA filter smooths the raw value first. Then, if the smoothed
     * value has moved more than `deadband` from the last stable value,
     * we update the stable value and set the changed flag.
     *
     * When pickup is armed, the EWMA filter tracks the physical position
     * but stable_value_ stays frozen until the knob crosses the target.
     */
    void update(uint16_t raw) {
        input_.update(raw);
        uint16_t smoothed = input_.value();
 
        if (pickup_armed_) {
            bool now_above = smoothed > pickup_target_;
            bool crossed = (pickup_above_ && !now_above) ||
                           (!pickup_above_ && now_above);
 
            // Also pick up if we're within the deadband of the target
            int32_t dist = static_cast<int32_t>(smoothed) -
                           static_cast<int32_t>(pickup_target_);
            if (dist < 0) dist = -dist;
            if (crossed || static_cast<uint16_t>(dist) <= deadband_) {
                pickup_armed_ = false;
                stable_value_ = smoothed;
                changed_ = true;
            }
            return;
        }
 
        int32_t delta = static_cast<int32_t>(smoothed) - static_cast<int32_t>(stable_value_);
        if (delta < 0) delta = -delta;
 
        if (static_cast<uint16_t>(delta) >= deadband_) {
            stable_value_ = smoothed;
            changed_ = true;
        }
    }
 
    /** @brief Current stable (deadbanded) value (0-65535) */
    uint16_t value() const { return stable_value_; }
 
    /** @brief Last raw (unfiltered) ADC value */
    uint16_t raw() const { return input_.raw(); }
 
    /**
     * @brief Map stable value to an output range (linear)
     *
     * Linear interpolation from [0, 65535] -> [min, max].
     * Uses int64_t intermediate to avoid overflow.
     * For non-linear mapping (frequency, filter cutoff), see scaled_curved().
     */
    int32_t scaled(int32_t min, int32_t max) const {
        int64_t v = stable_value_;
        return static_cast<int32_t>(min + (v * (max - min)) / 65535);
    }
 
    /**
     * @brief Map stable value with curve shaping
     *
     * Applies ExpCurveWarp::warp() before scaling, useful for knob-friendly
     * non-linear mapping (frequency, filter cutoff, gain).
     *
     * @param min Output minimum (inclusive)
     * @param max Output maximum (inclusive)
     * @param curve Shape preset or arbitrary value (see sbl::dsp::curve)
     * @return Scaled value in [min, max]
     */
    int32_t scaled_curved(int32_t min, int32_t max,
                          uint16_t curve = sbl::dsp::curve::Log) const {
        uint16_t warped = sbl::dsp::ExpCurveWarp::warp(stable_value_, curve);
        int64_t v = warped;
        return static_cast<int32_t>(min + (v * (max - min)) / 65535);
    }
 
    /**
     * @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 Arm pickup mode — freeze output until knob crosses target
     *
     * The physical knob must cross `target` (a raw 0-65535 position)
     * before stable_value_ resumes tracking. Until then, value(),
     * scaled(), and scaled_curved() all return values based on `target`.
     *
     * Use on mode switch: save the current knob position per-mode,
     * then set_pickup(saved_position) when re-entering that mode.
     *
     * @param target The knob position (0-65535) that must be crossed
     */
    void set_pickup(uint16_t target) {
        uint16_t smoothed = input_.value();
        int32_t dist = static_cast<int32_t>(smoothed) -
                       static_cast<int32_t>(target);
        if (dist < 0) dist = -dist;
 
        // Already at target — no need to arm
        if (static_cast<uint16_t>(dist) <= deadband_) {
            stable_value_ = smoothed;
            return;
        }
 
        pickup_target_ = target;
        pickup_above_ = smoothed > target;
        pickup_armed_ = true;
        stable_value_ = target;  // freeze output at target
    }
 
    /** @brief True if knob has caught up (or pickup was never armed) */
    bool picked_up() const { return !pickup_armed_; }
 
    /** @brief Cancel pickup, resume normal tracking immediately */
    void clear_pickup() { pickup_armed_ = false; }
 
    /** @brief Reset all state (filter, stable value, changed flag, pickup) */
    void reset() {
        input_.reset();
        stable_value_ = 0;
        changed_ = false;
        pickup_armed_ = false;
    }
 
private:
    cv::CvInput input_;
    uint16_t deadband_;
    uint16_t stable_value_;
    uint16_t pickup_target_ = 0;
    bool changed_;
    bool pickup_armed_ = false;
    bool pickup_above_ = false;
};
 
} // namespace control
} // namespace components
} // namespace sbl
 
#endif // SBL_COMPONENTS_CONTROL_POT_HPP_