chumicro-knobs 0.1.0__py3-none-any.whl

chumicro_knobs/__init__.py

@@ -0,0 +1,22 @@
+"""Rotary encoders and analog knobs, read as a position that holds still."""
+
+import gc
+
+from chumicro_knobs.analog import (
+    DEFAULT_DEADBAND,
+    DEFAULT_STEPS,
+    RAW_RANGE,
+    AnalogKnob,
+)
+from chumicro_knobs.encoder import DEFAULT_DETENT_STEPS, Encoder
+
+__all__ = [
+    "DEFAULT_DEADBAND",
+    "DEFAULT_DETENT_STEPS",
+    "DEFAULT_STEPS",
+    "RAW_RANGE",
+    "AnalogKnob",
+    "Encoder",
+]
+
+gc.collect()

chumicro_knobs/_adapters/base.py

@@ -0,0 +1,75 @@
+"""``EncoderSource`` and ``AnalogSource``: the contracts every per-runtime reader implements."""
+
+#: How much of each new conversion a smoothed reading takes, as a right shift: the reading
+#: keeps all but ``1 / 2 ** SMOOTHING_SHIFT`` of itself and takes the rest from the sample.
+#: It runs after the median below and carries the whole burden of continuous noise, because a
+#: median does nothing for that; the two reject different things and neither substitutes.
+#:
+#: A converter's noise is jumpy rather than merely wide, and it is the jumpiness that defeats
+#: the deadband above it.  That deadband anchors on whichever sample tripped it, so a reading
+#: that leaps between noise extremes drags the anchor across a step boundary and back.  This
+#: removes the leaping, which is what lets the deadband behave the way it reads.  Four is the
+#: smallest shift that holds a parked knob on one number; at two it still wanders.
+SMOOTHING_SHIFT = 4
+
+def middle_of_three(first: int, second: int, third: int) -> int:
+    """Return the middle of three readings, by comparison rather than by sorting.
+
+    Three is the smallest window with a middle, and one wild sample can never be the middle
+    of three, so a lone bad conversion is discarded outright rather than averaged in.  That
+    is the half smoothing cannot do: a wild sample averaged in walks the reading steps away
+    and takes dozens of conversions to drain back out, while a discarded one moves nothing.
+    It costs no extra conversion, because the window holds readings the loop already took.
+
+    What it does not do is quieten continuous noise, where it is nearly useless alone, so it
+    runs ahead of the smoothing rather than instead of it.
+    """
+    if first > second:
+        first, second = second, first
+    if second > third:
+        second = third
+    if first > second:
+        second = first
+    return second
+
+
+class EncoderSource:
+    """Contract for the reader that turns two quadrature pins into a detent count.
+
+    A source owns capture and quadrature decode, including the division into the clicks a
+    wrist feels.  Bounds, wrap, and the per-tick readings are decided above it.
+    """
+
+    # Plain class, not a Protocol: MicroPython has no typing module to import.
+
+    #: Detents counted since the source was built, rising one way and falling the other.
+    #: Nothing clamps or resets it, so the difference between two ticks is the turning.
+    raw_position = 0
+
+    def poll(self, now_ms: int) -> None:
+        """Take one capture step against the tick ``now_ms``, if this source needs one."""
+        raise NotImplementedError
+
+    def deinit(self) -> None:
+        """Release the pins and any interrupt this source installed."""
+        raise NotImplementedError
+
+
+class AnalogSource:
+    """Contract for the reader that turns one analog pin into a number.
+
+    A source owns the conversion and stops there.  The deadband and the quantization into
+    steps are decided above it.
+    """
+
+    #: Most recent conversion, 0 at the bottom of the sweep and 65535 at the top, whatever
+    #: the converter's native width is.
+    raw = 0
+
+    def poll(self, now_ms: int) -> None:
+        """Convert once, as of the tick ``now_ms``, and store the answer in ``raw``."""
+        raise NotImplementedError
+
+    def deinit(self) -> None:
+        """Release the pin this source claimed."""
+        raise NotImplementedError

chumicro_knobs/_adapters/cp.py

