Add documentation for combination sensor (#3216)
This commit is contained in:
kahrendt
GitHub
parent
a7ac33d1bb
commit
340bd0d1c5
|
|
@ -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 <config-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 <config-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 <config-sensor>`): A sensor
|
||||
that publishes the current standard deviation of the state with each update.
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :ref:`sensor-filters`
|
||||
- :apiref:`combination/combination.h`
|
||||
- :ghedit:`Edit`
|
||||
|
|
@ -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 <config-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 <config-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 <config-sensor>`.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :ref:`sensor-filters`
|
||||
- :apiref:`kalman_combinator/kalman_combinator.h`
|
||||
- :ghedit:`Edit`
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue