8000 docs/library/machine: Add documentation of Counter and Encoder classes. · kholia/micropython@11612e8 · GitHub
[go: up one dir, main page]
Skip to content

Commit 11612e8

Browse files
jonathanhoggbuilder
jonathanhogg
authored and
builder
committed
docs/library/machine: Add documentation of Counter and Encoder classes.
Add documentation for the core Counter/Encoder API as currently implemented by the esp32 port. This documentation is a simplification of that in PR micropython#8072.
1 parent 1aa83b2 commit 11612e8

File tree

5 files changed

+164
-0
lines changed

5 files changed

+164
-0
lines changed

‎docs/esp32/quickref.rst

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -551,6 +551,26 @@ Use the :ref:`esp32.PCNT <esp32.PCNT>` class::
551551
counter.value(0) # reset counter
552552
count = counter.value(0) # read and reset
553553

554+
The PCNT hardware supports monitoring multiple pins in a single unit to
555+
implement quadrature decoding or up/down signal counters.
556+
557+
See the :ref:`machine.Counter <machine.Counter>` and
558+
:ref:`machine.Encoder <machine.Encoder>` classes for simpler abstractions of
559+
common pulse counting applications. These classes are implemented as thin Python
560+
shims around the ``PCNT()`` class::
561+
562+
from machine import Pin, Counter
563+
564+
counter = Counter(0, Pin(2)) # create a counter as above and start it
565+
count = counter.value() # read the count as an arbitrary precision signed integer
566+
567+
encoder = Encoder(0, Pin(12), Pin(14)) # create an encoder and begin counting
568+
count = encoder.value() # read the count as an arbitrary precision signed integer
569+
570+
Note that the id of these ``Counter()`` and ``Encoder()`` objects is an
571+
arbitrary number, each uniquely identified object will be allocated a free PCNT
572+
unit.
573+
554574

555575
Software SPI bus
556576
----------------

‎docs/library/esp32.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -282,6 +282,10 @@ There are 8 pulse counter units, with id 0..7.
282282
value. Thus the ``IRQ_ZERO`` event will also trigger when either of these
283283
events occurs.
284284

285+
See the :ref:`machine.Counter <machine.Counter>` and
286+
:ref:`machine.Encoder <machine.Encoder>` classes for simpler abstractions of
287+
common pulse counting applications.
288+
285289

286290
.. _esp32.RMT:
287291

‎docs/library/machine.Counter.rst

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
.. currentmodule:: machine
2+
.. _machine.Counter:
3+
4+
class Counter -- pulse counter
5+
==============================
6+
7+
Counter implements pulse counting by monitoring an input signal and counting
8+
rising or falling edges.
9+
10+
Minimal example usage::
11+
12+
from machine import Pin, Counter
13+
14+
counter = Counter(0, Pin(0, Pin.IN)) # create Counter for pin 0 and begin counting
15+
value = counter.value() # retrieve current pulse count
16+
17+
Availability: esp32 port
18+
19+
Constructors
20+
------------
21+
22+
.. class:: Counter(id, ...)
23+
24+
Construct a Counter object with the given id. Values of *id* depend on a
25+
particular port and its hardware. Values 0, 1, etc. are commonly used to
26+
select hardware block #0, #1, etc. Additional arguments are passed to the
27+
``init()`` method described below.
28+
29+
Methods
30+
-------
31+
32+
.. method:: Counter.init(src, *, ...)
33+
34+
Initialise the Counter with the given parameters:
35+
36+
- *src* specifies the input pin as a :ref:`machine.Pin <machine.Pin>` object.
37+
May be omitted on ports that have a predefined pin for a given hardware
38+
block.
39+
40+
Additional keyword-only parameters that may be supported by a port are:
41+
42+
- *edge* specifies the edge to count. Either ``Counter.RISING`` (the default)
43+
or ``Counter.FALLING``.
44+
45+
- *direction* specifies the direction to count. Either ``Counter.UP`` (the
46+
default) or ``Counter.DOWN``.
47+
48+
- *filter_ns* specifies a minimum period of time in nanoseconds that the
49+
source signal needs to be stable for a pulse to be counted. Implementations
50+
should use the longest filter supported by the hardware that is less than
51+
or equal to this value. The default is 0 (no filter).
52+
53+
.. method:: Counter.deinit()
54+
55+
Stops the Counter, disabling any interrupts and releasing hardware resources.
56+
A Soft Reset should deinitialize all Counter objects.
57+
58+
.. method:: Counter.value([value])
59+
60+
Get, and optionally set, the counter value as a signed integer.
61+
Implementations should aim to do the get and set atomically.
62+
63+
Constants
64+
---------
65+
66+
.. data:: Counter.RISING
67+
Counter.FALLING
68+
69+
Select the pulse edge.
70+
71+
.. data:: Counter.UP
72+
Counter.DOWN
73+
74+
Select the counting direction.

‎docs/library/machine.Encoder.rst

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
.. currentmodule:: machine
2+
.. _machine.Encoder:
3+
4+
class Encoder -- quadrature decoding
5+
====================================
6+
7+
Encoder implements decoding of quadrature signals as commonly output from
8+
rotary encoders, by counting either up or down depending on the order of two
9+
input pulses.
10+
11+
Minimal example usage::
12+
13+
from machine import Pin, Encoder
14+
15+
counter = Counter(0, Pin(0, Pin.IN), Pin(1, Pin.IN)) # create Encoder for pins 0, 1 and begin counting
16+
value = counter.value() # retrieve current count
17+
18+
Availability: esp32 port
19+
20+
Constructors
21+
------------
22+
23+
.. class:: Encoder(id, ...)
24+
25+
Construct an Encoder object with the given id. Values of *id* depend on a
26+
particular port and its hardware. Values 0, 1, etc. are commonly used to
27+
select hardware block #0, #1, etc. Additional arguments are passed to the
28+
``init()`` method described below.
29+
30+
Methods
31+
-------
32+
33+
.. method:: Encoder.init(phase_a, phase_b, *, ...)
34+
35+
Initialise the Encoder with the given parameters:
36+
37+
- *phase_a* specifies the first input pin as a
38+
:ref:`machine.Pin <machine.Pin>` object.
39+
40+
- *phase_a* specifies the second input pin as a
41+
:ref:`machine.Pin <machine.Pin>` object.
42+
43+
These pins may be omitted on ports that have predefined pins for a given
44+
hardware block.
45+
46+
Additional keyword-only parameters that may be supported by a port are:
47+
48+
- *filter_ns* specifies a minimum period of time in nanoseconds that the
49+
source signal needs to be stable for a pulse to be counted. Implementations
50+
should use the longest filter supported by the hardware that is less than
51+
or equal to this value. The default is 0 (no filter).
52+
53+
- *phases* specifies the number of signal edges to count and thus the
54+
granularity of the decoding. Ports may support either 1, 2 or 4 phases.
55+
56+
.. method:: Encoder.deinit()
57+
58+
Stops the Encoder, disabling any interrupts and releasing hardware resources.
59+
A Soft Reset should deinitialize all Encoder objects.
60+
61+
.. method:: Encoder.value([value])
62+
63+
Get, and optionally set, the encoder value as a signed integer.
64+
Implementations should aim to do the get and set atomically.

‎docs/library/machine.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,8 @@ Classes
267267
machine.I2S.rst
268268
machine.RTC.rst
269269
machine.Timer.rst
270+
machine.Counter.rst
271+
machine.Encoder.rst
270272
machine.WDT.rst
271273
machine.SD.rst
272274
machine.SDCard.rst

0 commit comments

Comments
 (0)
0