Skip to content

Commit 655dc9f

Browse files
robert-hhdpgeorge
robert-hh
authored and
dpgeorge
committed
docs: Add documentation for the mimxrt Encoder/Counter class.
This adds MIMXRT-specific arguments and methods, as a superset of the original Encoder/Counter documentation. The mimxrt pinout and quickref docs are updated with relevant information. Signed-off-by: robert-hh <robert@hammelrath.com>
1 parent b1aba22 commit 655dc9f

4 files changed

Lines changed: 290 additions & 11 deletions

File tree

‎docs/library/machine.Counter.rst‎

Lines changed: 90 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@ class Counter -- pulse counter
77
Counter implements pulse counting by monitoring an input signal and counting
88
rising or falling edges.
99

10-
Minimal example usage::
10+
Minimal ESP32 example usage::
1111

1212
from machine import Pin, Counter
1313

1414
counter = Counter(0, Pin(0, Pin.IN)) # create Counter for pin 0 and begin counting
1515
value = counter.value() # retrieve current pulse count
1616

17-
Availability: **ESP32**
17+
Availability: **ESP32, MIMXRT**
1818

1919
Constructors
2020
------------
@@ -47,12 +47,49 @@ Methods
4747
or ``Counter.FALLING``. *(Supported on ESP32)*
4848

4949
- *direction* specifies the direction to count. Either ``Counter.UP`` (the
50-
default) or ``Counter.DOWN``. *(Supported on ESP32)*
50+
default) or ``Counter.DOWN``. *(Supported on ESP32 and MIMXRT)*
51+
A :ref:`machine.Pin <machine.Pin>` object as parameter argument specifies a
52+
pin which controls the counting direction. Low: Count up, High: Count down.
53+
*(Supported on MIMXRT)*
5154

5255
- *filter_ns* specifies a minimum period of time in nanoseconds that the
5356
source signal needs to be stable for a pulse to be counted. Implementations
5457
should use the longest filter supported by the hardware that is less than
55-
or equal to this value. The default is 0 (no filter). *(Supported on ESP32)*
58+
or equal to this value. The default is 0 (no filter). *(Supported on ESP32 and MIMXRT)*
59+
60+
- *max* Specify the upper counting range. The position counter will count up
61+
from a *min* start value up to *max*, then roll over to the init value and
62+
increase the cycles counter by one. When counting down, the cycles counter
63+
decreases at the transition from *min* to *max*. The range is reset by defining
64+
both *max* and *min* to 0. The default value is the hardware's counter range.
65+
*(Supported by MIMXRT and the ESP32 PCNT module)*
66+
67+
- *min* Specify the lower counting range. The default value is 0.
68+
*(Supported by MIMXRT and the ESP32 PCNT module)*
69+
70+
- *index* A Pin specifier telling to which pin the index pulse is connected.
71+
At a rising slope of the index pulse the pulse counter is reset to the min value and
72+
the cycles counter is increased or decreased by one, depending on the counting direction.
73+
A *value* of *None* disables the index
74+
input. *(Supported on MIMXRT)*
75+
76+
- *reset* A Pin specifier telling to which pin the reset pulse is connected.
77+
At a rising slope of the reset pulse the counter is set to the init
78+
value, but the cycles counter is not changed. A *value* of *None* disables the reset input.
79+
*(Supported on MIMXRT)*
80+
81+
- *match* Set the counter value at which the interrupt IRQ_MATCH shall trigger.
82+
The value is not checked for being in the bounds of the counter range. This option
83+
if equivalent to the *threshold* options of the ESP32 PCNT module.
84+
A *value* of *None* resets the match value and disables the IRQ_MATCH interrupt.
85+
*(Supported on MIMXRT)*
86+
87+
- *match_pin* A Pin specifier telling to which pin the match output is connected.
88+
This output will have a high level as long as the counter matches the
89+
match value. The signal is generated by the encoder logic and requires no
90+
further software support. The pulse width is defined by the input signal frequency
91+
and can be very short, like 20ns, or stay, if the counter stops at the match value.
92+
A *value* of *None* disables the match output. *(Supported on MIMXRT)*
5693

5794
.. method:: Counter.deinit()
5895

@@ -79,15 +116,63 @@ Methods
79116
the counter (i.e. to measure the counts since the last call), and this will
80117
avoid this problem.
81118

