MPR121 Capacitive Touch Sensor
==============================

.. seo::
    :description: Instructions for setting up MPR121 Capacitive Touch Sensor
    :image: mpr121.jpg
    :keywords: MPR121

.. _mpr121-component:

Component/Hub
-------------

The ``mpr121`` sensor platform allows you to use your MPR121
(`datasheet <https://cdn-learn.adafruit.com/downloads/pdf/adafruit-mpr121-12-key-capacitive-touch-sensor-breakout-tutorial.pdf>`__,
`Adafruit`_) Capacitive Touch Sensor with ESPHome. The :ref:`I²C <i2c>` is
required to be set up in your configuration for this sensor to work.

.. figure:: images/mpr121-full.jpg
    :align: center
    :width: 50.0%

    MPR121 Capacitive Touch Sensor. Image by `Adafruit`_.

.. _Adafruit: https://learn.adafruit.com/adafruit-mpr121-12-key-capacitive-touch-sensor-breakout-tutorial/overview

.. code-block:: yaml

    # Example configuration entry
    mpr121:
      id: mpr121_component
      address: 0x5A
      touch_debounce: 1
      release_debounce: 1
      touch_threshold: 10
      release_threshold: 7

    binary_sensor:
      - platform: mpr121
        id: touch_key0
        channel: 0
        name: "Touch Key 0"
        touch_threshold: 12
        release_threshold: 6

Configuration variables:
------------------------

The configuration is made up of two parts: The central component, and individual Binary sensors per channel.

- **address** (*Optional*, int): The I²C address of the sensor. Defaults to ``0x5A``.
- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor.
- **touch_debounce** (*Optional*, int): The minimum length before a touch is recognized. Range is from 0 to 7.
  Defaults to 0.
- **release_debounce** (*Optional*, int): The minimum length that no touch is recognized before a release event is created.
  Range is from 0 to 7. Defaults to 0.
- **touch_threshold** (*Optional*, int): The touch threshold for all channels. This defines the sensitivity for touch detection
  and should be between 5 and 30 (lower = more sensitive). Defaults to 12. Typically the touch threshold is a little bigger than the release threshold.
- **release_threshold** (*Optional*, int): The release defines the sensitivity for touch detection and should be between 5 and 30. Defaults to 6.

Binary Sensor
-------------

The ``mpr121`` binary sensor allows you to use your MPR121 with ESPHome.
First, setup a :ref:`mpr121-component` and then use this binary sensor platform to create individual
binary sensors for each touch sensor.


Configuration variables:


- **name** (*Optional*, string): The name for the binary sensor.
- **mpr121_id** (*Optional*, :ref:`config-id`): The ID of the MPR121 defined above. Useful for multiple MPR121's on the I²C bus
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **channel** (**Required**, int): The channel number at the MPR121 the touchkey is connected to.
- **touch_threshold** (*Optional*, int): A per-channel override of the global touch_threshold value. If not specified, uses the global value.
- **release_threshold** (*Optional*, int): A per-channel override of the global release_threshold value. If not specified, uses the global value.
- All other options from :ref:`Binary Sensor <config-binary_sensor>`.

See Also
--------

- :ref:`sensor-filters`
- :apiref:`mpr121/mpr121.h`
- `Adafruit MPR121 Library <https://github.com/adafruit/Adafruit_MPR121_Library>`__ by `Adafruit <https://www.adafruit.com/>`__
- :ghedit:`Edit`