Skip to content

API Reference

chumicro_knobs.encoder

Encoder reads one rotary encoder: detents counted into a running position, the signed delta for each tick, and the optional bounds and wrap that keep the count inside a range you choose.

chumicro_knobs.encoder

Rotary encoders: detents counted into a position, with optional bounds and wrap.

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.

Parameters:

Name Type Description Default
pin_a object | None

First quadrature pin, named the way this runtime names pins. Pass both pins or pass source.

 None
pin_b object | None

Second quadrature pin. Swapping the two reverses which way counts up.

 None
source object | None

Pre-built quadrature source; overrides the pins. Tests inject a fake here.

 None
detent_steps int

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.

 DEFAULT_DETENT_STEPS
bounds tuple[int, int] | None

(low, high) inclusive range position is held inside, or None to let it run in both directions forever.

 None
wrap bool

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.

 False

check(now_ms)

Read how far the shaft turned since the last tick and fold it into position.

Parameters:

Name Type Description Default
now_ms int

Tick this pass of the loop is measured from.

 required

Returns:

Type Description
bool

True when position changed, so a quiet tick can skip handle.

handle(now_ms)

Call on_change when this tick's turning earned it.

deinit()

Release the pins and any interrupt the source installed.

chumicro_knobs.analog

AnalogKnob reads one potentiometer or slider: a converter held still by a deadband and quantized into steps, published as value, delta, and the settled raw reading behind them.

chumicro_knobs.analog

Analog knobs: a converter reading held still by a deadband and quantized into steps.

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.

Parameters:

Name Type Description Default
pin object | None

Analog-capable pin, named the way this runtime names pins. Pass a pin or pass source.

 None
source object | None

Pre-built converter; overrides pin. Tests inject a fake here.

 None
steps int

How many positions the sweep reports. value runs 0 to steps - 1.

 DEFAULT_STEPS
deadband int

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.

 DEFAULT_DEADBAND

check(now_ms)

Sample the pin and let value follow it when the reading cleared the deadband.

Parameters:

Name Type Description Default
now_ms int

Tick this pass of the loop is measured from.

 required

Returns:

Type Description
bool

True when value changed, so a quiet tick can skip handle.

handle(now_ms)

Call on_change when this tick's movement earned it.

deinit()

Release the pin the source claimed.

chumicro_knobs.testing

FakeEncoderSource and FakeAnalogSource stand in for the hardware so knob logic can be tested on a host. Turn the shaft or park the wiper, tick the knob, assert on what it made of them.

chumicro_knobs.testing

Test-support helpers: a hand-turned :class:FakeEncoderSource and :class:FakeAnalogSource.

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.

Parameters:

Name Type Description Default
raw_position int

Detent count the source starts from.

 0

turn(detents)

Move the shaft detents clicks, negative for the other direction.

poll(now_ms)

Record that a capture step was asked for; the count is moved by the test.

deinit()

Record that the knob released this source.

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.

Parameters:

Name Type Description Default
raw int

Reading the source starts from.

 0

set_raw(raw)

Park the wiper at raw on the 0 to 65535 scale.

poll(now_ms)

Record that a conversion was asked for; the reading is set by the test.

deinit()

Record that the knob released this source.

← Home

Source · \ PyPI · \ Bundle · \ Experimental Bundle