Counter (pin pulse/edge counting)

The ESP32 provides up to 8 pulse counter peripherals depending on the hardware,

with id 0..7. These can be configured to count rising and/or falling edges on

any input pin.

Use the :ref:`machine.Counter <machine.Counter>` class::

ESP32 specific Counter reference:

.. class:: Counter(id, *, pin, rising, falling, ...)

The constructor and ``init`` method support an additional set of

keyword arguments over-and-above the basic

:ref:`machine.Counter <machine.Counter>` API:

- ``mode_pin``: ESP32 pulse counters support monitoring a second pin and

altering the behaviour of the counter based on its level - set this

keyword to any input Pin

- ``mode_low``: set to either ``Counter.HOLD`` or ``Counter.REVERSE`` to

either suspend counting or reverse the direction of the counter (i.e.,

``Counter.INCREMENT`` behaves as ``Counter.DECREMENT`` and vice versa)

when ``mode_pin`` is low

- ``mode_high``: as ``mode_low`` but for the behaviour when ``mode_pin``

is high

- ``filter``: set to a value 1..1023, in ticks of the 80MHz clock, to

enable the pulse width filter

- ``minimum``: set to the minimum level of the counter value when

decrementing (-32768..0)

- ``maximum``: set to the maximum level of the counter value when

decrementing (0..32767)

- ``threshold0``: sets the counter value for the

``Counter.IRQ_THRESHOLD0`` event (see ``irq`` method)

- ``threshold1``: sets the counter value for the

``Counter.IRQ_THRESHOLD1`` event (see ``irq`` method)

- ``channel``: see description below

Each pulse counter unit supports two channels, 0 and 1. By default, the

constructor and ``init()`` method configure the 0 channel. Call the

``init()`` method with ``channel=1`` to configure the other channel. Both

channels update the same counter value, but are able to monitor different

pins with different edge behaviour. The ``pin``, ``rising``, ``falling``,

``mode_pin``, ``mode_low`` and ``mode_high`` keywords are per-channel, all

other keyword arguments are per-unit and specifying them will override any

previous configuration.

The second channel can be used to configure 4X quadrature decoding with a

single counter unit::

.. method:: Counter.value([value])

Call this method with no arguments to return the current counter value or

pass the value 0 to reset the counter and return the value before reset.

ESP32 pulse counters do not support being set to any value other than 0.

Reset and return is not atomic and so it is possible for a pulse to be

missed.

.. method:: Counter.irq(target=Counter.IRQ_ZERO, handler=None)

ESP32 pulse counters support interrupts on these counter events:

- ``Counter.IRQ_ZERO``: the counter has reset to zero

- ``Counter.IRQ_MINIMUM``: the counter has hit the ``minimum`` value

- ``Counter.IRQ_MAXIMUM``: the counter has hit the ``maximum`` value

- ``Counter.IRQ_THRESHOLD0``: the counter has hit the ``threshold0`` value

- ``Counter.IRQ_THRESHOLD1``: the counter has hit the ``threshold1`` value

``target`` should be the desired events or'ed together and ``handler``

should be a callable taking a single argument, which will be the Counter

object. Only one handler can be in place per-unit. Set ``handler`` to

``None`` to disable the event interrupt (or call ``irq`` with no arguments).

.. Note::

ESP32 pulse counters reset to *zero* when reaching the minimum or maximum

value. Thus the ``IRQ_ZERO`` event will also trigger when either of these

events occurs.

.. currentmodule:: machine

.. _machine.Counter:

class Counter -- Pulse/Edge counter

The Counter class provides hardware support for counting transitions on an input

pin.

Example usage::

.. Note::

The Counter class is currently only implemented for the ESP32 port.

Constructor

.. class:: Counter(id, *, pin, rising, falling)

Create a new Counter object with number ``id``. All ports should support

at least one pulse counter with id 0, but may support a number of

independent counters. ``pin`` is the :ref:`machine.Pin <machine.Pin>`

to be monitored. For all ports, one of either the ``rising`` or

``falling`` keyword arguments may be specified with either the

``Counter.INCREMENT`` or ``Counter.DECREMENT`` constant to specify the

edge and direction to count.

Counters begin in a stopped state, with count 0, and need to be started

before they will count transitions of the pin.

Methods

.. method:: Counter.init(*, ...)

Reinitialize the Counter. See Constructor for keyword arguments.

.. method:: Counter.deinit()

Deinitialize the Counter.

.. method:: Counter.start()

Start the counter, i.e., monitor the pin for transitions.

.. method:: Counter.stop()

Stop the counter, i.e., finish monitoring the pin for transitions. The

current counter value will be retained while the counter is stopped.

.. method:: Counter.value([value])

Returns the current counter value and optionally sets the counter value

to the argument. All ports should support at least resetting the counter to

0. A read and reset operation should be as close to atomic as possible for

the hardware.

Constants

.. data:: Counter.INCREMENT

to increment the counter on an edge

.. data:: Counter.DECREMENT

to decrement the counter on an edge

machine.Counter.rst