@@ -0,0 +1,62 @@
+"""CircuitPython sources: ``rotaryio`` for the shaft, ``analogio`` for the wiper."""
+
+__chumicro_runtimes__ = ("circuitpython",)  # pragma: no cover - CP runtime path
+
+import analogio  # pragma: no cover - CP runtime path
+import rotaryio  # pragma: no cover - CP runtime path
+
+from chumicro_knobs._adapters.base import SMOOTHING_SHIFT, middle_of_three
+
+
+class CpEncoderSource:  # pragma: no cover - CP runtime path
+    """Quadrature counting done by ``rotaryio.IncrementalEncoder`` in firmware.
+
+    The firmware watches the two pins from hardware rather than from the loop, so a fast
+    spin during a flash write or a socket read is still counted and a late tick reads the
+    whole turn.  ``detent_steps`` becomes the encoder's ``divisor``, which handles a turn
+    that reverses part way into a detent.
+    """
+
+    def __init__(self, pin_a, pin_b, *, detent_steps: int) -> None:
+        self._encoder = rotaryio.IncrementalEncoder(pin_a, pin_b, divisor=detent_steps)
+        self.raw_position = self._encoder.position
+
+    def poll(self, now_ms: int) -> None:
+        """Copy over the count the firmware kept while the loop was somewhere else."""
+        self.raw_position = self._encoder.position
+
+    def deinit(self) -> None:
+        """Release the two pins and the counter behind them."""
+        self._encoder.deinit()
+
+
+class CpAnalogSource:  # pragma: no cover - CP runtime path
+    """One ``analogio.AnalogIn``, sampled on the tick that asks for it.
+
+    ``AnalogIn.value`` reads 0 to 65535 on every board, scaled up by the firmware when the
+    converter underneath is narrower.
+    """
+
+    def __init__(self, pin) -> None:
+        self._converter = analogio.AnalogIn(pin)
+        reading = self._converter.value
+        # The window starts full of the first reading so the median has three from the outset.
+        self._recent = [reading, reading, reading]
+        self._slot = 0
+        # Carried scaled up by the shift so the fraction it keeps survives integer division.
+        self._smoothed = reading << SMOOTHING_SHIFT
+        self.raw = reading
+
+    def poll(self, now_ms: int) -> None:
+        """Convert once, drop it if it is a lone outlier, and smooth what is left."""
+        recent = self._recent
+        recent[self._slot] = self._converter.value
+        slot = self._slot + 1
+        self._slot = 0 if slot >= 3 else slot
+        middle = middle_of_three(recent[0], recent[1], recent[2])
+        self._smoothed += middle - (self._smoothed >> SMOOTHING_SHIFT)
+        self.raw = self._smoothed >> SMOOTHING_SHIFT
+
+    def deinit(self) -> None:
+        """Release the pin this knob claimed."""
+        self._converter.deinit()

chumicro_knobs/_adapters/mp.py

