:mod:`touchio`
==============

.. py:module:: touchio

.. autoapi-nested-parse::

   Touch related IO

   The `touchio` module contains classes to provide access to touch IO typically
   accelerated by hardware on the onboard microcontroller.

   All classes change hardware state and should be deinitialized when they
   are no longer needed if the program continues after use. To do so, either
   call :py:meth:`!deinit` or use a context manager. See
   :ref:`lifetime-and-contextmanagers` for more info.

   For example::

     import touchio
     from board import *

     touch_pin = touchio.TouchIn(D6)
     print(touch_pin.value)

   This example will initialize the the device, and print the
   :py:data:`~touchio.TouchIn.value`.





.. py:class:: TouchIn(pin: microcontroller.Pin)

   Read the state of a capacitive touch sensor

   Usage::

      import touchio
      from board import *

      touch = touchio.TouchIn(A1)
      while True:
          if touch.value:
              print("touched!")

   .. attribute:: value
      :annotation: :Any

      Whether the touch pad is being touched or not. (read-only)

      True when `raw_value` > `threshold`.


   .. attribute:: raw_value
      :annotation: :Any

      The raw touch measurement as an `int`. (read-only)


   .. attribute:: threshold
      :annotation: :Any

      Minimum `raw_value` needed to detect a touch (and for `value` to be `True`).

      When the **TouchIn** object is created, an initial `raw_value` is read from the pin,
      and then `threshold` is set to be 100 + that value.

      You can adjust `threshold` to make the pin more or less sensitive.


   .. method:: deinit(self)


      Deinitialises the TouchIn and releases any hardware resources for reuse.


   .. method:: __enter__(self)


      No-op used by Context Managers.


   .. method:: __exit__(self)


      Automatically deinitializes the hardware when exiting a context. See
      :ref:`lifetime-and-contextmanagers` for more info.