docs/library/machine: Add documentation of Counter and Encoder classes.

jonathanhogg · jonathanhogg · commit 0c3aa6ecb2e7 · 2024-10-29T14:53:39.000Z
Add documentation for the core Counter/Encoder API as currently implemented by the esp32 port. This documentation is a simplification of that in PR #8072.
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
@@ -468,6 +468,26 @@ Use the :ref:`esp32.PCNT <esp32.PCNT>` class::
     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. These classes are implemented as thin Python
+shims around the ``PCNT()`` class::
+
+    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 of these ``Counter()`` and ``Encoder()`` objects is an
+arbitrary number, each uniquely identified object will be allocated a free PCNT
+unit.
+
 
 Software SPI bus
 ----------------
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
@@ -282,6 +282,10 @@ There are 8 pulse counter units, with id 0..7.
     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:
 
diff --git a/docs/library/machine.Counter.rst b/docs/library/machine.Counter.rst
@@ -0,0 +1,74 @@
+.. 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 port
+
+Constructors
+------------
+
+.. class:: Counter(id, ...)
+
+   Construct a Counter object with 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
+   ``init()`` method described below.
+
+Methods
+-------
+
+.. method:: Counter.init(src, *, ...)
+
+   Initialise 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``.
+
+   - *direction* specifies the direction to count. Either ``Counter.UP`` (the
+     default) or ``Counter.DOWN``.
+
+   - *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).
+
+.. 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 should aim to do the get and set atomically.
+
+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,64 @@
+.. 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 port
+
+Constructors
+------------
+
+.. class:: Encoder(id, ...)
+
+   Construct an Encoder object with 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
+   ``init()`` method described below.
+
+Methods
+-------
+
+.. method:: Encoder.init(phase_a, phase_b, *, ...)
+
+   Initialise the Encoder with the given parameters:
+
+   - *phase_a* specifies the first input pin as a
+     :ref:`machine.Pin <machine.Pin>` object.
+
+   - *phase_a* 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).
+
+   - *phases* specifies the number of signal edges to count and thus the
+     granularity of the decoding. Ports may support either 1, 2 or 4 phases.
+
+.. 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.
diff --git a/docs/library/machine.rst b/docs/library/machine.rst
@@ -268,6 +268,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