119+
.. method:: Counter.cycles([value])
120+
121+
Get or set the current cycles counter of the counter as signed 16 bit integer.
122+
The value represents the overflow or underflow events of the count range.
123+
With no arguments the actual cycles counter value is returned.
124+
With a single *value* argument the cycles counter is set to that value. The
125+
base counter is not changed. The method returns the previous value.
126+
*(Supported on MIMXRT)*
127+
128+
.. method:: Counter.irq(handler=None, trigger=0, hard=False)
129+
130+
Specifies, that the *handler* is called when the respective *event* happens.
131+
132+
*event* may be:
133+
- Counter.IRQ_RESET Triggered with a transition at the *reset* input.
134+
- Counter.IRQ_INDEX Triggered with a transition at the *index* input.
135+
- Counter.IRQ_MATCH Triggered when the positions counter matches the match value. For fast signals,
136+
the actual position counter value when retrieved in the callback may be different from the trigger value.
137+
- Counter.IRQ_ROLL_OVER Triggered when the position counter rolls over from the highest
138+
to the lowest value.
139+
- Counter.IRQ_ROLL_UNDER Triggered when the position counter rolls under from the lowest
140+
to the highest value.
141+
142+
The callback function *handler* receives a single argument, which is the Counter object. All
143+
events share the same callback. The event which triggers the callback can be identified
144+
with the irq.flags() method. The argument *hard* specifies, whether the callback is called
145+
as a hard interrupt or as regular scheduled function. Hard interrupts have always a short latency,
146+
but are limited in that they must not allocate memory. Regular scheduled functions are not limited
147+
in what can be used, but depending on the load of the device execution may be delayed.
148+
Under low load, the difference in latency is minor.
149+
150+
The default arguments values are handler=None, trigger=0, hard=False. The callback will be
151+
disabled, when called with handler=None.
152+
153+
The position match event is triggered as long as the position and match value are identical.
154+
Therefore the position match callback is run in a one-shot fashion, and has to be enabled
155+
again when the position has changed. It will be enabled by re-defining the trigger with either
156+
:meth:`Counter.irq()` or :meth:`irq().trigger()`. For ESP32, Counter interrupts are handled
157+
by the :ref:`PCNT<esp32.PCNT>`. *(Supported on MIMXRT)*
158+
82159
Constants
83160
---------
84161

85162
.. data:: Counter.RISING
86163
Counter.FALLING
87164

88-
Select the pulse edge.
165+
Select the pulse edge. *(Supported on ESP32)*
89166

90167
.. data:: Counter.UP
91168
Counter.DOWN
92169

93170
Select the counting direction.
171+
172+
.. data:: Counter.IRQ_RESET
173+
Counter.IRQ_INDEX
174+
Counter.IRQ_MATCH
175+
Counter.IRQ_ROLL_OVER
176+
Counter.IRQ_ROLL_UNDER
177+
178+
Select the IRQ trigger event. *(Supported on MIMXRT)*

‎docs/library/machine.Encoder.rst‎

Lines changed: 93 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@ Encoder implements decoding of quadrature signals as commonly output from
88
rotary encoders, by counting either up or down depending on the order of two
99
input pulses.
1010

11-
Minimal example usage::
11+
Minimal ESP32 example usage::
1212

1313
from machine import Pin, Encoder
1414

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
15+
encoder = Encoder(0, Pin(0, Pin.IN), Pin(1, Pin.IN)) # create Encoder for pins 0, 1 and begin counting
16+
value = encoder.value() # retrieve current count
1717

18-
Availability: **ESP32**
18+
Availability: **ESP32, MIMXRT**
1919

2020
Constructors
2121
------------
@@ -52,12 +52,46 @@ Methods
5252
- *filter_ns* specifies a minimum period of time in nanoseconds that the
5353
source signal needs to be stable for a pulse to be counted. Implementations
5454
should use the longest filter supported by the hardware that is less than
55-
or equal to this value. The default is 0 (no filter). *(Supported on ESP32)*
55+
or equal to this value. The default is 0 (no filter). *(Supported on ESP32 and MIMXRT)*
5656

