From ecdb160f5657cafea6426e0650745d39d59c89db Mon Sep 17 00:00:00 2001 From: Valentin Ochs Date: Sun, 9 Jan 2022 23:55:29 +0100 Subject: [PATCH] Add kalman_combinator docs (#1762) --- components/sensor/index.rst | 2 + components/sensor/kalman_combinator.rst | 61 +++++++++++++++++++++++++ index.rst | 1 + 3 files changed, 64 insertions(+) create mode 100644 components/sensor/kalman_combinator.rst diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 5bb8afd40..74b554358 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -384,6 +384,8 @@ Configuration variables: published. With this parameter you can specify when the very first value is to be sent. Defaults to ``1``. +.. _sensor-filter-exponential_moving_average: + ``exponential_moving_average`` ****************************** diff --git a/components/sensor/kalman_combinator.rst b/components/sensor/kalman_combinator.rst new file mode 100644 index 000000000..24a2f7a38 --- /dev/null +++ b/components/sensor/kalman_combinator.rst @@ -0,0 +1,61 @@ +Kalman filter-based sensor fusion +================================= + +.. seo:: + :description: Instructions for setting up a kalman_combinator sensor + +The ``kalman_combinator`` sensor platform allows you to filter one or several +sensors into one with a reduced error. If using a single sensor as data source, +it acts like a :ref:`sensor-filter-exponential_moving_average` filter. With +multiple sensors, it combines their values based on their respective standard +deviation. + +The ``unit_of_measurement``, ``device_class``, ``entity_category``, ``icon``, and +``accuracy_decimals`` properties are by default inherited from the first sensor. +``state_class`` is explicitly not inherited, because ``total_increasing`` states +could still decrease when multiple sensors are used. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: kalman_combinator + name: "Temperature" + unit_of_measurement: °C + process_std_dev: 0.001 + sources: + - source: temperature_sensor_1 + error: 1.0 + - source: temperature_sensor_2 + error: !lambda |- + return 0.5 + std::abs(x - 25) * 0.023 + +Configuration variables: +------------------------ + +- **process_std_dev** (**Required**, float): The standard deviation of the + measurement's change per second (e.g. ``1/3600 = 0.000277`` if the + temperature usually changes at most by one Kelvin per hour). A low value here + will place high importance on the current state and be slow to respond to + changes in the measured samples. A high value will update faster, but also be + more noisy. +- **std_dev** (*Optional*, :ref:`Sensor `): A sensor + that publishes the current standard deviation of the state with each update. +- **sources** (**Required**, list): A list of sensors to use as source. Each + source must have either **error** or **error_function** set. These work like + the **process_std_dev** parameter, with low values marking accurate data. + + - **sensor** (**Required**, :ref:`config-id` of a :doc:`/components/sensor/index`): The + sensor that is used as sample source + - **error** (**Required**, float, :ref:`templatable `): The standard deviation of the + sensor's measurements. If implemented as a template, the measurement is in + parameter ``x``. + +- All other options from :ref:`Sensor `. + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`kalman_combinator/kalman_combinator.h` +- :ghedit:`Edit` diff --git a/index.rst b/index.rst index 3a658d0bb..5400a2e85 100644 --- a/index.rst +++ b/index.rst @@ -327,6 +327,7 @@ Miscellaneous EZO sensor circuits, components/sensor/ezo, ezo-ph-circuit.png, (pH) Havells Solar, components/sensor/havells_solar, havellsgti5000d_s.jpg, Solar rooftop Growatt Solar, components/sensor/growatt_solar, growatt.jpg, Solar rooftop + Kalman Combinator, components/sensor/kalman_combinator, function.svg Modbus Sensor, components/sensor/modbus_controller, modbus.png Nextion, components/sensor/nextion, nextion.jpg, Sensors from display Rotary Encoder, components/sensor/rotary_encoder, rotary_encoder.jpg