diff --git a/components/sensor/binary_sensor_map.rst b/components/sensor/binary_sensor_map.rst index 28a6c4212..82e4ccf49 100644 --- a/components/sensor/binary_sensor_map.rst +++ b/components/sensor/binary_sensor_map.rst @@ -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 ` -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 ` +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 `__. 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 ` 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 ` + 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 `. @@ -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 `__ - :ghedit:`Edit`