From 242ba37942f72a1a4395e9650f0223066e1d5f81 Mon Sep 17 00:00:00 2001
From: Bas Nijholt <basnijholt@gmail.com>
Date: Mon, 3 Feb 2020 21:25:46 +0100
Subject: [PATCH 1/2] update the docs, see
 https://github.com/home-assistant/home-assistant/pull/31397

---
 source/_integrations/derivative.markdown | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/source/_integrations/derivative.markdown b/source/_integrations/derivative.markdown
index aef2586feb25..7fb3d37eab36 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,9 @@ 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.

From 978bd5b94cf58c12efe4321c46e9664918490478 Mon Sep 17 00:00:00 2001
From: Bas Nijholt <basnijholt@gmail.com>
Date: Mon, 3 Feb 2020 21:55:47 +0100
Subject: [PATCH 2/2] add more detailed example

---
 source/_integrations/derivative.markdown | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/source/_integrations/derivative.markdown b/source/_integrations/derivative.markdown
index 7fb3d37eab36..c8a872fd17d2 100644
--- a/source/_integrations/derivative.markdown
+++ b/source/_integrations/derivative.markdown
@@ -59,3 +59,21 @@ time_window:
   required: false
   type: time
 {% endconfiguration %}
+
+## 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
+```