Merge #19885

19885: drivers/stmpe811: changes for interrupt-driven touch handling and gesture recognition r=aabadie a=gschorcht

### Contribution description

This PR contains changes needed for the purely interrupt-driven handling of the touch position as `touch_dev` device, which is a prerequisite for the realization of gesture recognition. (PR #19884).

The interrupt-driven approach of `touch_dev` devices (PR #19882) and the gesture recognition (PR #19884) need continuous reporting of the touch position as long as there is at least one touch. Since the driver so far only uses the _Touch Detect_ interrupt, only the position at the beginning of a touch is available. All further positions must be polled.

Therefore, the changes in this PR additionally enable the _FIFO Threshold_ interrupt when the `touch_dev` module is enabled. However, since the _Touch Detect_ interrupt does not work reliably when the _FIFO Threshold_ interrupt is enabled and the FIFO Threshold is 1, the FIFO Threshold is set to 2 by default when the `touch_dev` module is enabled.

Furthermore, the FIFO queue has to be reset after reading one touch position. Otherwise new touch positions are processed with a delay if the rate of calling the function to read the FIFO is slower than the rate at which the FIFO is filled. The reason for this is that with each call of this function only the oldest touch position is read value by value from the FIFO. Gestures can't be implemented with such a behavior.

### Testing procedure

1. `tests/drivers/stmpe811` should work as before (only a single position is shown):
   ```
   BOARD=stm32f429i-disco make -j8 -C tests/drivers/stmpe811 flash
   ```
   ```
   main(): This is RIOT! (Version: 2023.10-devel-120-g848d1- 
   drivers/stmpe811_touch_dev_gestures)
   STMPE811 test application
   +------------Initializing------------+
   Initialization successful
   Pressed!
   X: 135, Y:131
   Released!
   ```
2. `tests/drivers/stmpe811` should work on top of PR #19882 with continuous outputs of touch positions:
   ```
   BOARD=stm32f429i-disco make -j8 -C tests/drivers/touch_dev flash
   ```
   ```
   main(): This is RIOT! (Version: 2023.10-devel-121-g38d3db-drivers/stmpe811_touch_dev_gestures)
   Event: pressed!
   X: 131, Y:145
   X: 133, Y:141
   X: 135, Y:138
   X: 138, Y:133
   X: 141, Y:128
   X: 146, Y:122
   X: 151, Y:117
   Event: released!
   ```
3. `tests/driver/touch_dev_gestures` of PR #19884 should work on top of this PR:
   ```
   BOARD=stm32f429i-disco make -j8 -C tests/drivers/touch_dev_gestures flash
   ```
   ```
   main(): This is RIOT! (Version: 2023.10-devel-128-g05f690-drivers/touch_dev_gestures_work)
   Swipe right
   Swipe left
   Swipe down
   Swipe up
   Single Tap X: 246, Y:148
   Single Tap X: 256, Y:139
   Double Tap X: 247, Y:136
   Pressed    X: 246, Y:131
   Moving     X: 248, Y:132
   Moving     X: 250, Y:133
   Moving     X: 258, Y:135
   Moving     X: 270, Y:136
   Moving     X: 285, Y:132
   Moving     X: 300, Y:126
   Moving     X: 309, Y:122
   Moving     X: 310, Y:119
   Released   X: 310, Y:119
   ```

### Issues/PRs references


Co-authored-by: Gunar Schorcht <[email protected]>

drivers/stmpe811/Makefile.include

@@ -3,3 +3,7 @@ USEMODULE_INCLUDES += $(USEMODULE_INCLUDES_stmpe811)
 
 PSEUDOMODULES += stmpe811_i2c
 PSEUDOMODULES += stmpe811_spi
+
+ifneq (,$(filter touch_dev,$(USEMODULE)))
+  CFLAGS += '-DSTMPE811_FIFO_THRESHOLD_ENABLED=1'
+endif

drivers/stmpe811/stmpe811.c

@@ -46,6 +46,23 @@
 #define ADDR                (dev->params.addr)
 #endif
 
+#ifndef STMPE811_FIFO_THRESHOLD_ENABLED
+#define STMPE811_FIFO_THRESHOLD_ENABLED    (0)
+#endif
+
+/* The driver only works reliably with FIFO threshold interrupts if the FIFO
+ * threshold is at least 2. The reason is that all interrupts are cleared when
+ * the status is checked in `stmpe811_read_touch_state` but the FIFO Threshold
+ * interrupt is asserted again immediately since the FIFO is not read so that
+ * a new interrupt is pending. On the other hand, the Touch Detected interrupt
+ * does not work reliably for the release event if only the Touch Detected
+ * interrupt in `stmpe811_read_touch_state` is cleared. The workaround is
+ * to set the FIFO threshold to at least 2 to introduce a small delay between
+ * the Touch Detect interrupt on a touch and the first FIFO threshold
+ * interrupt. */
+#ifndef STMPE811_FIFO_THRESHOLD
+#define STMPE811_FIFO_THRESHOLD     (STMPE811_FIFO_THRESHOLD_ENABLED ? 2 : 1)
+#endif
 
 #if IS_USED(MODULE_STMPE811_SPI) /* using SPI mode */
 static inline void _acquire(const stmpe811_t *dev)
@@ -194,7 +211,7 @@ int stmpe811_init(stmpe811_t *dev, const stmpe811_params_t *params, stmpe811_eve
     }
 
     /* check mode configuration */
-    if(_stmpe811_check_mode(dev) != 0) {
+    if (_stmpe811_check_mode(dev) != 0) {
         DEBUG("[stmpe811] error: couldn't setup SPI\n");
         return -EIO;
     }
@@ -257,7 +274,7 @@ int stmpe811_init(stmpe811_t *dev, const stmpe811_params_t *params, stmpe811_eve
     ret += _write_reg(dev, STMPE811_TSC_CFG, reg);
 
     /* set fifo threshold */
-    ret += _write_reg(dev, STMPE811_FIFO_TH, 0x01);
+    ret += _write_reg(dev, STMPE811_FIFO_TH, STMPE811_FIFO_THRESHOLD);
 
     /* reset fifo */
     _reset_fifo(dev);
@@ -287,7 +304,9 @@ int stmpe811_init(stmpe811_t *dev, const stmpe811_params_t *params, stmpe811_eve
         }
 
         /* Enable touchscreen interrupt */
-        ret += _write_reg(dev, STMPE811_INT_EN, STMPE811_INT_EN_TOUCH_DET);
+        ret += _write_reg(dev, STMPE811_INT_EN,
+                          STMPE811_INT_EN_TOUCH_DET |
+                          (STMPE811_FIFO_THRESHOLD_ENABLED ? STMPE811_INT_EN_FIFO_TH : 0));
 
         /* Enable global interrupt */
         ret += _write_reg(dev, STMPE811_INT_CTRL,
@@ -341,6 +360,14 @@ int stmpe811_read_touch_position(stmpe811_t *dev, stmpe811_touch_position_t *pos
     }
 #endif
 
+    /* Reset the FIFO, otherwise new touch data will be processed with a delay
+     * if the rate of calling this function to read the FIFO is slower than
+     * the rate at which the FIFO is filled. The reason for this is that with
+     * each call of this function only the oldest touch data is read
+     * value by value from the FIFO. Gestures, for example, can't be
+     * implemented with such a behavior. */
+    _reset_fifo(dev);
+
     /* Release device bus */
     _release(dev);
 

makefiles/driver_with_touch_dev.mk

@@ -4,7 +4,7 @@ TOUCH_DEV_INTERFACE ?= $(MODULE)_touch_dev.c
 # by default include all .c files except <module>_touch_dev.c
 SRC = $(filter-out $(TOUCH_DEV_INTERFACE),$(wildcard *.c))
 
-# only include <module>_touch_dev.c if saul module is used
+# only include <module>_touch_dev.c if touch_dev module is used
 ifneq (,$(filter touch_dev,$(USEMODULE)))
   SRC += $(TOUCH_DEV_INTERFACE)
 endif