:mod:`frequencyio`
==================

.. py:module:: frequencyio

.. autoapi-nested-parse::

   Support for frequency based protocols

   .. warning:: This module is not available in SAMD21 builds. See the
     :ref:`module-support-matrix` for more info.

   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 time
     import frequencyio
     import board

     frequency = frequencyio.FrequencyIn(board.D11)
     frequency.capture_period = 15
     time.sleep(0.1)

   This example will initialize the the device, set
   :py:data:`~frequencyio.FrequencyIn.capture_period`, and then sleep 0.1 seconds.
   CircuitPython will automatically turn off FrequencyIn capture when it resets all
   hardware after program completion. Use ``deinit()`` or a ``with`` statement
   to do it yourself.



.. raw:: html

    <p>
    <details>
    <summary>Available on these boards</summary>
    <ul>
    <li> ATMegaZero ESP32-S2
    <li> Adafruit EdgeBadge
    <li> Adafruit Feather ESP32-S2 TFT
    <li> Adafruit Feather ESP32S2
    <li> Adafruit Feather M4 CAN
    <li> Adafruit Feather M4 Express
    <li> Adafruit FunHouse
    <li> Adafruit Grand Central M4 Express
    <li> Adafruit Hallowing M4 Express
    <li> Adafruit ItsyBitsy M4 Express
    <li> Adafruit MagTag
    <li> Adafruit Matrix Portal M4
    <li> Adafruit Metro ESP32S2
    <li> Adafruit Metro M4 Airlift Lite
    <li> Adafruit Metro M4 Express
    <li> Adafruit Monster M4SK
    <li> Adafruit PyGamer
    <li> Adafruit PyPortal
    <li> Adafruit PyPortal Pynt
    <li> Adafruit PyPortal Titano
    <li> Adafruit Pybadge
    <li> Adafruit QT Py ESP32S2
    <li> Adafruit Trellis M4 Express
    <li> AloriumTech Evo M51
    <li> Artisense Reference Design RD00
    <li> BDMICRO VINA-D51
    <li> BastWiFi
    <li> CP32-M4
    <li> Capable Robot Programmable USB Hub
    <li> CircuitBrains Deluxe
    <li> CrumpS2
    <li> DynOSSAT-EDU-OBC
    <li> ESP 12k NodeMCU
    <li> Feather ESP32S2 without PSRAM
    <li> FeatherS2
    <li> FeatherS2 Neo
    <li> FeatherS2 PreRelease
    <li> Franzininho WIFI w/Wroom
    <li> Franzininho WIFI w/Wrover
    <li> Gravitech Cucumber M
    <li> Gravitech Cucumber MS
    <li> Gravitech Cucumber R
    <li> Gravitech Cucumber RS
    <li> HMI-DevKit-1.1
    <li> Kaluga 1
    <li> LILYGO TTGO T8 ESP32-S2 w/Display
    <li> MORPHEANS MorphESP-240
    <li> MicroDev microS2
    <li> Mini SAM M4
    <li> Oak Dev Tech PixelWing ESP32S2
    <li> PyCubedv04
    <li> PyCubedv04-MRAM
    <li> PyCubedv05
    <li> PyCubedv05-MRAM
    <li> S2Mini
    <li> S2Pico
    <li> SAM E54 Xplained Pro
    <li> SAM32v26
    <li> Saola 1 w/Wroom
    <li> Saola 1 w/Wrover
    <li> Seeeduino Wio Terminal
    <li> Silicognition LLC M4-Shim
    <li> SparkFun MicroMod SAMD51 Processor
    <li> SparkFun Thing Plus - SAMD51
    <li> Sprite_v2b
    <li> TG-Boards' Datalore IP M4
    <li> Targett Module Clip w/Wroom
    <li> Targett Module Clip w/Wrover
    <li> The Open Book Feather
    <li> Thingz - Galaxia
    <li> TinyS2
    <li> UARTLogger II
    <li> Winterbloom Sol
    <li> nanoESP32-S2  w/Wrover
    <li> nanoESP32-S2 w/Wroom
    </ul>
    </details>
    </p>




.. py:class:: FrequencyIn(pin: microcontroller.Pin, capture_period: int = 10)

   Read a frequency signal

   FrequencyIn is used to measure the frequency, in hertz, of a digital signal
   on an incoming pin. Accuracy has shown to be within 10%, if not better. It
   is recommended to utilize an average of multiple samples to smooth out readings.

   Frequencies below 1KHz are not currently detectable.

   FrequencyIn will not determine pulse width (use ``PulseIn``).

   Create a FrequencyIn object associated with the given pin.

   :param ~microcontroller.Pin pin: Pin to read frequency from.
   :param int capture_period: Keyword argument to set the measurement period, in
                              milliseconds. Default is 10ms; range is 1ms - 500ms.

   Read the incoming frequency from a pin::

     import frequencyio
     import board

     frequency = frequencyio.FrequencyIn(board.D11)

     # Loop while printing the detected frequency
     while True:
         print(frequency.value)

         # Optional clear() will reset the value
         # to zero. Without this, if the incoming
         # signal stops, the last reading will remain
         # as the value.
         frequency.clear()

   .. py:attribute:: capture_period
      :annotation: :int

      The capture measurement period. Lower incoming frequencies will be measured
      more accurately with longer capture periods. Higher frequencies are more
      accurate with shorter capture periods.

      .. note:: When setting a new ``capture_period``, all previous capture information is
                cleared with a call to ``clear()``.


   .. py:method:: deinit() -> None

      Deinitialises the FrequencyIn and releases any hardware resources for reuse.


   .. py:method:: __enter__() -> FrequencyIn

      No-op used by Context Managers.


   .. py:method:: __exit__() -> None

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


   .. py:method:: pause() -> None

      Pause frequency capture.


   .. py:method:: resume() -> None

      Resumes frequency capture.


   .. py:method:: clear() -> None

      Clears the last detected frequency capture value.


   .. py:method:: __get__(index: int) -> int

      Returns the value of the last frequency captured.