From adaded35fe36ad3d0735b53dc3b48b3b438beaaa Mon Sep 17 00:00:00 2001 From: Roy Meissner Date: Wed, 13 Oct 2021 02:04:33 +0200 Subject: [PATCH] Added documentation for a throttle_average filter (#1521) Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/sensor/index.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 87cb466cf..28fe2b1b6 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -132,6 +132,7 @@ Filters are processed in the order they are defined in your configuration. alpha: 0.1 send_every: 15 - throttle: 1s + - throttle_average: 1s - heartbeat: 5s - debounce: 0.1s - delta: 5.0 @@ -369,6 +370,17 @@ If it is not older than the configured value, the value is not passed forward. - delta: 5.0 - lambda: return x * (9.0/5.0) + 32.0; +``throttle_average`` +******************** + +An average over the ``specified time period``, potentially throttling incoming values. When this filter gets incoming values, it sums up all values and pushes out the average after the ``specified time period`` passed. There are two edge cases to consider within the ``specified time period``: + +* no value(s) received: ``NaN`` is returned - add the ``heartbeat`` filter if periodical pushes are required and/or ``filter_out: nan`` if required +* one value received: the value is pushed out after the ``specified time period`` passed, without calculating an average + +For example a ``throttle_average: 60s`` will push out a value every 60 seconds, in case at least one sensor value is received within these 60 seconds. + +In comparison to the ``throttle`` filter it won't discard any values. In comparison to the ``sliding_window_moving_average`` filter it supports variable sensor reporting rates without influencing the filter reporting interval (except for the first edge case). ``heartbeat`` *************