micropython · jimmo · Aug 15, 2023 · Sep 10, 2022 · Sep 10, 2022 · Sep 12, 2022
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
@@ -427,6 +427,42 @@ supported ADC resolutions:
   - ``ADC.WIDTH_12BIT`` = 12
 
 
+Pulse Counter (pin pulse/edge counting)
+---------------------------------------
+
+The ESP32 provides up to 8 pulse counter peripherals depending on the hardware,
+with id 0..7. These can be configured to count rising and/or falling edges on
+any input pin.
+
+Use the :ref:`esp32.PCNT <esp32.PCNT>` class::
+
+    from machine import Pin
+    from esp32 import PCNT
+
+    counter = PCNT(0, pin=Pin(2), rising=PCNT.INCREMENT)        # create counter
+    counter.start()                                             # start counter
+    count = counter.value()                                     # read count, -32768..32767
+    counter.value(0)                                            # reset counter
+    count = counter.value(0)                                    # read and reset
+
+The PCNT hardware supports monitoring multiple pins in a single unit to
+implement quadrature decoding or up/down signal counters.
+
+See the :ref:`machine.Counter <machine.Counter>` and
+:ref:`machine.Encoder <machine.Encoder>` classes for simpler abstractions of
+common pulse counting applications::
+
+    from machine import Pin, Counter
+
+    counter = Counter(0, Pin(2))    # create a counter as above and start it
+    count = counter.value()         # read the count as an arbitrary precision signed integer
+
+    encoder = Encoder(0, Pin(12), Pin(14))    # create an encoder and begin counting
+    count = encoder.value()                   # read the count as an arbitrary precision signed integer
+
+Note that the id passed to these ``Counter()`` and ``Encoder()`` objects must be
+a PCNT id.
+
 Software SPI bus
 ----------------
 

diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
@@ -164,6 +164,153 @@ Constants
 
     Used in `idf_heap_info`.
 
