RainGauge Class Reference

Calculation of hourly (past 60 minutes), daily, weekly and monthly rainfall. More...

#include <RainGauge.h>

Inheritance diagram for RainGauge:

Public Member Functions
	RainGauge (const float raingauge_max=RAINGAUGE_MAX_VALUE, const float quality_threshold=DEFAULT_QUALITY_THRESHOLD)
void	set_max (float raingauge_max)
bool	setUpdateRate (uint8_t rate=RAINGAUGE_UPD_RATE)
	Set expected update rate for pastHour() calculation.
void	reset (uint8_t flags=0x1F)
void	hist_init (int16_t rain=-1) override
void	hist24h_init (int16_t rain=-1)
void	update (time_t ts, float rain, bool startup=false)
	Update rain gauge statistics.
float	pastHour (bool *valid=nullptr, int *nbins=nullptr, float *quality=nullptr)
float	past24Hours (bool *valid=nullptr, int *nbins=nullptr, float *quality=nullptr)
float	currentDay (void)
float	currentWeek (void)
float	currentMonth (void)
Public Member Functions inherited from RollingCounter
	RollingCounter (const float quality_threshold=DEFAULT_QUALITY_THRESHOLD)
virtual	~RollingCounter ()=default
time_t	getLastUpdate () const
uint8_t	getUpdateRate () const

Detailed Description

Calculation of hourly (past 60 minutes), daily, weekly and monthly rainfall.

Additionally overflow of the rain gauge is handled when reaching RAINGAUGE_MAX_VALUE.

Constructor & Destructor Documentation

RainGauge()

RainGauge::RainGauge ( const float  raingauge_max = RAINGAUGE_MAX_VALUE, const float  quality_threshold = DEFAULT_QUALITY_THRESHOLD  )

inline

Constructor

Parameters

raingauge_max	raingauge value which causes a counter overflow
quality_threshold	fraction of valid rain_hist entries required for valid pastHour() result

Member Function Documentation

currentDay()

float RainGauge::currentDay

(

void

)

Rainfall of current calendar day

Returns

amount of rain

currentMonth()

float RainGauge::currentMonth

(

void

)

Rainfall of current calendar month

Returns

amount of rain

currentWeek()

float RainGauge::currentWeek

(

void

)

Rainfall of current calendar week

Returns

amount of rain

hist24h_init()

void RainGauge::hist24h_init

(

int16_t

rain = -1

)

Initialize 24-hour history buffer

Parameters

rain	initial value for all entries (default: -1 for invalid)

hist_init()

void RainGauge::hist_init ( int16_t  rain = -1 )

overridevirtual

Initialize history buffer for hourly (past 60 minutes) rainfall

Parameters

rain	initial value for all entries (default: -1 for invalid)

Implements RollingCounter.

past24Hours()

float RainGauge::past24Hours	(	bool *	valid = nullptr,
		int *	nbins = nullptr,
		float *	quality = nullptr
	)

Rainfall during past 24 hours

Parameters

valid	number of valid entries in rain_hist24h >= qualityThreshold * 24
nbins	number of valid entries in rain_hist24h
quality	fraction of valid entries in rain_hist24h (0..1); quality = nbins / 24

Returns

amount of rain during past 24 hours

pastHour()

float RainGauge::pastHour	(	bool *	valid = nullptr,
		int *	nbins = nullptr,
		float *	quality = nullptr
	)

Rainfall during past 60 minutes

Parameters

valid	number of valid entries in rain_hist >= qualityThreshold * 60 / updateRate
nbins	number of valid entries in rain_hist
quality	fraction of valid entries in rain_hist (0..1); quality = nbins / (60 / updateRate)

Returns

amount of rain during past 60 minutes

reset()

void RainGauge::reset

(

uint8_t

flags = 0x1F

)

Reset non-volatile data and current rain counter value

Parameters

flags

Flags defining what to reset:

set_max()

void RainGauge::set_max ( float  raingauge_max )

inline

Set maximum rain counter value

Parameters

raingauge_max

raingauge value which causes a counter overflow

setUpdateRate()

bool RainGauge::setUpdateRate ( uint8_t  rate = RAINGAUGE_UPD_RATE )

inline

Set expected update rate for pastHour() calculation.

RAIN_HIST_SIZE: number of entries in rain_hist[] updateRate: update rate in minutes

60 minutes / updateRate = no_of_hist_bins The resulting number of history bins must be an integer value which does not exceed RAIN_HIST_SIZE.

Examples:

1. updateRate = 6 -> 60 / 6 = 10 entries
2. updateRate = 12 -> 60 / 12 = 5 entries

Changing the update rate will reset the history buffer, therefore the caller should avoid frequent changes.

Actual update intervals shorter than updateRate will lead to a reduced resolution of the pastHour() result and a higher risk of an invalid result if a bin in the history buffer was missed.

Actual update intervals longer than updateRate will lead to an invalid result, because bins in the history buffer will be missed.

Parameters

rate	update rate in minutes (default: 6)

Returns

true if rate is valid and was set, false otherwise

update()

RainGauge::update	(	time_t	ts,
		float	rain,
		bool	startup = false
	)

Update rain gauge statistics.

Parameters

ts	timestamp
rain	rain gauge raw value (in mm/m²)
startup	sensor startup flag

* Total rainfall during past 60 minutes
* --------------------------------------
*
* In each update():
* - timestamp (time_t) ->                  t (localtime, struct tm)
* - calculate index into hist[]:           idx = t.tm_min / updateRate
* - expired time since last update:        t_delta = timestamp - nvData.lastUpdate
* - amount of rain since last update:      rainDelta = rainCurr - nvData.rainPrev
* - t_delta
*      < 0:                                something is wrong, e.g. RTC was not set correctly -> ignore, return
*      t_delta < expected update rate:
*          idx same as in previous cycle:  hist[idx] += rainDelta
*          idx changed by 1:               hist[idx] = rainDelta
*      t_delta >= history size:            mark all history entries as invalid
*      else (index changed > 1):           mark all history entries in interval [expected_index, current_index) as invalid
*                                          hist[idx] = rainDelta
*
*   ---------------     -----------
*  |   |   |   |   |...|   |   |   |   hist[RAIN_HIST_SIZE]
*   ---------------     -----------
*        ^
*        |
*       idx = t.tm_min / updateRate
*
* - Calculate hourly rate:
*   pastHour = sum of all valid hist[] entries
*
* Notes:
* - rainDelta values (floating point with resolution of 0.1) are stored as integers to reduce memory consumption.
*   To avoid rounding errors, the rainDelta values are multiplied by 100 for conversion to integer.
* 

---

The documentation for this class was generated from the following files:

• src/RainGauge.h
• src/RainGauge.cpp