From 31c1a255c19b098ee4dc368bf2b3793651a3cfbb Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Tue, 4 Feb 2020 10:31:38 +0100 Subject: [PATCH] Derivative component update, add time_window (#11963) * update the docs, see https://github.com/home-assistant/home-assistant/pull/31397 * add more detailed example --- source/_integrations/derivative.markdown | 28 +++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/source/_integrations/derivative.markdown b/source/_integrations/derivative.markdown index aef2586feb2..c8a872fd17d 100644 --- a/source/_integrations/derivative.markdown +++ b/source/_integrations/derivative.markdown @@ -10,7 +10,8 @@ logo: derivative.png ha_qa_scale: internal --- -The `derivative` platform provides the numerical derivative or numerical differentiation of the values provided by a source sensor. Derivative sensors are updated upon changes of the **source**. Fast sampling source sensors provide better results. +The `derivative` platform creates a sensor that estimates the derivative of the values provided by a source sensor. +Derivative sensors are updated upon changes of the **source**. ## Configuration @@ -39,7 +40,7 @@ round: default: 3 type: integer unit_prefix: - description: Metric unit to prefix the derivative result. Available units are k, M, G, T. + description: Metric unit to prefix the derivative result ([Wikipedia](https://en.wikipedia.org/wiki/Unit_prefix)]). Available symbols are "n" (1e-9), "µ" (1e-6), "m" (1e-3), "k" (1e3), "M" (1e6), "G" (1e9), "T" (1e12). required: false default: None type: string @@ -52,6 +53,27 @@ unit: description: Unit of Measurement to be used for the derivative. required: false type: string +time_window: + description: The time window in which to calculate the derivative. This is useful for sensor that output discrete values. By default the derivative is calculated between two consecutive updates. + default: 0 + required: false + type: time {% endconfiguration %} -If 'unit' is set then 'unit_prefix' and 'unit_time' are ignored. +## Temperature example + +For example, you have a temperature sensor `sensor.temperature` that outputs a value every few seconds, but rounds to the nearest half number. +That means that two consecutive output values might be the same (so the derivative is `Δy/Δx=0` because `Δy=0` !) +However, the temperature might actually be changing over time. +In order to capture this, you should use a `time_window`, such that immediate jumps don't result in high derivatives and that after the next sensor update, the derivatives doesn't vanish to zero. +An example config that uses `time_window` is + +```yaml +sensor: + - platform: derivative + source: sensor.temperature + name: Temperature change per hour + round: 1 + unit_time: h + time_window: "00:30:00" # we look at the change over the last half hour +```