+
+.. _esp32.PCNT:
+
+PCNT
+----
+
+This class provides access to the ESP32 hardware support for pulse counting.
+There are 8 pulse counter units, with id 0..7.
+
+See the :ref:`machine.Counter <machine.Counter>` and
+:ref:`machine.Encoder <machine.Encoder>` classes for simpler and portable
+abstractions of common pulse counting applications. These classes are
+implemented as thin Python shims around :class:`PCNT`.
+
+.. class:: PCNT(id, *, ...)
+
+    Returns the singleton PCNT instance for the given unit ``id``.
+
+    Keyword arguments are passed to the ``init()`` method as described
+    below.
+
+.. method:: PCNT.init(*, ...)
+
+    (Re-)initialise a pulse counter unit. Supported keyword arguments are:
+
+      - ``channel``: see description below
+      - ``pin``: the input Pin to monitor for pulses
+      - ``rising``: an action to take on a rising edge - one of
+        ``PCNT.INCREMENT``, ``PCNT.DECREMENT`` or ``PCNT.IGNORE`` (the default)
+      - ``falling``: an action to take on a falling edge (takes the save values
+        as the ``rising`` argument).
+      - ``mode_pin``: ESP32 pulse counters support monitoring a second pin and
+        altering the behaviour of the counter based on its level - set this
+        keyword to any input Pin
+      - ``mode_low``: set to either ``PCNT.HOLD`` or ``PCNT.REVERSE`` to
+        either suspend counting or reverse the direction of the counter (i.e.,
+        ``PCNT.INCREMENT`` behaves as ``PCNT.DECREMENT`` and vice versa)
+        when ``mode_pin`` is low
+      - ``mode_high``: as ``mode_low`` but for the behaviour when ``mode_pin``
+        is high
+      - ``filter``: set to a value 1..1023, in ticks of the 80MHz clock, to
+        enable the pulse width filter
+      - ``min``: set to the minimum level of the counter value when
+        decrementing (-32768..-1) or 0 to disable
+      - ``max``: set to the maximum level of the counter value when
+        incrementing (1..32767) or 0 to disable
+      - ``threshold0``: sets the counter value for the
+        ``PCNT.IRQ_THRESHOLD0`` event (see ``irq`` method)
+      - ``threshold1``: sets the counter value for the
+        ``PCNT.IRQ_THRESHOLD1`` event (see ``irq`` method)
+      - ``value``: can be set to ``0`` to reset the counter value
+
+    The hardware initialisation is done in stages and so some of the keyword
+    arguments can be used in groups or in isolation to partially reconfigure a
+    unit:
+
+      - the ``pin`` keyword (optionally combined with ``mode_pin``) can be used
+        to change just the bound pin(s)
+      - ``rising``, ``falling``, ``mode_low`` and ``mode_high`` can be used
+        (singly or together) to change the counting logic - omitted keywords
+        use their default (``PCNT.IGNORE`` or ``PCNT.NORMAL``)
+      - ``filter`` can be used to change only the pulse width filter (with 0
+        disabling it)
+      - each of ``min``, ``max``, ``threshold0`` and ``threshold1`` can
+        be used to change these limit/event values individually; however,
+        setting any will reset the counter to zero (i.e., they imply
+        ``value=0``)
+
+    Each pulse counter unit supports two channels, 0 and 1, each able to
+    monitor different pins with different counting logic but updating the same
+    counter value. Use ``channel=1`` with the ``pin``, ``rising``, ``falling``,
+    ``mode_pin``, ``mode_low`` and ``mode_high`` keywords to configure the
+    second channel.
+
+    The second channel can be used to configure 4X quadrature decoding with a
+    single counter unit::
+
+        pin_a = Pin(2, Pin.INPUT, pull=Pin.PULL_UP)
+        pin_b = Pin(3, Pin.INPUT, pull=Pin.PULL_UP)
+        rotary = PCNT(0, min=-32000, max=32000)
+        rotary.init(channel=0, pin=pin_a, falling=PCNT.INCREMENT, rising=PCNT.DECREMENT, mode_pin=pin_b, mode_low=PCNT.REVERSE)
+        rotary.init(channel=1, pin=pin_b, falling=PCNT.DECREMENT, rising=PCNT.INCREMENT, mode_pin=pin_a, mode_low=PCNT.REVERSE)
+        rotary.start()
+
+.. method:: PCNT.value([value])
+
+    Call this method with no arguments to return the current counter value.
+
+    If the optional *value* argument is set to ``0`` then the counter is
+    reset (but the previous value is returned). Read and reset is not atomic and
+    so it is possible for a pulse to be missed. Any value other than ``0`` will
+    raise an error.
+
+.. method:: PCNT.irq(handler=None, trigger=PCNT.IRQ_ZERO)
+
+    ESP32 pulse counters support interrupts on these counter events:
+
+      - ``PCNT.IRQ_ZERO``: the counter has reset to zero
+      - ``PCNT.IRQ_MIN``: the counter has hit the ``min`` value
+      - ``PCNT.IRQ_MAX``: the counter has hit the ``max`` value
+      - ``PCNT.IRQ_THRESHOLD0``: the counter has hit the ``threshold0`` value
+      - ``PCNT.IRQ_THRESHOLD1``: the counter has hit the ``threshold1`` value
+
+    ``trigger`` should be a bit-mask of the desired events OR'ed together. The
+    ``handler`` function should take a single argument which is the
+    :class:`PCNT` instance that raised the event.
+
+    This method returns a callback object. The callback object can be used to
+    access the bit-mask of events that are outstanding on the PCNT unit.::
+
+        def pcnt_irq(pcnt):
+            flags = pcnt.irq().flags()
+            if flags & PCNT.IRQ_ZERO:
+               # reset
+            if flags & PCNT.IRQ_MAX:
+               # overflow...
+            ... etc
+
+        pcnt.irq(handler=pcnt_irq, trigger=PCNT.IRQ_ZERO | PCNT.IRQ_MAX | ...)
+
+    **Note:** Accessing ``irq.flags()`` will clear the flags, so only call it
+    once per invocation of the handler.
+
+    The handler is called with the MicroPython scheduler and so will run at a
+    point after the interrupt. If another interrupt occurs before the handler
+    has been called then the events will be coalesced together into a single
+    call and the bit mask will indicate all events that have occurred.
+
+    To avoid race conditions between a handler being called and retrieving the
+    current counter value, the ``value()`` method will force execution of any
+    pending events before returning the current counter value (and potentially
+    resetting the value).
+
+    Only one handler can be in place per-unit. Set ``handler`` to ``None`` to
+    disable the event interrupt.
+
+
+.. Note::
+    ESP32 pulse counters reset to *zero* when reaching the minimum or maximum
+    value. Thus the ``IRQ_ZERO`` event will also trigger when either of these
+    events occurs.
+
+See the :ref:`machine.Counter <machine.Counter>` and
+:ref:`machine.Encoder <machine.Encoder>` classes for simpler abstractions of
+common pulse counting applications.
+
+
 .. _esp32.RMT:
 
 RMT

