ewma.hpp

Go to the documentation of this file.

/**
 * @file ewma.hpp
 * @brief Exponentially Weighted Moving Average filter
 * @ingroup primitives
 *
 * Integer-only EWMA with Q16 internal state for sub-LSB precision.
 * Uses power-of-2 shift for the smoothing factor (no division).
 * Suitable for Cortex-M0+ (no FPU required).
 *
 * Alpha = 1 / 2^shift:
 *   shift=1 → alpha=1/2  (fast tracking, little smoothing)
 *   shift=3 → alpha=1/8  (good default for pots)
 *   shift=5 → alpha=1/32 (heavy smoothing)
 *
 * Usage:
 *   sbl::primitives::math::Ewma filter(3);
 *   uint16_t smoothed = filter.update(raw_adc_value);
 */
 
#ifndef SBL_HW_UTIL_EWMA_HPP_
#define SBL_HW_UTIL_EWMA_HPP_
 
#include <cstdint>
 
namespace sbl {
namespace primitives {
namespace math {
 
class Ewma {
public:
    /**
     * @brief Construct EWMA filter
     * @param shift Smoothing exponent (alpha = 1/2^shift). Range: 1–15.
     */
    explicit Ewma(uint8_t shift = 3) : shift_(shift), state_(0), primed_(false) {}
 
    /**
     * @brief Feed a new sample and return the smoothed value
     *
     * First call seeds the filter (no smoothing on first sample).
     * Internal state uses Q16 fixed-point for sub-LSB precision.
     *
     * @param raw Raw input value (16-bit)
     * @return Smoothed output (16-bit)
     */
    uint16_t update(uint16_t raw) {
        uint32_t input_q16 = static_cast<uint32_t>(raw) << 16;
 
        if (!primed_) {
            state_ = input_q16;
            primed_ = true;
        } else {
            // EWMA: state += (input - state) >> shift
            // Signed delta handles both directions correctly
            int32_t delta = static_cast<int32_t>(input_q16 - state_);
            state_ += static_cast<uint32_t>(delta >> shift_);
        }
 
        return static_cast<uint16_t>(state_ >> 16);
    }
 
    /** @brief Return current smoothed value without updating */
    uint16_t value() const {
        return static_cast<uint16_t>(state_ >> 16);
    }
 
    /** @brief Change smoothing exponent without resetting filter state */
    void set_shift(uint8_t shift) { shift_ = shift; }
 
    /** @brief Reset filter state (next update will re-seed) */
    void reset() {
        state_ = 0;
        primed_ = false;
    }
 
private:
    uint8_t  shift_;
    uint32_t state_;    // Q16 fixed-point accumulator (32-bit aligned → atomic on Cortex-M)
    bool     primed_;
    // Atomicity note: On Cortex-M, 32-bit aligned reads/writes are atomic.
    // It is safe to call update() from an ISR and value() from the main loop
    // (or vice versa), provided only one context calls update() on a given
    // instance. Do not call update() from multiple contexts simultaneously.
};
 
} // namespace math
} // namespace primitives
} // namespace sbl
 
#endif // SBL_HW_UTIL_EWMA_HPP_