mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-02-28 03:41:57 +01:00
Document Bayesian type for binary_sensor_map component (#2796)
Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
kahrendt
GitHub
parent
c01cce8ddd
commit
b9c710a133
@ -5,19 +5,50 @@ Binary Sensor Map
|
||||
:description: Instructions for setting up a Binary Sensor Map
|
||||
:image: binary_sensor_map.jpg
|
||||
|
||||
The ``binary_sensor_map`` sensor platform allows you to map :doc:`binary sensor </components/binary_sensor/index>`
|
||||
to values. When a given binary sensor is on, the value associated with it in this platform's configuration will be published.
|
||||
The ``binary_sensor_map`` sensor platform allows you to map multiple :doc:`binary sensor </components/binary_sensor/index>`
|
||||
to an individual value. Depending on the state of each binary sensor, its associated configured parameters, and this sensor's mapping type,
|
||||
the ``binary_sensor_map`` publishes a single numerical value.
|
||||
|
||||
This sensor is **mostly used for touch** devices but could be used for any ``binary_sensor`` that publishes its ``ON`` or ``OFF`` state.
|
||||
Use this sensor to combine one or more binary sensors' ``ON`` or ``OFF`` states into a numerical value. Some possible use cases include
|
||||
touch devices and determining Bayesian probabilities for an event.
|
||||
|
||||
Add your binary sensors as ``channels`` to the binary sensor map. The binary sensor map then publishes a value depending
|
||||
on the type of the binary sensor map and the values specified with each channel. The maximum amount of possible channels is 64.
|
||||
This platform supports three measurement types: ``BAYESIAN``, ``GROUP``, and ``SUM``.
|
||||
You need to specify your desired mapping with the ``type:`` configuration value.
|
||||
|
||||
This platform currently supports two measurement types: ``GROUP`` and ``SUM``, and others might get added later.
|
||||
You need to specify which type of mapping you want with the ``type:`` configuration value:
|
||||
When using the ``BAYESIAN`` type, add your binary sensors as ``observations`` to the binary sensor map.
|
||||
If you use the ``GROUP`` or ``SUM`` type, add your binary sensors as ``channels``.
|
||||
The maximum amount of observations/channels supported is 64.
|
||||
|
||||
- ``GROUP`` Each channel has its own value. The sensor publishes the average value of all active
|
||||
binary sensors.
|
||||
- ``BAYESIAN`` This type replicates Home Assistant's `Bayesian sensor <https://www.home-assistant.io/integrations/bayesian/>`__. Based on the observation states, this sensor returns the Bayesian probability of a particular event occurring. The configured ``prior:`` probability is the likelihood that the Bayesian event is true, ignoring all external influences. Every observation has its own ``prob_given_true`` and ``prob_given_false`` parameters. The ``prob_given_true:`` value is the probability that the observation's binary sensor is ``ON`` when the Bayesian event is ``true``. The ``prob_given_false:`` value is the probability that the observation's binary sensor is ``ON`` when the Bayesian event is ``false``. Use an :doc:`/components/binary_sensor/analog_threshold` to convert this sensor's probability to a binary ``ON`` or ``OFF`` by setting an appropriate threshold.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
sensor:
|
||||
- platform: binary_sensor_map
|
||||
id: bayesian_prob
|
||||
name: 'Bayesian Event Probability'
|
||||
type: bayesian
|
||||
prior: 0.4
|
||||
observations:
|
||||
- binary_sensor: binary_sensor_0
|
||||
prob_given_true: 0.9
|
||||
prob_given_false: 0.2
|
||||
- binary_sensor: binary_sensor_1
|
||||
prob_given_true: 0.6
|
||||
prob_given_false: 0.1
|
||||
|
||||
binary_sensor:
|
||||
# If the Bayesian probability is greater than 0.6,
|
||||
# then predict the event is occuring
|
||||
- platform: analog_threshold
|
||||
name: "Bayesian Event Predicted State"
|
||||
sensor_id: bayesian_prob
|
||||
threshold: 0.6
|
||||
# ...
|
||||
|
||||
- ``GROUP`` Each channel has its own ``value``. The sensor publishes the average value of all active
|
||||
binary sensors or ``NAN`` if no sensors are active.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -48,8 +79,8 @@ You need to specify which type of mapping you want with the ``type:`` configurat
|
||||
id: touchkey0
|
||||
# ...
|
||||
|
||||
- ``SUM`` Each channel has its own value. The sensor publishes the sum of all active
|
||||
binary sensors values.
|
||||
- ``SUM`` Each channel has its own ``value``. The sensor publishes the sum of all the active
|
||||
binary sensors values or ``0`` if no sensors are active.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -91,12 +122,19 @@ Configuration variables:
|
||||
------------------------
|
||||
|
||||
- **name** (**Required**, string): The name of the sensor.
|
||||
- **type** (**Required**, string): The sensor type. Should be one of: ``GROUP``.
|
||||
- **channels** (**Required**): A list of channels that are mapped to certain values.
|
||||
- **type** (**Required**, string): The sensor type. Should be one of: ``BAYESIAN``, ``GROUP``, or ``SUM``.
|
||||
- **channels** (**Required for GROUP or SUM types**): A list of channels that are mapped to certain values.
|
||||
|
||||
- **binary_sensor** (**Required**): The id of the :doc:`binary sensor </components/binary_sensor/index>`
|
||||
to add as a channel for this sensor.
|
||||
- **value** (**Required**): The value this channel should report when its binary sensor is active.
|
||||
- **prior** (**Required for BAYESIAN type**, float between 0 and 1): The prior probability of the event.
|
||||
- **observations** (**Required for BAYESIAN type**): A list of observations that influence the Bayesian probability of the event.
|
||||
|
||||
- **binary_sensor** (**Required**): The id of the :doc:`binary sensor </components/binary_sensor/index>`
|
||||
to add as an observation.
|
||||
- **prob_given_true** (**Required**, float between 0 and 1): Assuming the event is true, the probability this observation is on.
|
||||
- **prob_given_false** (**Required**, float between 0 and 1): Assuming the event is false, the probability this observation is on.
|
||||
|
||||
- All other options from :ref:`Sensor <config-sensor>`.
|
||||
|
||||
@ -104,6 +142,8 @@ See Also
|
||||
--------
|
||||
|
||||
- :doc:`/components/binary_sensor/mpr121`
|
||||
- :doc:`/components/binary_sensor/analog_threshold`
|
||||
- :ref:`sensor-filters`
|
||||
- :apiref:`binary_sensor_map/binary_sensor_map.h`
|
||||
- `Bayesian sensor in Home Assistant <https://www.home-assistant.io/integrations/bayesian/>`__
|
||||
- :ghedit:`Edit`
|
||||
|
||||
Loading…
Reference in New Issue
Block a user