OverSample.h

/*
 * OverSample.h
 *
 * This file is part of Mozzi.
 *
 * Copyright 2013-2024 Tim Barrass and the Mozzi Team
 *
 * Mozzi is licensed under the GNU Lesser General Public Licence (LGPL) Version 2.1 or later.
 *
 */
 
#ifndef OVERSAMPLE_H
#define OVERSAMPLE_H
 
#include "RollingAverage.h"
 
 
/** @ingroup sensortools
    Enables the resolution of analog inputs to be increased by oversampling and decimation.
    Noise should be added to the input before it's digitised, then a succession of input readings are summed and 
    finally divided to give a number with greater resolution than the ADC.  
    Often, noise in the Arduino system will be enough, but there are other practical methods described in 
    [Enhancing ADC Resolution by Oversampling](http://www.atmel.com/images/doc8003.pdf‎),
    as well as an explanation of the overall approach.
    @tparam RESOLUTION_INCREASE_BITS how many extra bits of resolution to produce.
    The window length and the memory it needs increases quickly as the oversampling resolution increases.  
    1 bit = 4 unsigned ints (analog input between 0-1023) = 8 uint8_ts,
    2 bits = 16 unsigned ints = 32 uint8_ts,  
    3 bits = 64 unsigned ints = 128 uint8_ts,
    More than 3 bits increase in resolution would require either using longs to store the readings,
    which would need 1024 uint8_ts for a 4 bit increase and 4096 uint8_ts for 5 bits (do any avr's have that much room?),
    or the average reading would have to be no more than 128 (for 4 bits increase), because 256 readings would be needed,
    and the sum of all 256 readings would have to fit into an int.  (32767 / 256 = 128).
    Changing OverSample to use unsigned ints could enable an average reading of 256, but isn't tested properly yet.
    @note The higher the resolution, the more lag there will be.
    It's almost a RollingAverage filter, with the difference that 
    OverSample doesn't divide by as much as you would for an average.
*/
 
 
template <class T, const uint8_t RESOLUTION_INCREASE_BITS>
class OverSample: public RollingAverage<T, (1<<(RESOLUTION_INCREASE_BITS*2))>
{
 
public:
    using RollingAverage<T, (1<<(RESOLUTION_INCREASE_BITS*2))>::add;
 
    /** Oversample and decimate the input to increase resolution by RESOLUTION_INCREASE_BITS;
    @param input an analog input to oversample.
    @return the higher resolution result.
    @note timing 5.7us
    */
    T next(T input)
    {
        return add(input)>>RESOLUTION_INCREASE_BITS;
    }
 
};
 
 
/**
@example 05.Control_Filters/Thermistor_OverSample/Thermistor_OverSample.ino
This is an example demonstrating the OverSample class.
*/
 
#endif        //  #ifndef OVERSAMPLE_H