8000 docs\machine: Add Counter and Encoder classes. · micropython/micropython@129cac2 · GitHub
[go: up one dir, main page]
Skip to content

Commit 129cac2

Browse files
IhorNehrutsaIhorNehrutsa
committed
docs\machine: Add Counter and Encoder classes.
1 parent 1dedb65 commit 129cac2

File tree

3 files changed

+130
-0
lines changed

3 files changed

+130
-0
lines changed

‎docs/library/machine.Counter.rst

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
.. currentmodule:: machine
2+
.. _machine.Counter:
3+
4+
class Counter-- Pulse Counter
5+
=============================
6+
7+
This class provides access to hardware-supported pulse counting.
8+
9+
It is currently provided for ports:
10+
11+
* :ref:`ESP32 <esp32_machine.Counter>`
12+
* :ref:`MIMXRT <mimxrt_machine.Counter>`
13+
14+
Minimal example usage::
15+
16+
from machine import Pin, Counter
17+
18+
counter = Counter(0, src=Pin(0, mode=Pin.IN)) # create Counter object and start to count input pulses
19+
counter.init(filter_ns=1000) # switch source filtering on
20+
value = counter.value(0) # get current Counter value, set counter to 0
21+
counter.deinit() # turn off the Counter
22+
23+
print(counter) # show the Counter object properties
24+
25+
Constructor
26+
-----------
27+
28+
.. class:: Counter(id, src=None, \*, direction=Counter.UP, filter_ns=0)
29+
30+
- *id*. Values of *id* depend on a particular port and its hardware.
31+
Values 0, 1, etc. are commonly used to select hardware block #0, #1, etc.
32+
33+
- *src*. The Counter pulses input pin, which is usually a
34+
:ref:`machine.Pin <machine.Pin>` object, but a port may allow other values,
35+
like integers or strings, which designate a Pin in the *machine.Pin* class.
36+
It may be omitted on ports that have a predefined pin for *id*-specified hardware block.
37+
38+
- *direction* specifies the direction to count. Values for this include the constants
39+
``Counter.UP`` (default value) and ``Counter.DOWN``. Ports may support additional values or
40+
objects, such as a :ref:`machine.Pin <machine.Pin>` object to control the direction externally.
41+
42+
- *filter_ns* specifies a minimum period of time in nanoseconds that the source signal needs to
43+
be stable for a pulse to be counted. Implementations should use the longest filter supported
44+
by the hardware that is less than or equal to this value. The default is 0 – no filter.
45+
46+
Methods
47+
-------
48+
49+
.. method:: Counter.init(*, src, ...)
50+
51+
Modify the settings of the Counter object. See the **Constructor** for details about the parameters.
52+
53+
.. method:: Counter.deinit()
54+
55+
Stops the Counter, disables interrupts and releases hardware resources used by the counter.
56+
A Soft Reset involve deinitializing all Encoder objects.
57+
58+
.. method:: Counter.value([value])
59+
60+
Get, and optionally set, the counter value as a signed integer. Implementations should aim to do the get and set atomically.
61+
62+
Constants
63+
---------
64+
65+
.. data:: Counter.UP
66+
Counter.DOWN
67+
68+
Select the counter direction.

‎docs/library/machine.Encoder.rst

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
.. currentmodule:: machine
2+
.. _machine.Encoder:
3+
4+
class Encoder -- Quadrature Incremental Encoder
5+
===============================================
6+
7+
This class provides a hardware-supported Quadrature Incremental Encoder service.
8+
9+
If your port does not support hardware encoder use `Quadrature incremental encoder based on machine.Pin interrupts <https://github.com/IhorNehrutsa/MicroPython-quadrature-incremental-encoder>`_.
10+
See also Pin-interrupt-based encoders (and problems) from Peter Hinch `Incremental encoders <https://github.com/peterhinch/micropython-samples/blob/master/encoders/ENCODERS.md>`_.
11+
There is also `Dave Hylands an STM specific hardware-Timer-based solution <https://github.com/dhylands/upy-examples/blob/master/encoder.py>`_.
12+
13+
It is currently provided for ports:
14+
15+
* :ref:`ESP32 <esp32_machine.Encoder>`
16+
* :ref:`MIMXRT <mimxrt_machine.Encoder>`
17+
18+
Minimal example usage::
19+
20+
from machine import Pin, Encoder
21+
22+
enc = Encoder(id, phase_a=Pin(0), phase_b=Pin(1)) # create Quadrature Encoder object and start to encode input pulses
23+
enc.init(filter_ns=1000) # switch source filtering on
24+
value = enc.value(0) # get current Encoder value, set Encoder to 0
25+
enc.deinit() # turn off the Encoder
26+
27+
print(enc) # show the Encoder object properties
28+
29+
Constructor
30+
-----------
31+
32+
.. class:: Encoder(id, phase_a=None, phase_b=None, \*, filter_ns=0)
33+
34+
- *id*. Values of *id* depend on a particular port and its hardware.
35+
Values 0, 1, etc. are commonly used to select hardware block #0, #1, etc.
36+
37+
- *phase_a* and *phase_b* are the Quadrature encoder inputs, which are usually
38+
:ref:`machine.Pin <machine.Pin>` objects, but a port may allow other values,
39+
like integers or strings, which designate a Pin in the *machine.Pin* class.
40+
They may be omitted on ports that have predefined pins for *id*-specified hardware block.
41+
42+
- *filter_ns* specifies a minimum period of time in nanoseconds that the source signal needs to
43+
be stable for a pulse to be counted. Implementations should use the longest filter supported
44+
by the hardware that is less than or equal to this value. The default is 0 – no filter.
45+
46+
Methods
47+
-------
48+
49+
.. method:: Encoder.init(*, phase_a, ...)
50+
51+
Modify the settings of the Encoder object. See the **Constructor** for details about the parameters.
52+
53+
.. method:: Encoder.deinit()
54+
55+
Stops the Encoder, disables interrupts and releases hardware resources used by the encoder.
56+
A Soft Reset involve deinitializing all Encoder objects.
57+
58+
.. method:: Encoder.value([value])
59+
60+
Get, and optionally set, the counter value as a signed integer. 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
@@ -262,6 +262,8 @@ Classes
262262
machine.I2S.rst
263263
machine.RTC.rst
264264
machine.Timer.rst
265+
machine.Counter.rst
266+
machine.Encoder.rst
265267
machine.WDT.rst
266268
machine.SD.rst
267269
machine.SDCard.rst

0 commit comments

Comments
 (0)
0