home-assistant.io/source/_integrations/derivative.markdown

title	description	ha_category	ha_release	ha_iot_class	ha_qa_scale	ha_codeowners	ha_domain	ha_config_flow	ha_platforms	ha_integration_type
Derivative	Instructions on how to integrate Derivative Sensor into Home Assistant.	Energy Helper Sensor Utility	0.105	Calculated	internal	@afaucogney	derivative	true	sensor	helper

The derivative (Wikipedia) integration creates a sensor that estimates the derivative of the values provided by another sensor (the source sensor). Derivative sensors are updated upon changes of the source sensor.

{% include integrations/config_flow.md %} {% configuration_basic %} Name: description: The name the sensor should have. You can change it again later. Input sensor: description: The entity providing numeric readings to create the derivative of. Precision: description: Round the calculated integration value to at most N decimal places. Time window: description: The time window in which to calculate the derivative. Derivatives in this window will be averaged with a simple moving average algorithm (SMA) weighted by time. This is for instance useful for a sensor that outputs discrete values, or to filter out short duration noise. By default the derivative is calculated between two consecutive updates without any smoothing. Metric Prefix: description: Metric unit to prefix the derivative result (Wikipedia). Time unit: description: SI unit of time of the derivative. If this parameter is set, the unit of measurement will be set to x/y where x is the unit of the source sensor and y is the value of this parameter. {% endconfiguration_basic %}

YAML Configuration

Alternatlively, this integration can be configured and set up manually via YAML instead. To enable the Integration sensor in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry
sensor:
  - platform: derivative
    source: sensor.current_speed

{% configuration %} source: description: The entity ID of the sensor providing numeric readings required: true type: string name: description: Name to use in the frontend. required: false default: source entity ID meter type: string round: description: Round the calculated derivative value to at most N decimal places. required: false default: 3 type: integer unit_prefix: description: Metric unit to prefix the derivative result (Wikipedia). 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 unit_time: description: SI unit of time of the derivative. Available units are s, min, h, d. If this parameter is set, the attribute unit_of_measurement will be set like x/y where x is the unit of the sensor given via the source parameter and y is the value given here. required: false default: h type: string unit: description: Unit of Measurement to be used for the derivative. This will overwrite the automatically set unit_of_measurement as explained above. required: false type: string time_window: description: The time window in which to calculate the derivative. Derivatives in this window will be averaged with a Simple Moving Average algorithm weighted by time. This is for instance useful for a sensor that outputs discrete values, or to filter out short duration noise. By default the derivative is calculated between two consecutive updates without any smoothing. default: 0 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 YAML configuration that uses time_window is

sensor:
  - platform: derivative
    source: sensor.temperature
    name: Temperature change per hour
    round: 1
    unit_time: h # the resulting "unit_of_measurement" will be °C/h if the sensor.temperate has set °C as its unit
    time_window: "00:30:00"  # we look at the change over the last half hour