RollingCounter.h

 
// RollingCounter.h
//
// Base class for rolling counter implementations (RainGauge, Lightning, etc.)
// Provides common functionality for history buffer management and calculations
//
// https://github.com/matthias-bs/BresserWeatherSensorReceiver
//
//
// created: 02/2026
//
//
// MIT License
//
// Copyright (c) 2026 Matthias Prinke
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
//
// History:
//
// 20260211 Created from common code in RainGauge and Lightning
// 20260221 Improved generalization, documentation, and code deduplication
//
// ToDo:
// -
//
#ifndef _ROLLINGCOUNTER_H
#define _ROLLINGCOUNTER_H
 
#if defined(ESP32) || defined(ESP8266)
#include <sys/time.h>
#else
#include <time.h>
#include <stdint.h>
#include <stddef.h>
#endif
 
#define ROLLING_COUNTER_UPD_RATE 6
 
#define DEFAULT_QUALITY_THRESHOLD 0.8
 
class RollingCounter
{
protected:
    float qualityThreshold;
    time_t lastUpdate;
    uint8_t updateRate;
 
    typedef void (*HistInitCallback)();
 
    enum UpdateResult
    {
        UPDATE_SUCCESS, 
        UPDATE_EXPIRED  
    };
 
    typedef struct
    {
        int16_t *hist;      // pointer to buffer
        size_t size;        // number of bins
        uint8_t updateRate; // minutes per bin
    } History;
 
    int calculateIndex(const struct tm &tm, uint8_t rate) const;
 
    void markMissedEntries(int16_t *hist, size_t size, time_t lastUpdate,
                           time_t timestamp, uint8_t rate);
 
    UpdateResult updateHistoryBufferCore(int16_t *hist, size_t size, int idx, int16_t delta,
                                         time_t t_delta, time_t timestamp, time_t lastUpdate,
                                         uint8_t updateRate);
 
    void updateHistoryBuffer(int16_t *hist, size_t size, int idx, int16_t delta,
                             time_t t_delta, time_t timestamp, time_t lastUpdate,
                             uint8_t updateRate);
 
    virtual void hist_init(int16_t value = -1) = 0;
 
    float sumHistory(const History &h, bool *valid = nullptr, int *nbins = nullptr,
                     float *quality = nullptr, float scale = 1.0);
 
public:
    RollingCounter(const float quality_threshold = DEFAULT_QUALITY_THRESHOLD) : qualityThreshold(quality_threshold),
                                                                                lastUpdate(0),
                                                                                updateRate(ROLLING_COUNTER_UPD_RATE) {};
 
    virtual ~RollingCounter() = default;
 
    time_t getLastUpdate() const { return lastUpdate; }
 
    uint8_t getUpdateRate() const { return updateRate; }
};
 
#endif // _ROLLINGCOUNTER_H