From fe9d0e375f5e1dbb7aff620118035a7c8fe2814b Mon Sep 17 00:00:00 2001 From: IhorNehrutsa Date: Fri, 10 Dec 2021 01:00:26 +0200 Subject: [PATCH] docs\machine: Add Counter and Encoder classes. --- docs/library/machine.Counter.rst | 68 ++++++++++++++++++++++++++++++++ docs/library/machine.Encoder.rst | 60 ++++++++++++++++++++++++++++ docs/library/machine.rst | 2 + 3 files changed, 130 insertions(+) create mode 100644 docs/library/machine.Counter.rst create mode 100644 docs/library/machine.Encoder.rst diff --git a/docs/library/machine.Counter.rst b/docs/library/machine.Counter.rst new file mode 100644 index 0000000000..8cefc2bcea --- /dev/null +++ b/docs/library/machine.Counter.rst @@ -0,0 +1,68 @@ +.. currentmodule:: machine +.. _machine.Counter: + +class Counter-- Pulse Counter +============================= + +This class provides access to hardware-supported pulse counting. + +It is currently provided for ports: + + * :ref:`ESP32 ` + * :ref:`MIMXRT ` + +Minimal example usage:: + + from machine import Pin, Counter + + counter = Counter(0, src=Pin(0, mode=Pin.IN)) # create Counter object and start to count input pulses + counter.init(filter_ns=1000) # switch source filtering on + value = counter.value(0) # get current Counter value, set counter to 0 + counter.deinit() # turn off the Counter + + print(counter) # show the Counter object properties + +Constructor +----------- + +.. class:: Counter(id, src=None, \*, direction=Counter.UP, filter_ns=0) + + - *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. + + - *src*. The Counter pulses input pin, which is usually a + :ref:`machine.Pin ` object, but a port may allow other values, + like integers or strings, which designate a Pin in the *machine.Pin* class. + It may be omitted on ports that have a predefined pin for *id*-specified hardware block. + + - *direction* specifies the direction to count. Values for this include the constants + ``Counter.UP`` (default value) and ``Counter.DOWN``. Ports may support additional values or + objects, such as a :ref:`machine.Pin ` object to control the direction externally. + + - *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. + +Methods +------- + +.. method:: Counter.init(*, src, ...) + + Modify the settings of the Counter object. See the **Constructor** for details about the parameters. + +.. method:: Counter.deinit() + + Stops the Counter, disables interrupts and releases hardware resources used by the counter. + A Soft Reset involve deinitializing all Encoder 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.UP + Counter.DOWN + + Select the counter direction. diff --git a/docs/library/machine.Encoder.rst b/docs/library/machine.Encoder.rst new file mode 100644 index 0000000000..a46f5669ff --- /dev/null +++ b/docs/library/machine.Encoder.rst @@ -0,0 +1,60 @@ +.. currentmodule:: machine +.. _machine.Encoder: + +class Encoder -- Quadrature Incremental Encoder +=============================================== + +This class provides a hardware-supported Quadrature Incremental Encoder service. + +If your port does not support hardware encoder use `Quadrature incremental encoder based on machine.Pin interrupts `_. +See also Pin-interrupt-based encoders (and problems) from Peter Hinch `Incremental encoders `_. +There is also `Dave Hylands an STM specific hardware-Timer-based solution `_. + +It is currently provided for ports: + + * :ref:`ESP32 ` + * :ref:`MIMXRT ` + +Minimal example usage:: + + from machine import Pin, Encoder + + enc = Encoder(id, phase_a=Pin(0), phase_b=Pin(1)) # create Quadrature Encoder object and start to encode input pulses + enc.init(filter_ns=1000) # switch source filtering on + value = enc.value(0) # get current Encoder value, set Encoder to 0 + enc.deinit() # turn off the Encoder + + print(enc) # show the Encoder object properties + +Constructor +----------- + +.. class:: Encoder(id, phase_a=None, phase_b=None, \*, filter_ns=0) + + - *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. + + - *phase_a* and *phase_b* are the Quadrature encoder inputs, which are usually + :ref:`machine.Pin ` objects, but a port may allow other values, + like integers or strings, which designate a Pin in the *machine.Pin* class. + They may be omitted on ports that have predefined pins for *id*-specified hardware block. + + - *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. + +Methods +------- + +.. method:: Encoder.init(*, phase_a, ...) + + Modify the settings of the Encoder object. See the **Constructor** for details about the parameters. + +.. method:: Encoder.deinit() + + Stops the Encoder, disables interrupts and releases hardware resources used by the encoder. + A Soft Reset involve deinitializing all Encoder objects. + +.. method:: Encoder.value([value]) + + Get, and optionally set, the counter 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 index 3f5cd6f13c..877def9784 100644 --- 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