diff --git a/components/sensor/binary_sensor_map.rst b/components/sensor/binary_sensor_map.rst new file mode 100644 index 000000000..6a6f8e634 --- /dev/null +++ b/components/sensor/binary_sensor_map.rst @@ -0,0 +1,70 @@ +Binary Sensor Map +================= + +.. seo:: + :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. + +This sensor is **mostly used for touch** devices but could be used for any ``binary_sensor`` that publishes its ``ON`` or ``OFF`` state. + +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. + +This platform currently supports only one measurement type: ``GROUP``, but others might get added later. +You need to specify which type of mapping you want with the ``type:`` configuration value: + +- ``GROUP`` Each channel has its own value. The sensor publishes the average value of all active + binary sensors. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: binary_sensor_map + id: group_0 + name: 'Group Map 0' + type: GROUP + channels: + - binary_sensor: touchkey0 + value: 0 + - binary_sensor: touchkey1 + value: 10 + - binary_sensor: touchkey2 + value: 20 + - binary_sensor: touchkey3 + value: 30 + + # Example binary sensors using MPR121 component + mpr121: + id: mpr121_first + address: 0x5A + + binary_sensor: + - platform: mpr121 + channel: 0 + id: touchkey0 + # ... + +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. + + - **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. + +- All other options from :ref:`Sensor `. + +See Also +-------- + +- :doc:`/components/binary_sensor/mpr121` +- :ref:`sensor-filters` +- :apiref:`binary_sensor_map/binary_sensor_map.h` +- :ghedit:`Edit` diff --git a/images/binary_sensor_map.jpg b/images/binary_sensor_map.jpg new file mode 100644 index 000000000..7a8a62436 Binary files /dev/null and b/images/binary_sensor_map.jpg differ diff --git a/index.rst b/index.rst index 8cb251573..4fb832d4b 100644 --- a/index.rst +++ b/index.rst @@ -91,6 +91,7 @@ Sensor Components AM2320, components/sensor/am2320, am2320.jpg APDS9960, components/sensor/apds9960, apds9960.jpg BH1750, components/sensor/bh1750, bh1750.jpg + Binary Sensor Map, components/sensor/binary_sensor_map, binary_sensor_map.jpg BLE RSSI, components/sensor/ble_rssi, bluetooth.svg BME280, components/sensor/bme280, bme280.jpg BME680, components/sensor/bme680, bme680.jpg