_touch.py

# This file is part of espzero, automatically synced from
# https://github.com/roboticsware/espzero at revision 24cae2bc1c028458052675181e95f2a08fdf7481.
# Do not edit this file directly — run update_user_libs.py espzero instead.

"""
espzero/_touch.py
Capacitive touch sensor class for ESP32.

Uses the ESP32's built-in capacitive touch peripheral (TouchPad),
which is available on pins T0–T9 of WROOM/WROVER modules.
"""


class CapTouch:
    """
    Represents an ESP32 built-in capacitive touch pin (T0–T9).

    Unlike ``TouchSensor`` (which wraps an external TTP223 IC), this class
    uses the ESP32's hardware touch peripheral directly via
    ``machine.TouchPad``.

    The raw reading decreases when the pin is touched.  A reading below
    *threshold* is reported as a touch.

    Usage::

        from espzero import CapTouch
        touch = CapTouch(pin=4)   # GPIO 4 = T0 on WROOM
        if touch.is_touched:
            print("Touched!")

    :param int pin: GPIO number connected to a touch-capable pin.
    :param int threshold: Raw value below which a touch is detected. Default 300.
    """

    def __init__(self, pin, threshold=300):
        from machine import TouchPad, Pin
        self._touch     = TouchPad(Pin(pin))
        self._threshold = threshold
        self._pin_num   = pin

    @property
    def value(self):
        """Raw capacitance reading. Lower values indicate a touch."""
        return self._touch.read()

    @property
    def is_touched(self):
        """``True`` if the raw value is below the configured threshold."""
        return self._touch.read() < self._threshold

    @property
    def threshold(self):
        """Touch detection threshold (raw units)."""
        return self._threshold

    @threshold.setter
    def threshold(self, value):
        self._threshold = int(value)

    def __str__(self):
        return "CapTouch(pin={}, threshold={})".format(
            self._pin_num, self._threshold
        )