diff --git a/docs/library/machine.Counter.rst b/docs/library/machine.Counter.rst
@@ -0,0 +1,93 @@
+.. currentmodule:: machine
+.. _machine.Counter:
+
+class Counter -- pulse counter
+==============================
+
+Counter implements pulse counting by monitoring an input signal and counting
+rising or falling edges.
+
+Minimal example usage::
+
+    from machine import Pin, Counter
+
+    counter = Counter(0, Pin(0, Pin.IN))  # create Counter for pin 0 and begin counting
+    value = counter.value()               # retrieve current pulse count
+
+Availability: **ESP32**
+
+Constructors
+------------
+
+.. class:: Counter(id, ...)
+
+   Returns the singleton Counter object for the the given *id*. Values of *id*
+   depend on a particular port and its hardware. Values 0, 1, etc. are commonly
+   used to select hardware block #0, #1, etc.
+
+   Additional arguments are passed to the :meth:`init` method described below,
+   and will cause the Counter instance to be re-initialised and reset.
+
+   On ESP32, the *id* corresponds to a :ref:`PCNT unit <esp32.PCNT>`.
+
+Methods
+-------
+
+.. method:: Counter.init(src, *, ...)
+
+   Initialise and reset the Counter with the given parameters:
+
+   - *src* specifies the input pin as a :ref:`machine.Pin <machine.Pin>` object.
+     May be omitted on ports that have a predefined pin for a given hardware
+     block.
+
+   Additional keyword-only parameters that may be supported by a port are:
+
+   - *edge* specifies the edge to count. Either ``Counter.RISING`` (the default)
+     or ``Counter.FALLING``. *(Supported on ESP32)*
+
+   - *direction* specifies the direction to count. Either ``Counter.UP`` (the
+     default) or ``Counter.DOWN``. *(Supported on ESP32)*
+
+   - *filter_ns* specifies a minimum period of time in nanoseconds that the
+     source signal needs to be stable for a pulse to be counted. Implementations
+     should use the longest filter supported by the hardware that is less than
+     or equal to this value. The default is 0 (no filter). *(Supported on ESP32)*
+
+.. method:: Counter.deinit()
+
+   Stops the Counter, disabling any interrupts and releasing hardware resources.
+   A Soft Reset should deinitialize all Counter objects.
+
+.. method:: Counter.value([value])
+
+   Get, and optionally set, the counter value as a signed integer.
+   Implementations must aim to do the get and set atomically (i.e. without
+   leading to skipped counts).
+
+   This counter value could exceed the range of a :term:`small integer`, which
+   means that calling :meth:`Counter.value` could cause a heap allocation, but
+   implementations should aim to ensure that internal state only uses small
+   integers and therefore will not allocate until the user calls
+   :meth:`Counter.value`.
+
+   For example, on ESP32, the internal state counts overflows of the hardware
+   counter (every 32000 counts), which means that it will not exceed the small
+   integer range until ``2**30 * 32000`` counts (slightly over 1 year at 1MHz).
+
+   In general, it is recommended that you should use ``Counter.value(0)`` to reset
+   the counter (i.e. to measure the counts since the last call), and this will
+   avoid this problem.
+
+Constants
+---------
+
+.. data:: Counter.RISING
+          Counter.FALLING
+
+   Select the pulse edge.
+
+.. data:: Counter.UP
+          Counter.DOWN
+
+   Select the counting direction.
diff --git a/docs/library/machine.Encoder.rst b/docs/library/machine.Encoder.rst
@@ -0,0 +1,72 @@
+.. currentmodule:: machine
+.. _machine.Encoder:
+
+class Encoder -- quadrature decoding
+====================================
+
+Encoder implements decoding of quadrature signals as commonly output from
+rotary encoders, by counting either up or down depending on the order of two
+input pulses.
+
+Minimal example usage::
+
+    from machine import Pin, Encoder
+
+    counter = Counter(0, Pin(0, Pin.IN), Pin(1, Pin.IN))   # create Encoder for pins 0, 1 and begin counting
+    value = counter.value()                                # retrieve current count
+
+Availability: **ESP32**
+
+Constructors
+------------
+
+.. class:: Encoder(id, ...)
+
+   Returns the singleton Encoder object for the the given *id*. Values of *id*
+   depend on a particular port and its hardware. Values 0, 1, etc. are commonly
+   used to select hardware block #0, #1, etc.
+
+   Additional arguments are passed to the :meth:`init` method described below,
+   and will cause the Encoder instance to be re-initialised and reset.
+
+   On ESP32, the *id* corresponds to a :ref:`PCNT unit <esp32.PCNT>`.
+
+Methods
+-------
+
+.. method:: Encoder.init(phase_a, phase_b, *, ...)
+
+   Initialise and reset the Encoder with the given parameters:
+
+   - *phase_a* specifies the first input pin as a
+     :ref:`machine.Pin <machine.Pin>` object.
+
+   - *phase_b* specifies the second input pin as a
+     :ref:`machine.Pin <machine.Pin>` object.
+
+   These pins may be omitted on ports that have predefined pins for a given
+   hardware block.
+
+   Additional keyword-only parameters that may be supported by a port are:
+
+   - *filter_ns* specifies a minimum period of time in nanoseconds that the
+     source signal needs to be stable for a pulse to be counted. Implementations
+     should use the longest filter supported by the hardware that is less than
+     or equal to this value. The default is 0 (no filter). *(Supported on ESP32)*
+
+   - *phases* specifies the number of signal edges to count and thus the
+     granularity of the decoding. e.g. 4 phases corresponds to "4x quadrature
+     decoding", and will result in four counts per pulse. Ports may support
+     either 1, 2, or 4 phases and the default is 1 phase. *(Supported on ESP32)*
+
+.. method:: Encoder.deinit()
+
+   Stops the Encoder, disabling any interrupts and releasing hardware resources.
+   A Soft Reset should deinitialize all Encoder objects.
+
+.. method:: Encoder.value([value])
+
+   Get, and optionally set, the encoder value as a signed integer.
+   Implementations should aim to do the get and set atomically.
+
+   See :meth:`machine.Counter.value` for details about overflow of this value.
diff --git a/docs/library/machine.rst b/docs/library/machine.rst
@@ -262,6 +262,8 @@ Classes
    machine.I2S.rst
    machine.RTC.rst
    machine.Timer.rst
+   machine.Counter.rst
+   machine.Encoder.rst
    machine.WDT.rst
    machine.SD.rst
    machine.SDCard.rst
diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst
@@ -188,6 +188,13 @@ Glossary
         Most MicroPython boards make a REPL available over a UART, and this is
         typically accessible on a host PC via USB.
 
+    small integer
+        MicroPython optimises the internal representation of integers such that
+        "small" values do not take up space on the heap, and calculations with
+        them do not require heap allocation. On most 32-bit ports, this
+        corresponds to values in the interval ``-2**30 <= x < 2**30``, but this
+        should be considered an implementation detail and not relied upon.
+
     stream
         Also known as a "file-like object". A Python object which provides
         sequential read-write access to the underlying data. A stream object