Keypad - MPR121 Touch

.

Plugin details

Type: Keypad

Name: MPR121 Touch

Status ESP32: COLLECTION

Status ESP8266: COLLECTION

GitHub: P062_MPR121_KeyPad.ino

Maintainer: .

Used libraries: Adafruit_MPR121 (Local copy, with added extra sensitivity option)

Introduction

The NXP MPR121 I2C touch controller is often used as a keypad to allow data entry without mechanical or dome switches. This plugin supports up to 12 inputs, with optional separate configuration and calibration.

When mounting the keypad behind a glass shield, for added electrical safety, the Panel sensitivity can be increased to still be able to detect touch.

Supported hardware

NXP MPR121 I2C controller

MPR121 based, 12 key, keypad

A keypad based on the MPR121 controller.

MPR121 board without touchpads

A board having the MPR121 controller. Here some external touch-pads should be connected.

(Images taken from Aliexpress website, random seller.)

Configuration

Device configuration

  • Name A unique name should be entered here.

  • Enabled The device can be disabled or enabled. When not enabled the device should not use any resources.

I2C Options

  • The available settings here depend on the build used. At least the Force Slow I2C speed option is available, but selections for the I2C Multiplexer can also be shown. For details see the I2C Bus page

  • I2C Address: The address the device is using. Depending on the board used, when available a SDO or ADD(R) pin, can be used to select the used address. If that address selection is not available, then an I2C multiplexer (in a matching ESPEasy build) can be used to use multiple sensors on a single ESPEasy unit.

Addresses

ADDR to

Address

GND

0x5A (90)

VCC

0x5B (91)

SDA

0x5C (92)

SCL

0x5D (93)
Address options

Device Settings

  • ScanCode Select this option to get the ‘scancode’ for the key pressed, in range 1..12. If this is unchecked, the raw bitmap for the key pressed is returned (values: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048).

Sensitivity

  • Touch treshold (1..255) The amount of ‘touch’ needed to register a touch. This is the global configuration value, see below for per-key configuration.

  • Release treshold (1..255) The amount of ‘touch’ until a touch is no longer registered (released). This is the global configuration value, see below for per-key configuration.

  • Panel sensitivity When having direct access to the keypad, the sensitivity should be set to Normal. When mounting the keypad behind a sheet of glass or another capacitive inert material, the sensitivity can be set to Extra sensitive, to accomodate for a glass sheet of 4-6 mm.

Panel sensitivity options.

When mounting the keypad behind a glass panel, this should be very tight, without any air gap, to avoid unreliable registration of touches.

Per key configuration

To have better control per touch key, for each key a separate Touch and Release treshold can be set. When either of the settings per object is 0 it is ignored, and the global setting is applied.

  • Enable Calibration When the sensor is enabled, the calibration data per key (Current/Min/Max) can viewed, and depending on values the tresholds can be changed (user should experiment with settings to see what changes). By changing this option from No to Yes, the page will reload and show the calibration data, as collected by the sensor (the sensor does auto-calibration). When reverting to No, the page will reload again, without the calibration options visible.

Object list with calibration data

  • Clear calibrationdata This checkbox can be checked to clear the calibration data from the sensor, so it can restart the calibration process. This will be applied when the Submit button is used or the page is reloaded by changing the Enable Calibration option!. The initial setting is always unchecked, and is not stored.

Data Acquisition

This group of settings are standard available configuration items.

  • Single event with all values: When this setting is enabled, all available values will be sent in a single event <TaskName>#All, with all values in order as arguments to the event.

  • Show derived values: When checked, the Devices overview page, and the /json endpoint (used for updating the Devices overview page) will include any Derived values as defined. See the TaskValueSetDerived and TaskValueSetPresentation commands.

  • Event & Log derived values: When checked, the Derived values will be generated as Events, to be handled in Rules, and sent to logging devices like the Syslog server and/or SD-card logging.

(The derived values options are only available if String variables feature is included in the build.)


  • Send to Controller: Select the Controller(s) to send the Values to, either on a TaskRun command applied to the task, or on an Interval time action.

Send to Controller is only visible when one or more Controllers are configured.

Depending on the controller capabilities, some configuration settings may be shown:

../_images/Task_config_page_Controllers_section.png

All configured Controllers are shown here, including the enabled or disabled state (multiple Controllers can be enabled, only a single MQTT Controller can be enabled at one time!).

For each controller the user can select wether the data should be sent on each Interval (or explicit TaskRun).

For the Domoticz controllers the value index (IDX) has to be configured.

For some controllers, like Home Assistant/openHAB, there are extra options available.

  • Group: This represents the group id to combine all values from multiple tasks into a single grouped-device during MQTT AutoDiscovery. Groups, by design, can span multiple ESPEasy devices, if desired, as long as the Task/Valuename combinations are unique. If a group should only combine Tasks from a single ESPEasy unit, the group id should be unique across multiple ESPEasy units. The group description, default Group <n>, can be adjusted in Home Assistant. If the Group value matches the current Unit nr, the Unit name, %sysname%, is used instead of Group <nr>.

  • Retained: For MQTT Controllers, this setting can be enabled to send the values for the current task with the Retain flag set. The Publish Retain flag in the Controller settings will override this by sending all task values with Retain flag enabled.

  • Send derived: This checkbox determines if any configured Derived values should also be sent to the controller (and included in the AutoDiscovery if that’s available and enabled).

  • Resend MQTT Discovery: When checked, will start a resend of the MQTT Discovery process for this task after a random delay, when Submit is clicked, so any changed settings will be updated in the MQTT broker. This setting is only available if the controller is enabled, the Auto Discovery feature is available and enabled for the controller. This setting is not stored.

Other controllers, like f.e. FHEM HTTP, do not support additional settings besides the checkbox to enable sending the data.


  • Interval By default, Interval will be set to 0 sec (off). If a value > 0 is used, then every <Interval> seconds an event with the last value is generated.

Values

The last touched key is available in ScanCode.

Events

When a key is touched, the new data is sent out as an event, using the format <TaskName>#<ValueName>. This can be handled from the rules.

Change log

Changed in version 2.0: …

added 2021-12-29 Panel sensitivity setting added.

added 2020-10 Tresholds per touchkey.

added Major overhaul for 2.0 release.

Added in version 1.0: …

added Initial release version.