MPR121 Capacitive Touch Sensor

Component/Hub

The mpr121 sensor platform allows you to use your MPR121 (datasheet, Adafruit) Capacitive Touch Sensor with ESPHome. The I²C is required to be set up in your configuration for this sensor to work.

MPR121 Capacitive Touch Sensor. Image by [Adafruit](https://www.adafruit.com).

# 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, 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 Component/Hub and then use this binary sensor platform to create individual binary sensors for each touch sensor.

Configuration variables:

mpr121_id (Optional, ID): The ID of the MPR121 defined above. Useful for multiple MPR121’s on the I²C bus
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 Binary Sensor.

GPIO

The mpr121 also supports configuring its touch electrodes as GPIO inputs and outputs. To do so, specify an id in the configuration of the mpr121 component. Then, configure a GPIO output or input using this ID in the mpr121 field.

output:
  - id: ext_5v_power
    platform: gpio
    pin:
      mpr121: mpr121_component
      number: 10
      mode: OUTPUT
      inverted: true

The number refers to the ELEx pin number on the MPR121 chip. Only ELE4 up to including ELE11 are available as GPIO.

GPIO and touch functionality may be used at the same time, but not on the same pins.

It is also not valid to configure a pin as GPIO when a pin with a higher number is used as touch channel. This is because touch functionality is configured as a range, starting at ELE0. For example:

Using channel 2 and 5 as touch and channel 6 as GPIO is okay
Using channel 2 and 5 as touch and channel 4 as GPIO is not okay

MPR121 Capacitive Touch Sensor

Component/Hub

Configuration variables

Binary Sensor

GPIO

See Also