class Counter – pulse counter

The Counter class wraps the i.MX RT QENC (quadrature encoder / counter) hardware block configured as a single-input pulse counter. Each rising edge on the source pin increments (or decrements) a hardware position counter; software callbacks can be attached to ROLL_OVER / ROLL_UNDER / RESET / INDEX / MATCH events.

Available on the OpenMV Cam RT1062 (mimxrt port) only. On the STM32-based OpenMV cams, use pyb.Timer configured for input-capture instead. Not exposed on the OpenMV Cam AE3 (alif port).

Example usage:

from machine import Pin, Counter

counter = Counter(0, Pin("P0", Pin.IN))
counter.value(0)
# ... wait some time ...
print("pulses:", counter.value())

Constructors

class machine.Counter(id: int, src: Pin | None = None, *, direction: int | Pin = UP, filter_ns: int = 0, max: int | None = None, min: int = 0, reset: Pin | None = None, match: int | None = None, match_pin: Pin | None = None)

Construct (or fetch the singleton for) the QENC counter block identified by id. RT1062 has multiple QENC blocks (id selects one); the same arguments are also accepted by init() to re-configure an existing instance.

src – the input pin whose rising edges are counted.

direction (keyword-only) – either UP / DOWN to set a fixed direction, or a Pin whose logic level selects the direction at runtime (low = count up, high = count down).

filter_ns (keyword-only) – minimum input-stable time in nanoseconds for a pulse to be counted. The driver uses the longest hardware filter that is less than or equal to this value. 0 (the default) disables filtering.

max / min (keyword-only) – modulo range of the position counter. When the counter rolls past max it wraps to min and the cycles counter increments (decrements when counting down). Passing both max and min as 0 disables the range.

reset (keyword-only) – a Pin whose rising edge reloads the position counter to the start value (without changing the cycles counter).

match (keyword-only) – counter value at which an IRQ_MATCH interrupt fires. Pass None to disable.

match_pin (keyword-only) – a Pin driven high while the position counter equals match and low otherwise.

Methods

init(src: Pin | None = None, *, direction: int | Pin = UP, filter_ns: int = 0, max: int | None = None, min: int = 0, reset: Pin | None = None, match: int | None = None, match_pin: Pin | None = None) → None

Re-initialise the counter with the given parameters and reset its position and cycles counters. Accepts the same keyword arguments as the constructor.

deinit() → None

Stop the counter, disable any pending interrupts and release the QENC hardware resources. A soft reset deinitialises all Counter instances automatically.

value() → int
value(value: int, /) → int

Get or set the signed position counter.

With no argument, return the current count.

With a single value argument, atomically set the position counter to value and return the previous count. The common idiom counter.value(0) resets the counter at the start of a measurement window.

cycles() → int
cycles(value: int, /) → int

Get or set the cycles counter, a signed 16-bit integer that tracks how many times the position counter has rolled past max / min.

With no argument, return the current cycles count.

With a single value argument, set the cycles counter to value (without touching the position counter) and return the previous count.

irq(handler: Callable[[Counter], None] | None = None, trigger: int = 0, hard: bool = False) → None

Register a callback to be invoked when one of the supported QENC events fires. The handler receives the Counter object as its only argument; the specific event can be identified inside the handler via irq.flags().

trigger is a bitmask of one or more IRQ_* constants:

  • IRQ_RESET – the reset pin asserted.

  • IRQ_INDEX – a transition on the index line.

  • IRQ_MATCH – the position counter reached match. Match is auto-disabled after firing and must be re-armed by re-installing the IRQ.

  • IRQ_ROLL_OVER – the position counter wrapped from max to min.

  • IRQ_ROLL_UNDER – the position counter wrapped from min to max.

hard=True registers a hard interrupt handler (lower latency, but the handler must not allocate). The default is a scheduled callback. Pass handler=None to disable the interrupt.

Constants

UP: int

Pass to direction to count rising edges as positive.

DOWN: int

Pass to direction to count rising edges as negative.

IRQ_RESET: int

irq() trigger flag for the reset pin event.

IRQ_INDEX: int

irq() trigger flag for the index-input event.

IRQ_MATCH: int

irq() trigger flag for the position-match event.

IRQ_ROLL_OVER: int

irq() trigger flag for a counter roll-over (max -> min).

IRQ_ROLL_UNDER: int

irq() trigger flag for a counter roll-under (min -> max).