drivers/input: Add support to MPR121 Capacitive Keypad

Documentation/components/drivers/character/input/index.rst

@@ -7,6 +7,7 @@ Input Devices
 
   keypad-keyboard.rst
   keypad.rst
+  mpr121.rst
   sbutton.rst
 
 See ``include/nuttx/input/*.h`` for registration information.

Documentation/components/drivers/character/input/mpr121.rst

@@ -0,0 +1,72 @@
+========================
+MPR121 Capacitive Keypad
+========================
+
+**What is the MPR121 Keypad**
+The  MPR Capacitive Keypad is a small keyboard with 12 keys, similar
+to a telephone keypad, however the keys are numered from 0 to 11.
+
+This is the picture of the MPR121 Capacitive Keypad:
+
+.. image:: images/mpr121.png
+  :alt: MPR121 Capacitive Keypad
+  :align: center
+  :width: 200px
+
+**Purpose**. The MPR121 driver provides a generic keypad
+implementation for this capacitive keypad. The MPR121 uses the I2C
+bus to setup and read the touched/released key and uses an IRQ pin
+(open drain) to indicate when a key is pressed/released or when some
+unnexpected issue happens (currently not used).
+
+The driver also enables debounce, and emits keyboard events through
+the common keyboard upper-half. This makes the device available as a
+character driver (e.g., ``/dev/keypad0``) using the standard keyboard
+interfaces.
+
+**Driver Overview**. The MPR121 lower-half scans the matrix and calls
+``keyboard_event()`` when it detects a press or release. The keyboard
+upper-half registers the character device at the requested ``devpath``
+and stores events in a circular buffer. Applications read
+``struct keyboard_event_s`` from the device or use the optional
+kbd-codec layer.
+
+**Board Support**. To support the MPR121, a board must provide:
+
+#. **IRQ Definition**
+
+   - Define the GPIO Input pin with pull-up enabled (since the
+     IRQ pin is open-drain) to be used to detect the interrupts.
+
+#. **Registration Hook**
+
+   - Define a ``struct xxx_mpr121config_s`` that will wrap the
+     ``struct mpr121_config_s config`` as first member and the irq
+     argument and ISR handler (xcpt_t isr). The ``config`` needs to
+     have its ``.irq_attach`` and ``keymap`` initialized with the
+     board IRQ ISR function and the key mapping array.
+   - Implement ``board_mpr121_initialize(int devno, int busno)`` to
+     call ``mpr121_register(&config, devpath)``. It needs to initialize
+     the I2C Master port/channel that will be used to communicate with
+     the MPR121 and an instance of that ``xxx_mpr121config_s`` structure.
+   - Invoke the board hook during bring-up (for example,
+     ``board_mpr121_initialize(0, 1)`` for ``/dev/keymap0`` and ``i2c1``).
+
+**Reference Implementation (STM32F4Discovery)**. The current reference
+is in ``boards/arm/stm32/common/src/stm32_mpr121.c``:
+
+- Keymap: 4x3 keypad layout
+- Registration: ``board_mpr121_initialize()`` calls
+  ``mpr121_register()``
+
+**Data Path Summary**.
+
+- Board calls ``board_mpr121_initialize(0, 1)``
+- ``mpr121_register()`` initializes and configure the MPR121 chip
+  and calls ``keyboard_register(&lower, devpath, buflen)``
+- The upper-half registers the device node at ``devpath``
+- Every time an interruption is generated on IRQ pin it will call the
+  ``mpr121_worker()`` and it is calls ``keyboard_event()`` on
+  press/release of keys.
+- Applications read events from the device node (``/dev/keypad0``).
+

Documentation/platforms/arm/stm32f4/boards/stm32f4discovery/index.rst

@@ -1475,6 +1475,54 @@ because code cannot be executed from CCM memory.
 STATUS:
 2018-06-02: Configuration added by Alan Carvalho de Assis.
 
+mpr121_keypad
+-------------
+
+This board config enables the usage of an external MPR121 Capacitive
+Keypad connected to STM32F4Discovery board this way:
+
+================ =============
+STM32F4Discovery MPR121 Keypad
+================ =============
+GND              GND
+3V [1]           3V3
+I2C1 SDA (PB9)   SDA
+I2C1 SCL (PB6)   SCL
+PB0              IRQ
+================ =============
+
+1: You need to remove the diode D3 and short-circuit the PADs in the
+board to get 3.3V. Be aware: although my board works fine, it could
+damage something that expects 3V in our board (double check).
+
+After compiling and flashing the firmware in our board, run kbd command.
+
+.. code:: console
+
+   NuttShell (NSH) NuttX-12.13.0
+   nsh> ls /dev
+   /dev:
+    console
+    keypad0
+    null
+    ttyS0
+    zero
+   nsh> kbd
+   kbd_main: nsamples: 0
+   kbd_main: Opening /dev/keypad0
+   Sample  :
+      code : 48
+      type : 0
+   Sample  :
+      code : 48
+      type : 1
+   Sample  :
+      code : 49
+      type : 0
+   Sample  :
+      code : 49
+      type : 1
+
 netnsh
 ------
 

boards/arm/stm32/common/include/stm32_mpr121.h

@@ -0,0 +1,82 @@
+/****************************************************************************
+ * boards/arm/stm32/common/include/stm32_mpr121.h
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+#ifndef __BOARDS_ARM_STM32_COMMON_INCLUDE_STM32_MPR121_H
+#define __BOARDS_ARM_STM32_COMMON_INCLUDE_STM32_MPR121_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Data
+ ****************************************************************************/
+
+#ifdef __cplusplus
+#define EXTERN extern "C"
+extern "C"
+{
+#else
+#define EXTERN extern
+#endif
+
+/****************************************************************************
+ * Inline Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: board_mpr121_initialize
+ *
+ * Description:
+ *   Initialize and register the MPR121 capacitive keypad.
+ *
+ * Input Parameters:
+ *   devno - The device number, used to build the device path as /dev/keypadN
+ *   busno - The I2C bus number
+ *
+ * Returned Value:
+ *   Zero (OK) on success; a negated errno value on failure.
+ *
+ ****************************************************************************/
+
+int board_mpr121_initialize(int devno, int busno);
+
+#undef EXTERN
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __BOARDS_ARM_STM32_COMMON_INCLUDE_STM32_MPR121_H */

boards/arm/stm32/common/src/CMakeLists.txt

@@ -166,4 +166,8 @@ if(CONFIG_INPUT_KMATRIX_I2C)
   list(APPEND SRCS stm32_kmatrix_i2c.c)
 endif()
 
+if(CONFIG_INPUT_MPR121_KEYPAD)
+  list(APPEND SRCS stm32_mpr121.c)
+endif()
+
 target_sources(board PRIVATE ${SRCS})

boards/arm/stm32/common/src/Make.defs

@@ -86,6 +86,10 @@ ifeq ($(CONFIG_SENSORS_APDS9960),y)
   CSRCS += stm32_apds9960.c
 endif
 
+ifeq ($(CONFIG_INPUT_MPR121_KEYPAD),y)
+  CSRCS += stm32_mpr121.c
+endif
+
 ifeq ($(CONFIG_SENSORS_ZEROCROSS),y)
   CSRCS += stm32_zerocross.c
 endif