5757
- *phases* specifies the number of signal edges to count and thus the
5858
granularity of the decoding. e.g. 4 phases corresponds to "4x quadrature
5959
decoding", and will result in four counts per pulse. Ports may support
60-
either 1, 2, or 4 phases and the default is 1 phase. *(Supported on ESP32)*
60+
either 1, 2, or 4 phases and the default is 1 phase. *(Supported on ESP32 and MIMXRT)*
61+
62+
- *max* Specify the upper counting range. The position counter will count up
63+
from a *min* start value up to *max*, then roll over to the init value and
64+
increase the cycles counter by one. When counting down, the cycles counter
65+
decreases at the transition from *min* to *max*. The range is reset by defining
66+
both *max* and *min* to 0. The default value is the hardware's counter range.
67+
*(Supported by MIMXRT and the ESP32 PCNT module)*
68+
69+
- *min*. Specify the lower counting range. The default value is 0.
70+
*(Supported by MIMXRT and the ESP32 PCNT module)*
71+
72+
- *index* A Pin specifier telling to which pin the index pulse is connected.
73+
At a rising slope of the index pulse the encoder counter is set to the min value
74+
and the cycles counter is increased or decreased by one, depending on
75+
the input levels. A *value* of *None* disables the index input.
76+
*(Supported on MIMXRT)*
77+
78+
- *reset* A Pin specifier telling to which pin the reset pulse is connected.
79+
At a rising slope of the reset pulse the position counter is set to the init
80+
value, but the cycles counter is not changed. A *value* of *None* disables the reset input.
81+
*(Supported on MIMXRT)*
82+
83+
- *match* Set the counter value at which the interrupt IRQ_MATCH shall trigger.
84+
The value is not checked for being in the bounds of the counter range. This option
85+
if equivalent to the *threshold* options of the ESP32 PCNT module.
86+
A *value* of *None* resets the match value and disables the IRQ_MATCH interrupt.
87+
*(Supported on MIMXRT)*
88+
89+
- *match_pin* A Pin specifier telling to which pin the match output is connected.
90+
This output will have a high level as long as the position counter matches the
91+
match value. The signal is generated by the encoder logic and requires no
92+
further software support. The pulse width is defined by the input signal frequency
93+
and can be very short, like 20ns, or stay, if the counter stops at the match position.
94+
A *value* of *None* disables the match output. *(Supported on MIMXRT)*
6195

6296
.. method:: Encoder.deinit()
6397

@@ -70,3 +104,56 @@ Methods
70104
Implementations should aim to do the get and set atomically.
71105

72106
See :meth:`machine.Counter.value` for details about overflow of this value.
107+
108+
.. method:: Encoder.cycles([value])
109+
110+
Get or set the current cycles counter of the counter as signed 16 bit integer.
111+
The value represents the overflow or underflow events of the count range.
112+
With no arguments the actual cycles counter value is returned.
113+
With a single *value* argument the cycles counter is set to that value. The
114+
base counter is not changed. The method returns the previous value.
115+
*(Supported on MIMXRT)*
116+
117+
.. method:: Encoder.irq(handler=None, trigger=0, hard=False)
118+
119+
Specifies, that the *handler* is called when the respective *event* happens.
120+
121+
*event* may be:
122+
- Encoder.IRQ_RESET Triggered with a transition at the *reset* input.
123+
- Encoder.IRQ_INDEX Triggered with a transition at the *index* input.
124+
- Encoder.IRQ_MATCH Triggered when the position counter matches the *match* value. For fast signals,
125+
the actual position counter value when retrieved in the callback may be different from the trigger value.
126+
- Encoder.IRQ_ROLL_OVER Triggered when the position counter rolls over from the highest
127+
to the lowest value.
128+
- Encoder.IRQ_ROLL_UNDER Triggered when the position counter rolls under from the lowest
129+
to the highest value.
130+
131+
The callback function *handler* receives a single argument, which is the Encoder object. All
132+
events share the same callback. The event which triggers the callback can be identified
133+
with the irq.flags() method. The argument *hard* specifies, whether the callback is called
134+
as a hard interrupt or as regular scheduled function. Hard interrupts have always a short latency,
135+
but are limited in that they must not allocate memory. Regular scheduled functions are not limited
136+
in what can be used, but depending on the load of the device execution may be delayed.
137+
Under low load, the difference in latency is minor.
138+
139+
The default arguments values are trigger=0, handler=None, hard=False. The callback will be
140+
disabled, when called with handler=None.
141+
142+
The position match event is triggered as long as the position and match value are identical.
143+
Therefore the position match callback is run in a one-shot fashion, and has to be enabled
144+
again when the position has changed. It will be enabled by re-defining the trigger with either
145+
:meth:`Encoder.irq()` or :meth:`irq().trigger()`. For ESP32, Encoder interrupts are handled
146+
by the :ref:`PCNT unit <esp32.PCNT>`.
147+
148+
*(Supported on MIMXRT)*
149+
150+
Constants
151+
---------
152+
153+
.. data:: Encoder.IRQ_RESET
154+
Encoder.IRQ_INDEX
155+
Encoder.IRQ_MATCH
156+
Encoder.IRQ_ROLL_OVER
157+
Encoder.IRQ_ROLL_UNDER
158+
159+
Select the IRQ trigger event. *(Supported on MIMXRT)*

‎docs/mimxrt/pinout.rst‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -419,3 +419,61 @@ Makerdiary RT1011 1 D8 SD1 D7 D4 D1 D2 D3
419419