@@ -0,0 +1,125 @@
+"""MicroPython sources: a capture interrupt for the shaft, ``machine.ADC`` for the wiper."""
+
+__chumicro_runtimes__ = ("micropython",)  # pragma: no cover - MP runtime path
+
+import array  # pragma: no cover - MP runtime path
+
+import machine  # pragma: no cover - MP runtime path
+
+from chumicro_knobs._adapters.base import SMOOTHING_SHIFT, middle_of_three
+
+try:  # pragma: no cover - MP runtime path
+    from micropython import const
+except ImportError:
+    def const(value):
+        return value
+
+# Quadrature decode, indexed by (previous_state << 2) | current_state where a state is
+# (pin_a << 1) | pin_b.  Each byte holds the step plus one: 0 steps back, 1 stays put, 2 steps
+# forward.  The four entries where both pins changed at once read as no movement, because a
+# turning shaft cannot produce that and treating it as a step is how a dirty encoder invents
+# detents.  ``bytes`` keeps the table in flash, so indexing it costs nothing on the heap.
+_QUADRATURE_STEPS = (  # pragma: no cover - MP runtime path
+    b"\x01\x00\x02\x01\x02\x01\x01\x00"
+    b"\x00\x01\x01\x02\x01\x02\x00\x01"
+)
+
+# Slots the interrupt writes in the counter array: detents counted so far, quadrature steps
+# banked toward the detent in progress, and the pin state the last edge saw.
+_POSITION = const(0)  # pragma: no cover - MP runtime path
+_SUB_COUNT = const(1)  # pragma: no cover - MP runtime path
+_PREVIOUS_STATE = const(2)  # pragma: no cover - MP runtime path
+
+
+class MpEncoderSource:  # pragma: no cover - MP runtime path
+    """Quadrature counting done by a pin interrupt this class installs and owns.
+
+    MicroPython has no encoder peripheral binding, so both pins get an interrupt into one
+    handler, which is what catches a spin starting and ending between two passes of the
+    loop.  ``pin_a`` and ``pin_b`` take a pin number or a ``machine.Pin``, and
+    ``detent_steps`` is the quadrature steps that make one detent.
+    """
+
+    def __init__(self, pin_a, pin_b, *, detent_steps: int) -> None:
+        self._pin_a = machine.Pin(pin_a, machine.Pin.IN, machine.Pin.PULL_UP)
+        self._pin_b = machine.Pin(pin_b, machine.Pin.IN, machine.Pin.PULL_UP)
+        self._detent_steps = detent_steps
+
+        # Sized once here so the interrupt only ever writes into slots that already exist.
+        self._counters = array.array("l", (0, 0, 0))
+        self._counters[_PREVIOUS_STATE] = (self._pin_a.value() << 1) | self._pin_b.value()
+
+        # Bound once and kept, so no callable is built on the way into an interrupt.
+        self._edge_handler = self._on_edge
+        edges = machine.Pin.IRQ_RISING | machine.Pin.IRQ_FALLING
+        self._pin_a.irq(handler=self._edge_handler, trigger=edges)
+        self._pin_b.irq(handler=self._edge_handler, trigger=edges)
+
+        self.raw_position = 0
+
+    def _on_edge(self, pin) -> None:
+        """Fold one pin change into the detent count.  This runs in interrupt context.
+
+        It reads two pins, indexes a table that lives in flash, and writes small integers
+        into an array that already exists, so nothing here reaches the heap.  It decides
+        nothing either: bounds, wrap, and every callback happen later on the shared tick, in
+        normal context, where a slow or careless callback is harmless.  ``pin`` goes unread,
+        because both pins share this handler and both are sampled here anyway.
+        """
+        counters = self._counters
+        detent_steps = self._detent_steps
+        state = (self._pin_a.value() << 1) | self._pin_b.value()
+        step = _QUADRATURE_STEPS[(counters[_PREVIOUS_STATE] << 2) | state] - 1
+        counters[_PREVIOUS_STATE] = state
+        sub_count = counters[_SUB_COUNT] + step
+        if sub_count >= detent_steps:
+            counters[_POSITION] += 1
+            sub_count = 0
+        elif sub_count <= -detent_steps:
+            counters[_POSITION] -= 1
+            sub_count = 0
+        counters[_SUB_COUNT] = sub_count
+
+    def poll(self, now_ms: int) -> None:
+        """Copy over the count the interrupt kept while the loop was somewhere else."""
+        self.raw_position = self._counters[_POSITION]
+
+    def deinit(self) -> None:
+        """Take the interrupt off both pins so nothing counts after this."""
+        self._pin_a.irq(handler=None)
+        self._pin_b.irq(handler=None)
+
+
+class MpAnalogSource:  # pragma: no cover - MP runtime path
+    """One ``machine.ADC``, sampled on the tick that asks for it.
+
+    ``pin`` is a pin number or a ``machine.Pin``.  ``read_u16`` reports 0 to 65535 on every
+    port, stretched up from whatever the converter's native width is, so a 12-bit part
+    takes the same step arithmetic as a wider one.
+    """
+
+    def __init__(self, pin) -> None:
+        self._converter = machine.ADC(pin)
+        reading = self._converter.read_u16()
+        # The window starts full of the first reading so the median has three from the outset.
+        self._recent = [reading, reading, reading]
+        self._slot = 0
+        # Carried scaled up by the shift so the fraction it keeps survives integer division.
+        self._smoothed = reading << SMOOTHING_SHIFT
+        self.raw = reading
+
+    def poll(self, now_ms: int) -> None:
+        """Convert once, drop it if it is a lone outlier, and smooth what is left."""
+        recent = self._recent
+        recent[self._slot] = self._converter.read_u16()
+        slot = self._slot + 1
+        self._slot = 0 if slot >= 3 else slot
+        middle = middle_of_three(recent[0], recent[1], recent[2])
+        self._smoothed += middle - (self._smoothed >> SMOOTHING_SHIFT)
+        self.raw = self._smoothed >> SMOOTHING_SHIFT
+
+    def deinit(self) -> None:
+        """Do nothing, because ``machine.ADC`` claims no pin it could hand back.
+
+        The method is here so a knob is torn down the same way on either runtime.
+        """

chumicro_knobs/analog.py

