TTP223Row Arduino Library

A non-blocking Arduino library for recognizing taps, multi-finger touches, long presses, and directional swipes across a linear row of 2 to 5 TTP223 capacitive touch sensors.

Persian documentation: README-FA.md
Author: Hamidreza Milaninia — ARDUnia

• Supports 2 to 5 inline sensors.
• Uses millis() and never blocks the main loop.
• Distinguishes simultaneous multi-finger touches from sequential taps.
• Detects exact left-to-right, right-to-left, and round-trip swipe sequences.
• Uses fixed-size internal buffers to remain predictable on AVR boards.
• Preserves the original HowTouch() API and adds the clearer readGesture() alias.
• Has no third-party dependencies.

Open Tools > Manage Libraries, search for TTP223Row, and select Install.

Add the library from the PlatformIO Registry or add this line to platformio.ini:

lib_deps = ARDUnia/TTP223Row

Download this repository as a ZIP file, then select Sketch > Include Library > Add .ZIP Library in the Arduino IDE.

Connect each TTP223 signal output to a separate digital input. The constructor arguments must follow the physical left-to-right order of the sensors. The library expects the standard active-HIGH TTP223 output mode.

#include <TTP223Row.h>

TTP223Row touchRow(4, 2, 3, 4, 5);

void setup() {
  Serial.begin(115200);
  if (!touchRow.begin()) {
    Serial.println("Invalid TTP223Row configuration");
  }
}

void loop() {
  String gesture = touchRow.readGesture();
  if (gesture != "") {
    Serial.println(gesture);
  }
}

HowTouch() remains available as a backward-compatible alias for readGesture().

Mixed or ambiguous tap patterns are intentionally ignored rather than being reported as false multi-finger gestures.

Default values are:

All touches shorter than the long-press threshold are eligible taps, so there is no unclassified timing gap. Configure the values before or after begin():

bool accepted = touchRow.setTiming(
  800,   // longPressMin
  350,   // multiTapGap
  50,    // swipeMinDuration
  1200   // swipeMaxDuration
);

Invalid timing values are rejected and return false.

The constructor rejects sensor counts outside 2 to 5, missing required pins, and duplicate pins. Use isValid() or the return value of begin() to detect invalid configuration.

• BasicUsage: validation and basic gesture reading
• MediaPlayerController: media actions with swipe and tap gestures
• SmartHomeLighting: relay or LED control using a three-sensor panel

The CI workflow runs deterministic host-side gesture tests and compiles every example for Arduino Uno, ESP8266, and ESP32. See CONTRIBUTING.md for the contribution workflow and CHANGELOG.md for release history.

Released under the MIT License.