420420
Symbolic pin names are provided for the MIMXRT_10xx_DEV boards.
421421
These are provided for the other boards as well.
422+
423+
.. _mimxrt_encoder_counter_pinout:
424+
425+
|
426+
|
427+
428+
Pin Assignment
429+
--------------
430+
431+
Pins are specified in the same way as for the Pin class. The pins available for an
432+
assignment to the Encoder or Counter are:
433+
434+
**IMXRT1010_EVK**, **iMX RT1011 Nano Kit**, **Olimex RT1010Py**:
435+
436+
Not supported.
437+
438+
**IMXRT1015_EVK**:
439+
440+
J30, pins 1 and 3, with the pin names "ENC1" and "ENC2".
441+
442+
**IMXRT1020_EVK**:
443+
444+
Pins D0 and D1.
445+
446+
**IMXRT1050_EVK**, **IMXRT1050_EVKB**, **IMXRT1060_EVK**, **IMXRT1064_EBK**:
447+
448+
Pins D2, D4, D5, D8, D9, D10, D11, D12, D13, D14, D15, A4, A5.
449+
Depending on the board configuration, not all pins may be wired.
450+
Pins D2, D4 and D5 cannot be used for the match output.
451+
452+
**IMXRT1170_EVK**:
453+
454+
Pins D0, D1, D2.
455+
456+
D2 is connected to the 1G PHY chip as well. So levels may be distorted.
457+
458+
**Teensy 4.0**:
459+
460+
Pins D0, D1, D2, D3, D4, D5, D7, D8, D26, D27, D30, D31, D32, D33.
461+
Pin D0 and D5 share the same signal and cannot be used independently.
462+
Pins D26, D27, D30 and D31 cannot be used for the match output.
463+
464+
**Teensy 4.1**:
465+
466+
Pins D0, D1, D2, D3, D4, D5, D7, D8, D26, D27, D30, D31, D32, D33,
467+
D37, D42, D43, D44, D45, D46 and D47.
468+
Pins D26, D27, D30 and D31 cannot be used for the match output.
469+
Some pins are assigned to the same signal and cannot be used independently. These are:
470+
471+
- Pins D0, D5 and D37,
472+
- Pins D2 and D43,
473+
- Pins D3 and D42, and
474+
- Pins D4 and D47.
475+
476+
**Seeed ARCH MIX**
477+
478+
Pins J3_14, J3_15, J4_19, J4_20, J5_15, J5_16, J5_17, J5_22, J5_23, J5_24, J5_25 and J5_26.
479+
Pins J3_14 and J3_15 cannot be used for the match output.

‎docs/mimxrt/quickref.rst‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -556,6 +556,55 @@ port and LAN(1) for the 1G port.
556556

557557
For details of the network interface refer to the class :ref:`network.LAN <network.LAN>`.
558558

559+
class Counter -- Signal counter for i.MXRT MCUs
560+
-----------------------------------------------
561+
562+
This class provides a Counter service using the Quadrature Encoder module
563+
564+
Example usage::
565+
566+
# Samples for Teensy
567+
568+
from machine import Pin, Counter
569+
570+
counter = Counter(0, Pin("D0")) # create Counter object
571+
counter.value() # get current counter value
572+
counter.value(0) # set the counter to 0
573+
counter.init(max=128) # set the upper counting range
574+
counter.deinit() # turn off the Counter
575+
counter.init(match=1000) # create a match event at count 1000
576+
counter.irq(handler, Counter.IRQ_MATCH) # call the function handler at a counter match
577+
counter # show the Counter object properties
578+
579+
The Counter is hardware based. It is available at all MIMXRT devices except the ones
580+
based on the i.MX RT 1010 MCU. For details about using the Counter with a MIMXRT board
581+
see :ref:`machine.Counter <machine.Counter>`:
582+
583+
class Encoder -- Quadrature Encoder for i.MXRT MCUs
584+
---------------------------------------------------
585+
586+
This class provides the Quadrature Encoder Service.
587+
588+
Example usage::
589+
590+
# Samples for Teensy
591+
592+
from machine import Pin, Encoder
593+
594+
qe = Encoder(0, Pin("D0"), Pin("D1")) # create Quadrature Encoder object
595+
qe.value() # get current counter values
596+
qe.value(0) # set the counter value to 0
597+
qe.init(max=128) # specify 128 counts as upper range
598+
qe.init(index=Pin("D3")) # specify Pin 3 as Index pulse input
599+
qe.deinit() # turn off the Quadrature Encoder
600+
qe.init(match=64) # set a match event at count 64
601+
qe.irq(handler, qe.IRQ_MATCH) # call the function handler at a match event
602+
qe # show the Encoder object properties
603+
604+
The Quadrature Encoder is hardware based. It is available at all MIMXRT devices except the ones
605+
based on the i.MX RT 1010 MCU. For details about using the Encoder with a MIMXRT board
606+
see :ref:`machine.Encoder <machine.Encoder>`:
607+
559608
Transferring files
560609
------------------
561610

0 commit comments

Comments
 (0)