@@ -0,0 +1,115 @@
+"""Analog knobs: a converter reading held still by a deadband and quantized into steps."""
+
+import sys
+
+#: Full scale of the raw reading plus one.  Dividing a 0 to 65535 conversion by this turns
+#: it into a fraction of the sweep.
+RAW_RANGE = 65536
+
+#: How many positions a full sweep of the knob reports, numbered 0 to ``steps - 1``.
+DEFAULT_STEPS = 100
+
+#: How far the raw reading must move before ``value`` follows it.  A parked wiper still
+#: wanders a few counts, more on a noisy part or a long lead; 512 clears that and stays
+#: under one step at the default 100 steps, where a step spans 655 counts.
+DEFAULT_DEADBAND = 512
+
+
+def _select_analog_source(pin):
+    """Return the converter this runtime can build for one pin."""
+    runtime_name = sys.implementation.name
+    if runtime_name == "circuitpython":  # pragma: no cover - CP runtime path
+        from chumicro_knobs._adapters.cp import CpAnalogSource
+        return CpAnalogSource(pin)
+    if runtime_name == "micropython":  # pragma: no cover - MP runtime path
+        from chumicro_knobs._adapters.mp import MpAnalogSource
+        return MpAnalogSource(pin)
+    raise RuntimeError(
+        "CPython has no converter to sample.  Build the knob with "
+        "source=FakeAnalogSource() from chumicro_knobs.testing and set a reading from "
+        "your test, or run this on CircuitPython or MicroPython.",
+    )
+
+
+class AnalogKnob:
+    """One potentiometer or slider, read as a step number that stops rattling.
+
+    Every reading is a plain attribute refreshed by ``check(now_ms)``, and ``just_moved`` is
+    true only for the tick the knob moved on.  ``deadband`` is the analog counterpart of a
+    button's debounce, and ``steps`` gives the reading a size a person can aim at, so a
+    volume control lands on 47 and stays there.  Sampling happens on the tick that asks for
+    it, because a voltage has no edge to miss between two passes of the loop.
+
+    Args:
+        pin: Analog-capable pin, named the way this runtime names pins.  Pass a pin or pass
+            ``source``.
+        source: Pre-built converter; overrides ``pin``.  Tests inject a fake here.
+        steps: How many positions the sweep reports.  ``value`` runs 0 to ``steps - 1``.
+        deadband: How far the raw 0 to 65535 reading must move before ``value`` follows.
+            Keep it under one step, ``65536 // steps`` counts, or the steps at the edges
+            become unreachable.
+    """
+
+    def __init__(
+        self,
+        pin: object | None = None,
+        *,
+        source: object | None = None,
+        steps: int = DEFAULT_STEPS,
+        deadband: int = DEFAULT_DEADBAND,
+    ) -> None:
+        if source is not None:
+            self._source = source
+        elif pin is not None:
+            self._source = _select_analog_source(pin)
+        else:
+            raise ValueError("AnalogKnob needs either pin= or source=")
+
+        self._steps = steps
+        self._deadband = deadband
+
+        #: Where the knob points, 0 at one end of the sweep and ``steps - 1`` at the other.
+        self.value = 0
+        #: The 0 to 65535 reading ``value`` was worked out from.  It moves only when the
+        #: knob clears the deadband, so it is the settled reading rather than the newest.
+        self.raw = 0
+        #: Steps this tick added to ``value``, negative the other way round.
+        self.delta = 0
+        #: True only on the tick ``value`` changed.
+        self.just_moved = False
+        #: Called with the new step number when the knob moves.
+        self.on_change = None
+
+    def check(self, now_ms: int) -> bool:
+        """Sample the pin and let ``value`` follow it when the reading cleared the deadband.
+
+        Args:
+            now_ms: Tick this pass of the loop is measured from.
+
+        Returns:
+            True when ``value`` changed, so a quiet tick can skip ``handle``.
+        """
+        source = self._source
+        source.poll(now_ms)
+        raw = source.raw
+        if abs(raw - self.raw) <= self._deadband:
+            self.delta = 0
+            self.just_moved = False
+            return False
+
+        self.raw = raw
+        value = raw * self._steps // RAW_RANGE
+        delta = value - self.value
+        self.value = value
+        self.delta = delta
+        self.just_moved = delta != 0
+        return self.just_moved
+
+    def handle(self, now_ms: int) -> None:
+        """Call ``on_change`` when this tick's movement earned it."""
+        if self.just_moved and self.on_change is not None:
+            self.on_change(self.value)
+
+    def deinit(self) -> None:
+        """Release the pin the source claimed."""
+        self._source.deinit()

chumicro_knobs/encoder.py

