kopia lustrzana https://github.com/micropython/micropython
378 wiersze
17 KiB
ReStructuredText
378 wiersze
17 KiB
ReStructuredText
.. currentmodule:: machine
|
|
.. _mimxrt_machine.Encoder:
|
|
|
|
class Encoder -- Quadrature Encoder for i.MXRT MCUs
|
|
====================================================
|
|
|
|
This class provides the Quadrature Encoder Service.
|
|
|
|
Example usage::
|
|
|
|
# Samples for Teensy
|
|
#
|
|
|
|
from machine import Pin, Encoder
|
|
|
|
qe = Encoder(0, Pin("D0"), Pin("D1")) # create Quadrature Encoder object
|
|
qe.value() # get current counter values
|
|
qe.value(0) # Set value and cycles to 0
|
|
qe.init(cpc=128) # Specify 128 counts/cycle
|
|
qe.init(index=Pin(3)) # Specify Pin 3 as Index pulse input
|
|
qe.deinit() # turn off the Quadrature Encoder
|
|
qe.irq(qe.IRQ_MATCH, value=100, handler=handler)
|
|
# Call the function handler at a match event
|
|
|
|
qe # show the Encoder object properties
|
|
|
|
Constructors
|
|
------------
|
|
|
|
.. class:: Encoder(id, phase_a, phase_b, *, home, match_pin, filter_ns, cpc, signed, index)
|
|
|
|
Construct and return a new quadrature encoder object using the following parameters:
|
|
|
|
- id: The number of the Encoder. The range is board-specific, starting with 0.
|
|
For i.MX RT1015 and i.MX RT1021 based boards, this is 0..1, for i.MX RT1052,
|
|
i.MX RT106x and i.MX RT11xx based boards it is 0..3.
|
|
- *phase_a*. *phase_a* tells to which pin the phase a of the
|
|
encoder is connected. This is usually a :ref:`machine.Pin <machine.Pin>`
|
|
object, but a port may allow other values, like integers or strings,
|
|
which designate a Pin in the machine.PIN class.
|
|
- *phase_b*. *phase_b* tells to which pin the phase b of the
|
|
encoder is connected. This is usually a :ref:`machine.Pin <machine.Pin>`
|
|
object, but a port may allow other values, like integers or strings,
|
|
which designate a Pin in the machine.PIN class.
|
|
|
|
Keyword arguments:
|
|
|
|
- *phase_a*\=value and *phase_b*\=value may be assigned by keyword arguments as well.
|
|
- *home*\=value. A Pin specifier telling to which pin the home pulse is connected.
|
|
At a rising slope of the home pulse the position counter is set to the init
|
|
value, but the cycles counter is not changed. A *value* of *None* disables the home input.
|
|
- *match_pin*\=value. A Pin specifier telling to which pin the match output is connected.
|
|
This output will have a high level as long as the position counter matches the
|
|
match value. The signal is generated by the encoder logic and requires no
|
|
further software support. The pulse width is defined by the input signal frequency
|
|
and can be very short, like 20ns, or stay, if the counter stops at the match position.
|
|
A *value* of *None* disables the match output.
|
|
- *filter_ns*\=value. Specifies a ns-value for the minimal time a signal has to be stable
|
|
at the input to be recognized. The code does the best effort to configure the filter.
|
|
The largest value is 20400 for the i.MXRT102x and 17000 for the i.MXRT105x/i.MXRT106x
|
|
(1000000000 * 2550 * 4 / CPU_CLK). A value of 0 sets the filter off.
|
|
- *cpc*\=value. Specify the number of counts per cycle. Since the
|
|
Encoder counts all four phases of the input signal, the cpc value has to be four
|
|
times the ppr value given in the encoder data sheet. The position counter will count up
|
|
from the 0 up to cpc - 1, and then reset to the init value of 0 and increase
|
|
the cycles counter by one. The default is: no cpc set. In that case the
|
|
position counter overflows at 2**32 - 1. When counting down, the cycles counter changes
|
|
at the transition from 0 to cpc - 1.
|
|
- *signed*\=False|True tells, whether the value return by Encoder.value() is signed or
|
|
unsigned. The default is ``True``.
|
|
- *index*\=value. A Pin specifier telling to which pin the index pulse is connected.
|
|
At a rising slope of the index pulse the position counter is set to the init value
|
|
and the cycles counter is increased by one. A *value* of *None* disables the index input.
|
|
|
|
The arguments phase_a, phase_b and filter_ns are generic across ports, all other arguments are port-specific.
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. method:: Encoder.init(*, phase_a, phase_b, home, match_pin, filter_ns, cpc, signed, index)
|
|
|
|
Modify settings for the Encoder object. See the above constructor for details
|
|
about the parameters.
|
|
|
|
.. method:: Encoder.deinit()
|
|
|
|
Stops the Encoder, disables interrupts and releases the resources used by the encoder. On
|
|
Soft Reset, all instances of Encoder and Counter are deinitialized.
|
|
|
|
.. method:: value=Encoder.value([value])
|
|
|
|
Get or set the current position counter of the Encoder as signed or unsigned 32 bit integer,
|
|
depending on the signed=xxx keyword option of init().
|
|
|
|
With no arguments the actual position counter value is returned.
|
|
|
|
With a single *value* argument the position counter is set to that value and the
|
|
cycles counter is cleared. The methods returns the previous value.
|
|
|
|
.. method:: cycles=Encoder.cycles([value])
|
|
|
|
Get or set the current cycles counter of the Encoder as signed 16 bit integer.
|
|
|
|
With no arguments the actual cycles counter value is returned.
|
|
|
|
With a single *value* argument the cycles counter is set to that value. The
|
|
position counter is not changed. The methods returns the previous value.
|
|
|
|
If the value returned by Encoder.value() is unsigned,
|
|
the total position can be calculated as cycles() * cpc + value().
|
|
If the total position range is still too small, you can create your own cycles
|
|
counter using the irq() callback method.
|
|
|
|
.. method:: Encoder.irq(trigger=event, value=nnn, handler=handler, hard=False)
|
|
|
|
Specifies, that the *handler* is called when the respective *event* happens.
|
|
|
|
*event* may be:
|
|
- Encoder.IRQ_MATCH Triggered when the position counter matches the match value.
|
|
- Encoder.IRQ_ROLL_OVER Triggered when the position counter rolls over from the highest
|
|
to the lowest value.
|
|
- Encoder.IRQ_ROLL_UNDER Triggered when the position counter rolls under from the lowest
|
|
to the highest value.
|
|
|
|
The callback is called, when the Encoder is at *value*. For fas signals, the actual counter
|
|
value may be different from the trigger value.
|
|
The callback function *handler* receives a single argument, which is the Encoder object. All
|
|
events share the same callback. The event which triggers the callback can be identified
|
|
with the Encoder.status() method. The argument *hard* specifies, whether the callback is called
|
|
as a hard interrupt or as regular scheduled function. Hard interrupts have always a short latency,
|
|
but are limited in that they must not allocate memory. Regular scheduled functions are not limited
|
|
in what can be used, but depending on the load of the device execution may be delayed.
|
|
Under low load, the difference in latency is minor.
|
|
|
|
The default arguments values are trigger=0, handler=None, hard=False. The callback will be
|
|
disabled, when called with handler=None.
|
|
|
|
The position match event is triggered as long as the position and match value are identical.
|
|
Therefore the position match callback is run in a one-shot fashion, and has to be enabled
|
|
again when the position has changed.
|
|
|
|
.. method:: Encoder.status()
|
|
|
|
Returns the event status flags of the recent handled Encoder interrupt as a bitmap.
|
|
The assignment of events to the bits are:
|
|
|
|
- 0: Transition at the HOME signal. (*)
|
|
- 1: Transition at the INDEX signal. (*)
|
|
- 2: Watchdog event. (*)
|
|
- 3 or Encoder.IRQ_MATCH: Position match event.
|
|
- 4: Phase_A and Phase_B changed at the same time. (*)
|
|
- 5 or Encoder.IRQ_ROLL_OVER: Roll-Over event of the counter.
|
|
- 6 or Encoder.IRQ_ROLL_UNDER: Roll-Under event of the counter.
|
|
- 7: Direction of the last count. 1 for counting up, 0 for counting down.
|
|
|
|
(*) These flags are defined, but not (yet) enabled.
|
|
|
|
.. method:: Encoder.id()
|
|
|
|
Return the id of the Encoder. That may be helpful for interrupt callback functions.
|
|
|
|
The Encoder was tested to work up to 25MHz on a Teensy. It may work at
|
|
higher frequencies as well, but that was the limit of the test set-up.
|
|
|
|
|
|
.. _mimxrt_machine.Counter:
|
|
|
|
class Counter-- Signal counter for i.MXRT MCUs
|
|
==============================================
|
|
|
|
This class provides a Counter service using the Quadrature Encoder module
|
|
|
|
Example usage::
|
|
|
|
# Samples for Teensy
|
|
#
|
|
|
|
from machine import Pin, Counter
|
|
|
|
counter = Counter(0, Pin("D0")) # create Counter object
|
|
counter.value() # get current counter value
|
|
counter.value(0) # Set the counter to 0
|
|
counter.init(cpc=128) # Specify 128 counts/cycle
|
|
counter.deinit() # turn off the Counter
|
|
counter.irq(Counter.IRQ_MATCH, handler) # Call the function handler at a counter match
|
|
|
|
counter # show the Counter object properties
|
|
|
|
Constructors
|
|
------------
|
|
|
|
.. class:: Counter(id, src, *, direction, match_pin, filter_ns, cpc, match, signed, index)
|
|
|
|
Construct and return a new Counter object using the following parameters:
|
|
|
|
- id: The number of the Counter. The range is board-specific, starting with 0.
|
|
For i.MX RT1015 and i.MX RT1021 based boards, this is 0..1, for i.MX RT1052,
|
|
i.MX RT106x and i.MX RT11xx based boards it is 0..3.
|
|
- *src*. *src* tells to which pin the counter
|
|
is connected. This is usually a :ref:`machine.Pin <machine.Pin>`
|
|
object, but a port may allow other values, like integers or strings,
|
|
which designate a Pin in the machine.PIN class.
|
|
|
|
Keyword arguments:
|
|
|
|
- *src*\=value may be assigned by a keyword argument as well.
|
|
- *direction*\=value. Specifying the direction of counting. Suitable values are:
|
|
|
|
- Counter.UP: Count up, with a roll-over to 0 at 2**48-1.
|
|
- Counter.DOWN: Count down, with a roll-under to 2**48-1 at 0.
|
|
- a :ref:`machine.Pin <machine.Pin>` object. The level at that pin controls
|
|
the counting direction. Low: Count up, High: Count down.
|
|
|
|
- *match_pin*\=value. A Pin specifier telling to which pin the match output is connected.
|
|
This output will have a high level as long as the lower 32 bit of the counter value
|
|
matches the match value. The signal is generated by the encoder logic and
|
|
requires no further software support. A *value* of *None* disables the match output.
|
|
- *filter_ns*\=value. Specifies a ns-value for the minimal time a signal has to be stable
|
|
at the input to be recognized. The code does the best effort to configure the filter.
|
|
The largest value is 20400 for the i.MXRT102x and 17000 for the i.MXRT105x/i.MXRT106x
|
|
(1000000000 * 2550 * 4 / CPU_CLK). A value of 0 sets the filter off.
|
|
- *cpc*\=value. Specify the number of counts per cycle.The counter will count up
|
|
from the 0 up to cpc - 1, and then reset to 0 and increase
|
|
the cycles counter by one. The default is: no cpc set. In that case the
|
|
counter overflows at 2**32 - 1. If the counting direction is DOWN, then the cycles
|
|
counter is decreased when counting from 0 to cpc-1.
|
|
- *signed*\=False|True tells, whether the value returned by Counter.value() is signed or
|
|
unsigned. The default is ``True``.
|
|
- *index*\=value. A Pin specifier telling to which pin the index pulse is connected.
|
|
At a rising slope of the index pulse the counter is set to 0
|
|
and the cycles counter is increased by one. A *value* of *None* disables the index input.
|
|
|
|
The arguments input, direction and filter are generic across ports, all other arguments are port-specific.
|
|
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. method:: Counter.init( *, src, direction, match_pin, filter_ns, cpc, match, signed, index)
|
|
|
|
Modify settings for the Counter object. See the above constructor for details
|
|
about the parameters.
|
|
|
|
.. method:: Counter.deinit()
|
|
|
|
Stops the Counter, disables interrupts and releases the resources used by the encoder. On
|
|
Soft Reset, all instances of Encoder and Counter are deinitialized.
|
|
|
|
.. method:: value=Counter.value([value])
|
|
|
|
Get or set the current event value of the Counter. The value is returned as a signed or
|
|
unsigned 32 bit integer, as defined with the signed=True/False option of init()
|
|
|
|
With a single *value* argument the counter is set to the lower 32 bits of that value,
|
|
and the cycles counter to the bits 32-47 of the supplied number. The methods returns the
|
|
previous value.
|
|
|
|
.. method:: cycles=Counter.cycles([value])
|
|
|
|
Get or set the current cycles counter of the counter as signed 16 bit integer.
|
|
The value represents the overflow or underflow events of the 32bit basic counter.
|
|
A total count can be calculated as cycles() * 0x100000000 + value().
|
|
If the total count range is still too small, you can create your own overflow
|
|
counter using the irq() callback method.
|
|
|
|
With no arguments the actual cycles counter value is returned.
|
|
|
|
With a single *value* argument the cycles counter is set to that value. The
|
|
base counter is not changed. The methods returns the previous value.
|
|
|
|
.. method:: Counter.irq(trigger=event, value=nnn, handler=handler, hard=False)
|
|
|
|
Specifies, that the *handler* is called when the respective *event* happens.
|
|
|
|
*event* may be:
|
|
- Counter.IRQ_COMPARE Triggered when the positions counter matches the match value.
|
|
- Counter.IRQ_ROLL_OVER Triggered when the position counter rolls over from the highest
|
|
to the lowest value.
|
|
- Counter.IRQ_ROLL_UNDER Triggered when the position counter rolls under from the lowest
|
|
to the highest value.
|
|
|
|
The callback is called, when the Counter is at *value*. For fast signals, the actual counter
|
|
value may be different from the trigger value.
|
|
The callback function *handler* receives a single argument, which is the Counter object. All
|
|
events share the same callback. The event which triggers the callback can be identified
|
|
with the Counter.status() method. The argument *hard* specifies, whether the callback is called
|
|
as a hard interrupt or as regular scheduled function. Hard interrupts have always a short latency,
|
|
but are limited in that they must not allocate memory. Regular scheduled functions are not limited
|
|
in what can be used, but depending on the load of the device execution may be delayed.
|
|
Under low load, the difference in latency is minor.
|
|
|
|
The default arguments values are trigger=0, handler=None, hard=False. The callback will be
|
|
disabled, when called with handler=None.
|
|
|
|
The counter match event is triggered as long as the lower 32 bit of the counter and match
|
|
value match. Therefore the counter match callback is run in a one-shot fashion, and has to be enabled
|
|
again when the counter value has changed.
|
|
|
|
.. method:: Counter.status()
|
|
|
|
Returns the event status flags of the recent handled Counter interrupt as a bitmap.
|
|
The assignment of events to the bits are:
|
|
|
|
- 0: Transition at the HOME signal. (*)
|
|
- 1: Transition at the INDEX signal. (*)
|
|
- 2: Watchdog event. (*)
|
|
- 3 or Counter.IRQ_MATCH: Position match event.
|
|
- 4: Phase_A and Phase_B changed at the same time. (*)
|
|
- 5 or Counter.IRQ_ROLL_OVER: Roll-Over event of the counter.
|
|
- 6 or Counter.IRQ_ROLL_UNDER: Roll-Under event of the counter.
|
|
- 7: Direction of the last count. 1 for counting up, 0 for counting down.
|
|
|
|
(*) These flags are defined, but not (yet) enabled.
|
|
|
|
.. method:: Counter.id()
|
|
|
|
Return the id of the Counter. That may be helpful for interrupt callback functions.
|
|
|
|
|
|
The counter was tested up to 50MHz. It may work at higher frequencies
|
|
as well, but that was the limit of the test set-up.
|
|
|
|
Pin Assignment
|
|
--------------
|
|
|
|
Pins are specified in the same way as for the Pin class. The pins available for an
|
|
assignment to the Encoder or Counter are:
|
|
|
|
**IMXRT1010_EVK**:
|
|
|
|
Not supported.
|
|
|
|
**IMXRT1015_EVK**:
|
|
|
|
J30, pins 1 and 3, with the pin names "ENC1" and "ENC2".
|
|
|
|
**IMXRT1020_EVK**:
|
|
|
|
Pins D0 and D1.
|
|
|
|
**IMXRT1050_EVK**, **IMXRT1050_EVKB**, **IMXRT1060_EVK**, **IMXRT1064_EBK**:
|
|
|
|
Pins D2, D4, D5, D8, D9, D10, D11, D12, D13, D14, D15, A4, A5.
|
|
Depending on the board configuration, not all pins may be wired.
|
|
Pins D2, D4 and D5 cannot be used for the match output.
|
|
|
|
**IMXRT1170_EVK**:
|
|
|
|
Pins D0, D1, D2.
|
|
|
|
D2 is connected to the 1G PHY chip as well. So levels may be distorted.
|
|
|
|
**Teensy 4.0**:
|
|
|
|
Pins D0, D1, D2, D3, D4, D5, D7, D8, D26, D27, D30, D31, D32, D33.
|
|
Pin D0 and D5 share the same signal and cannot be used independently.
|
|
Pins D26, D27, D30 and D31 cannot be used for the match output.
|
|
|
|
**Teensy 4.1**:
|
|
|
|
Pins D0, D1, D2, D3, D4, D5, D7, D8, D26, D27, D30, D31, D32, D33,
|
|
D37, D42, D43, D44, D45, D46 and D47.
|
|
Pins D26, D27, D30 and D31 cannot be used for the match output.
|
|
Some pins are assigned to the same signal and cannot be used independently. These are:
|
|
|
|
- Pins D0, D5 and D37,
|
|
- Pins D2 and D43,
|
|
- Pins D3 and D42, and
|
|
- Pins D4 and D47.
|
|
|
|
**Seeed ARCH MIX**
|
|
|
|
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.
|
|
Pins J3_14 and J3_15 cannot be used for the match output.
|
|
|
|
**Olimex RT1010Py**
|
|
|
|
Not supported. |