diff --git a/components/sensor/combination.rst b/components/sensor/combination.rst new file mode 100644 index 000000000..62563587a --- /dev/null +++ b/components/sensor/combination.rst @@ -0,0 +1,103 @@ +Combine the state of several sensors +==================================== + +.. seo:: + :description: Instructions for setting up a combination sensor + +The ``combination`` sensor platform allows you to combine the state of several +sensors into one. To use this sensor, specify the combination type and add your source sensors. + +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 for several of the combination types. + +The source sensor states can be combined in several ways: + +- ``KALMAN`` filter: This type filters 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. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: combination + type: kalman + name: "Temperature" + 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 + +- ``LINEAR`` combination: This type sums all source sensors after multiplying each by + a configured coeffecient. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: combination + type: linear + name: "Balance Power" + sources: + - source: total_power + coeffecient: 1.0 + - source: circuit_1_power + coeffecient: -1.0 + +- ``MAXIMUM``, ``MEAN``, ``MEDIAN``, ``MINIMUM``, ``MOST_RECENTLY_UPDATED``, + ``RANGE``, ``SUM`` combinations: These types compute the specified combination among + all source sensor states. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: combination + type: median + name: "Median Temperature" + sources: + - source: temperature_sensor_1 + - source: temperature_sensor_2 + - source: temperature_sensor_3 + +Configuration variables: +------------------------ + +- **type** (**Required**, enum): Combination statistic type, should be one of + ``KALMAN``, ``LINEAR``, ``MAXIMUM``, ``MEAN``, ``MEDIAN``, ``MINIMUM``, + ``MOST_RECENTLY_UPDATED``, ``RANGE``, or ``SUM``. +- **sources** (**Required**, list): A list of sensors to use as source. + + - **source** (**Required**, :ref:`config-id` of a :doc:`/components/sensor/index`): The + sensor id that is used as sample source. + - **error** (**Required** - only for ``KALMAN`` type, float, :ref:`templatable `): + The standard deviation of the sensor's measurements. This works like the ``process_std_dev`` + parameter, with low values marking accurate data. If implemented as a template, the + measurement is in parameter ``x``. + - **coeffecient** (**Required** - only for ``LINEAR`` type, float, :ref:`templatable `): + The coeffecient to multiply the sensor's state by before summing all source sensor states. + If implemented as a template, the measurement is in parameter ``x``. + +- **process_std_dev** (**Required** - only for ``KALMAN`` type, 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 - only for KALMAN type*, :ref:`Sensor `): A sensor + that publishes the current standard deviation of the state with each update. +- All other options from :ref:`Sensor `. + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`combination/combination.h` +- :ghedit:`Edit` diff --git a/components/sensor/kalman_combinator.rst b/components/sensor/kalman_combinator.rst deleted file mode 100644 index 8b51c85ef..000000000 --- a/components/sensor/kalman_combinator.rst +++ /dev/null @@ -1,61 +0,0 @@ -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. - - - **source** (**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 7ff9105e0..ec3967c43 100644 --- a/index.rst +++ b/index.rst @@ -385,13 +385,13 @@ Miscellaneous AS3935, components/sensor/as3935, as3935.jpg, Storm lightning Binary Sensor Map, components/sensor/binary_sensor_map, binary_sensor_map.jpg, Map binary to value b-parasite, components/sensor/b_parasite, b_parasite.jpg, Moisture & Temperature & Humidity & Light + Combination, components/sensor/combination, function.svg, dark-invert Duty Time, components/sensor/duty_time, timer-play-outline.svg, dark-invert EZO sensor circuits, components/sensor/ezo, ezo-ph-circuit.png, (pH) FS3000, components/sensor/fs3000, fs3000.jpg, Air velocity Havells Solar, components/sensor/havells_solar, havellsgti5000d_s.jpg, Solar rooftop Integration, components/sensor/integration, sigma.svg, dark-invert Growatt Solar, components/sensor/growatt_solar, growatt.jpg, Solar rooftop - Kalman Combinator, components/sensor/kalman_combinator, function.svg, dark-invert 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