@@ -0,0 +1,149 @@
+"""Rotary encoders: detents counted into a position, with optional bounds and wrap."""
+
+import sys
+
+#: Quadrature steps that make one detent, the click a wrist feels as the shaft turns.
+DEFAULT_DETENT_STEPS = 4
+
+
+def _select_encoder_source(pin_a, pin_b, *, detent_steps):
+    """Return the quadrature source this runtime can build for two pins."""
+    runtime_name = sys.implementation.name
+    if runtime_name == "circuitpython":  # pragma: no cover - CP runtime path
+        from chumicro_knobs._adapters.cp import CpEncoderSource
+        return CpEncoderSource(pin_a, pin_b, detent_steps=detent_steps)
+    if runtime_name == "micropython":  # pragma: no cover - MP runtime path
+        from chumicro_knobs._adapters.mp import MpEncoderSource
+        return MpEncoderSource(pin_a, pin_b, detent_steps=detent_steps)
+    raise RuntimeError(
+        "CPython has no pins to watch a shaft with.  Build the encoder with "
+        "source=FakeEncoderSource() from chumicro_knobs.testing and turn it from "
+        "your test, or run this on CircuitPython or MicroPython.",
+    )
+
+
+class Encoder:
+    """One rotary encoder, read as a position in detents plus how far it just turned.
+
+    Every reading is a plain attribute refreshed by ``check(now_ms)``, and ``just_moved``
+    is true only for the tick the turning landed on.  ``position`` counts detents from
+    zero rather than reporting an angle, because an encoder knows how far its shaft moved
+    and never where it points.  The push switch under the shaft is a separate part on its
+    own pin.
+
+    Args:
+        pin_a: First quadrature pin, named the way this runtime names pins.  Pass both
+            pins or pass ``source``.
+        pin_b: Second quadrature pin.  Swapping the two reverses which way counts up.
+        source: Pre-built quadrature source; overrides the pins.  Tests inject a fake here.
+        detent_steps: Quadrature steps that make one detent.  Four suits a panel-mount
+            encoder with a click at every cycle; use 1 for a smooth one with no clicks.
+        bounds: ``(low, high)`` inclusive range ``position`` is held inside, or None to let
+            it run in both directions forever.
+        wrap: True to carry ``position`` around the ends of ``bounds`` instead of stopping
+            there, which is what a hue selector or a menu ring wants.  Needs ``bounds``.
+    """
+
+    def __init__(
+        self,
+        pin_a: object | None = None,
+        pin_b: object | None = None,
+        *,
+        source: object | None = None,
+        detent_steps: int = DEFAULT_DETENT_STEPS,
+        bounds: tuple[int, int] | None = None,
+        wrap: bool = False,
+    ) -> None:
+        if detent_steps < 1:
+            # At zero the detent guard is satisfied by a step of zero, so a shaft
+            # standing still counts up; below zero every edge counts.
+            raise ValueError("detent_steps must be 1 or more")
+        if source is not None:
+            self._source = source
+        elif pin_a is not None and pin_b is not None:
+            self._source = _select_encoder_source(
+                pin_a, pin_b, detent_steps=detent_steps,
+            )
+        else:
+            raise ValueError("Encoder needs both pin_a= and pin_b=, or source=")
+
+        if bounds is None:
+            if wrap:
+                raise ValueError("wrap=True needs bounds=(low, high) to wrap around")
+            self._bounded = False
+            self._low = 0
+            self._high = 0
+            self._span = 0
+        else:
+            self._bounded = True
+            self._low = bounds[0]
+            self._high = bounds[1]
+            self._span = self._high - self._low + 1
+        self._wrap = wrap
+
+        start_position = 0
+        if self._bounded:
+            if start_position < self._low:
+                start_position = self._low
+            elif start_position > self._high:
+                start_position = self._high
+
+        #: Detents counted so far, held inside ``bounds`` when there are any.  Assign to it
+        #: to restore a reading saved at shutdown without turning the shaft.
+        self.position = start_position
+        #: Detents this tick added to ``position``, negative the other way round.  Held
+        #: against a bound with no wrap, the turning that did not fit reports as zero.
+        self.delta = 0
+        #: True only on the tick ``position`` changed.
+        self.just_moved = False
+        #: Called with the signed detent change when the knob turns.
+        self.on_change = None
+
+        self._last_raw_position = self._source.raw_position
+
+    def check(self, now_ms: int) -> bool:
+        """Read how far the shaft turned since the last tick and fold it into ``position``.
+
+        Args:
+            now_ms: Tick this pass of the loop is measured from.
+
+        Returns:
+            True when ``position`` changed, so a quiet tick can skip ``handle``.
+        """
+        source = self._source
+        source.poll(now_ms)
+        raw_position = source.raw_position
+        moved = raw_position - self._last_raw_position
+        if moved == 0:
+            self.delta = 0
+            self.just_moved = False
+            return False
+        self._last_raw_position = raw_position
+
+        previous_position = self.position
+        position = previous_position + moved
+        if not self._bounded:
+            delta = moved
+        elif self._wrap:
+            position = self._low + (position - self._low) % self._span
+            delta = moved
+        else:
+            if position < self._low:
+                position = self._low
+            elif position > self._high:
+                position = self._high
+            delta = position - previous_position
+
+        self.position = position
+        self.delta = delta
+        self.just_moved = delta != 0
+        return self.just_moved
+
+    def handle(self, now_ms: int) -> None:
+        """Call ``on_change`` when this tick's turning earned it."""
+        if self.just_moved and self.on_change is not None:
+            self.on_change(self.delta)
+
+    def deinit(self) -> None:
+        """Release the pins and any interrupt the source installed."""
+        self._source.deinit()

chumicro_knobs/testing.py

@@ -0,0 +1,69 @@
+"""Test-support helpers: a hand-turned :class:`FakeEncoderSource` and :class:`FakeAnalogSource`."""
+
+__chumicro_test_support__ = True
+
+
+class FakeEncoderSource:
+    """Quadrature source a test turns by hand instead of by wrist.
+
+    ``turn`` moves it by whole detents, which is what the runtime sources publish once they
+    have divided the quadrature steps down.  Several turns before one tick add up.
+
+    Args:
+        raw_position: Detent count the source starts from.
+    """
+
+    def __init__(self, raw_position: int = 0) -> None:
+        self.raw_position = raw_position
+        #: How many times a knob asked this source to capture.
+        self.poll_calls = 0
+        #: Tick of the last capture, which proves the knob passes the loop's timestamp down.
+        self.last_poll_ms = 0
+        #: How many times a knob released this source.
+        self.deinit_calls = 0
+
+    def turn(self, detents: int) -> None:
+        """Move the shaft ``detents`` clicks, negative for the other direction."""
+        self.raw_position += detents
+
+    def poll(self, now_ms: int) -> None:
+        """Record that a capture step was asked for; the count is moved by the test."""
+        self.poll_calls += 1
+        self.last_poll_ms = now_ms
+
+    def deinit(self) -> None:
+        """Record that the knob released this source."""
+        self.deinit_calls += 1
+
+
+class FakeAnalogSource:
+    """Converter a test sets a reading on instead of turning a wiper.
+
+    ``set_raw`` takes the 0 to 65535 scale every runtime reports on, so small moves between
+    ticks exercise the deadband.
+
+    Args:
+        raw: Reading the source starts from.
+    """
+
+    def __init__(self, raw: int = 0) -> None:
+        self.raw = raw
+        #: How many times a knob asked this source to convert.
+        self.poll_calls = 0
+        #: Tick of the last conversion, which proves the knob passes the loop's timestamp down.
+        self.last_poll_ms = 0
+        #: How many times a knob released this source.
+        self.deinit_calls = 0
+
+    def set_raw(self, raw: int) -> None:
+        """Park the wiper at ``raw`` on the 0 to 65535 scale."""
+        self.raw = raw
+
+    def poll(self, now_ms: int) -> None:
+        """Record that a conversion was asked for; the reading is set by the test."""
+        self.poll_calls += 1
+        self.last_poll_ms = now_ms
+
+    def deinit(self) -> None:
+        """Record that the knob released this source."""
+        self.deinit_calls += 1

chumicro_knobs-0.1.0.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.5
+Name: chumicro-knobs
+Version: 0.1.0
+Summary: Rotary encoders and analog knobs, read as a position that holds still
+Project-URL: Homepage, https://github.com/ChuMicro/ChuMicro
+Project-URL: Documentation, https://chumicro.com/ChuMicro/knobs/stable/
+Project-URL: Source, https://github.com/ChuMicro/ChuMicro/tree/main/libraries/knobs
+Project-URL: Issues, https://github.com/ChuMicro/ChuMicro/issues
+Project-URL: Bundle, https://github.com/ChuMicro/ChuMicro-Bundle
+Author: ChuMicro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adc,circuitpython,embedded,esp32,microcontroller,micropython,potentiometer,quadrature,rotary-encoder,rp2040
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.11
+Provides-Extra: test
+Requires-Dist: chumicro-test-harness; extra == 'test'
+Requires-Dist: chumicro-timing; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# chumicro-knobs
+
+<img src="https://raw.githubusercontent.com/ChuMicro/ChuMicro/main/support/docs/chumicro_tip.png"
+align="left" width="64" style="margin-right: 16px; margin-bottom: 8px;">
+
+**Rotary encoders and analog knobs, read as a number that holds still.**
+
+Turn a shaft and `encoder.position` counts the clicks.  Turn a potentiometer and `knob.value` lands on a step and stays there.  A fast spin arrives whole even when your loop was busy elsewhere, a parked wiper keeps reporting the same number, and the same code runs on CircuitPython, MicroPython, and your laptop.
+
+<br clear="left">
+
+> Part of the [ChuMicro](https://github.com/ChuMicro/ChuMicro) family: small, focused Python libraries for microcontrollers and laptops. [Browse all libraries.](https://github.com/ChuMicro/ChuMicro/tree/main/libraries)
+
+## Install
+
+```bash
+# CircuitPython (after `circup bundle-add ChuMicro/ChuMicro-Bundle`)
+circup install chumicro_knobs
+
+# MicroPython
+mpremote mip install github:ChuMicro/ChuMicro-Bundle/chumicro_knobs
+
+# CPython
+pip install chumicro-knobs
+```
+
+For bundle setup, pre-compiled `.mpy` bundles, the experimental channel, and details on PyPI naming, see the [ChuMicro install guide](https://chumicro.com/ChuMicro/guides/install/).
+
+## Quick example
+
+Wire the encoder's two signal pins to GPIO pins and its common pin to GND.  The internal pull-ups are switched on for you, so no extra parts are needed.
+
+```python
+import board
+from chumicro_knobs import Encoder
+from chumicro_timing import ticks_ms
+
+volume = Encoder(board.GP16, board.GP17, bounds=(0, 20))
+
+while True:
+    now = ticks_ms()
+    volume.check(now)
+
+    if volume.just_moved:                    # true only on the tick the shaft moved
+        print("volume", volume.position)     # walks 0 to 20 and stops at both ends
+```
+
+The loop never pauses, so the rest of your program keeps running between turns.  `just_moved` is true for exactly one pass, which means you can read it as many times as you like without it firing twice.
+
+## A fast spin arrives whole
+
+An encoder reports movement as pulses on two signal pins, and one brisk flick of the wrist sends dozens of them.  If your loop stalls on a socket read or a flash write, a plain pin read looks at the wrong moments and most of the turn is gone.  The counting here happens outside your loop, so a tick that arrives late still reads the whole spin.
+
+On CircuitPython that counting is `rotaryio`, running in the firmware's own C, which on RP2040 boards is a state machine in the PIO block.  On MicroPython the library installs an interrupt on both signal pins and decodes the pulses itself.  Your program sets up neither one; it reads `position` on whichever runtime it happens to be on.
+
+```python
+volume.check(now)
+if volume.just_moved:
+    print(volume.delta)      # every detent of the spin, even the ones during the stall
+```
+
+## What's included
+
+### Core
+
+| Symbol | Description |
+|---|---|
+| `Encoder(pin_a, pin_b, detent_steps=4, bounds=None, wrap=False)` | One rotary encoder on two signal pins, counted in detents |
+| `AnalogKnob(pin, steps=100, deadband=512)` | One potentiometer or slider on one analog pin, read as a step number |
+| `knob.check(now_ms)` | Take one reading; returns `True` when the number changed |
+| `knob.handle(now_ms)` | Call `on_change` when the tick earned it |
+| `knob.deinit()` | Hand the pins back, along with any interrupt the library installed |
+
+### Readings, refreshed by `check(now_ms)`
+
+| Symbol | Description |
+|---|---|
+| `encoder.position` | Detents counted so far, held inside `bounds` when there are any.  Assign to it to restore a saved value |
+| `encoder.delta` | Detents this tick added to `position`, negative the other way round |
+| `encoder.just_moved` | `True` only on the tick `position` changed |
+| `knob.value` | Where the knob points, `0` at one end of the sweep and `steps - 1` at the other |
+| `knob.delta` | Steps this tick added to `value`, negative the other way round |
+| `knob.raw` | The settled 0 to 65535 reading `value` was worked out from |
+| `knob.just_moved` | `True` only on the tick `value` changed |
+
+### Callbacks, dispatched by `handle(now_ms)`
+
+| Symbol | Description |
+|---|---|
+| `encoder.on_change` | Called with the signed detent change when the shaft turns |
+| `knob.on_change` | Called with the new step number when the knob moves |
+
+### Defaults you can import
+
+| Symbol | Description |
+|---|---|
+| `DEFAULT_DETENT_STEPS` | `4`, the pulses one click of a detented encoder produces |
+| `DEFAULT_STEPS` | `100` positions across a full sweep of an analog knob |
+| `DEFAULT_DEADBAND` | `512`, how far a reading moves before `value` follows it |
+| `RAW_RANGE` | `65536`, the raw scale every runtime reports a conversion on |
+
+### Testing
+
+| Symbol | Description |
+|---|---|
+| `chumicro_knobs.testing.FakeEncoderSource` | A shaft your test turns by hand, so encoder logic runs with no board |
+| `chumicro_knobs.testing.FakeAnalogSource` | A wiper your test parks where it likes, so the deadband is testable too |
+
+## The reading holds still
+
+A potentiometer's voltage is never exactly steady.  The low bits of a 12-bit converter wander a couple of counts under a parked wiper, which is 32 counts once the reading is scaled to the 0 to 65535 range every runtime reports on, and a noisier part on a long lead wanders several times that.  A program that prints the raw reading shows a knob somebody is fiddling with.
+
+`deadband` is how far the reading has to move before `value` follows it, and quantizing into `steps` gives the number a size a person can aim at:
+
+```python
+brightness = AnalogKnob(board.A0, steps=10)                # reports 0 to 9
+fine = AnalogKnob(board.A1, steps=256, deadband=128)       # a finer sweep, a tighter deadband
+```
+
+The default 512 sits well above the wander and well under the 655 counts one step spans at 100 steps.  Keep `deadband` under the width of one step, which is `65536 // steps` counts, so every step stays reachable including the ones at the ends of the sweep.
+
+## Where this fits
+
+Depends on nothing.  The timestamp you hand to `check()` comes from wherever your loop already gets one, and [`chumicro-timing`](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/timing)'s `ticks_ms()` is the usual source.  Used directly in user apps; nothing downstream depends on it.
+
+Pairs with [`chumicro-runner`](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/runner), which deals out turns to every service in your program:
+
+```python
+runner.add(volume)      # check() and handle() are the runner's contract
+```
+
+A rotary encoder's push switch is a button on its own pin, so an encoder with a click reads its shaft here and its switch with [`chumicro-buttons`](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/buttons).
+
+## Platform support
+
+Works on CPython, MicroPython, and CircuitPython.
+
+### RP2040 wants adjacent pins
+
+`rotaryio` on RP2040 boards reads the two signal pins with one PIO state machine, which requires them to sit next to each other in GPIO numbering.  `board.GP16` and `board.GP17` work; `board.GP16` and `board.GP20` do not.  Other CircuitPython ports and every MicroPython port take any two pins.
+
+`pin_a`, `pin_b`, and `pin` need real hardware, so on a laptop they raise and point you at the fakes below.
+
+## Testing your code
+
+The `chumicro_knobs.testing` module provides `FakeEncoderSource` and `FakeAnalogSource`, hand-driven stand-ins for the hardware, so knob logic is an ordinary unit test with no board:
+
+```python
+from chumicro_knobs import Encoder
+from chumicro_knobs.testing import FakeEncoderSource
+
+source = FakeEncoderSource()
+volume = Encoder(source=source, bounds=(0, 20))
+
+source.turn(3)
+volume.check(0)
+
+assert volume.position == 3
+```
+
+## Examples
+
+| Example | What it shows |
+|---|---|
+| [`circuitpython_encoder_volume.py`](https://github.com/ChuMicro/ChuMicro/blob/main/libraries/knobs/examples/circuitpython_encoder_volume.py) | An encoder for volume and a potentiometer for brightness on CircuitPython |
+| [`micropython_encoder_volume.py`](https://github.com/ChuMicro/ChuMicro/blob/main/libraries/knobs/examples/micropython_encoder_volume.py) | The same two knobs on MicroPython |
+
+## Contributing
+
+Issues, bug reports, and pull requests are welcome, and so is "I ran it on this board and here's what happened", some of the most useful feedback a hardware project can get.  Development happens in the [ChuMicro repository](https://github.com/ChuMicro/ChuMicro), whose contributing guide covers setup and the test workflow.
+
+## Docs
+
+📖 **[Stable docs](https://chumicro.com/ChuMicro/knobs/stable/)** · **[Experimental docs](https://chumicro.com/ChuMicro/knobs/experimental/)**
+
+## Find this library
+
+- **PyPI:** [chumicro-knobs](https://pypi.org/project/chumicro-knobs/)
+- **Bundle:** [ChuMicro-Bundle](https://github.com/ChuMicro/ChuMicro-Bundle/tree/main/chumicro_knobs) (CircuitPython & MicroPython)
+- **Experimental bundle:** [ChuMicro-Bundle-Experimental](https://github.com/ChuMicro/ChuMicro-Bundle-Experimental/tree/main/chumicro_knobs)
+- **Source:** [libraries/knobs](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/knobs)
+
+## License
+
+[MIT](https://github.com/ChuMicro/ChuMicro/blob/main/LICENSE)

chumicro_knobs-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+chumicro_knobs/__init__.py,sha256=_oxx-vJH0PCyYaeiz8gpqtOXokQDyCjwsBkYSUjhxug,416
+chumicro_knobs/analog.py,sha256=0U9bP9iPbEtVoIRSqfU4fWHd9mjDRDK0VOtQw9sZg1A,4634
+chumicro_knobs/encoder.py,sha256=3832E_eo3kNDhId7SV9_VkkjAHN5ZedXa6A5f2F2hog,6160
+chumicro_knobs/testing.py,sha256=fQrY9CDg1s50XnT9Iy9cqq11yKWcCqlIyEnmVU4DJqw,2453
+chumicro_knobs/_adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chumicro_knobs/_adapters/base.py,sha256=tYzPvfWu21n6_1xWqC_O1jesqTMXcYQCHAos9Qf2FC0,3403
+chumicro_knobs/_adapters/cp.py,sha256=tioE5qzriraCPffpiq2WCSobHVTEsro93s6Wv4eL42U,2657
+chumicro_knobs/_adapters/mp.py,sha256=2Il-pU8oACFQhw5i5ucHS6eqh8qqWgQcG2x92ADgHtY,5816
+chumicro_knobs-0.1.0.dist-info/METADATA,sha256=Ydy4K4d1GaN2QlZBV_QkmJey2bPEY8VnMQYAuj34V6U,10466
+chumicro_knobs-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+chumicro_knobs-0.1.0.dist-info/licenses/LICENSE,sha256=yV2dzHegsHSrEDhSKAICdTOEljKxiq20rQycXtRUlL4,1066
+chumicro_knobs-0.1.0.dist-info/RECORD,,

chumicro_knobs-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

chumicro_knobs-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ChuMicro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+