MojoScale Studio Docs
API Reference

rotary

Rotary encoder module.

All modules Open Studio
Studio Docs Sensors & I/O

import rotary

The rotary module reads common Arduino-style incremental rotary encoder boards, including KY-040 style encoders with CLK, DT, and an optional push switch. The firmware uses GPIO interrupts to track movement, while user code reads position or delta synchronously. Use ``rotary.Encoder(...)`` to create independent encoder objects without manually choosing native channels.

Quick example

import rotary
import system

volume = rotary.Encoder(clk_pin=4, dt_pin=5, sw_pin=6)
menu = rotary.Encoder(clk_pin=18, dt_pin=19)

def poll_knob():
    movement = volume.delta()
    if movement != 0:
        print("volume", volume.read(), "delta", movement)

    if volume.clicked():
        print("volume button clicked")

system.schedule("knob", 25, 25, -1, poll_knob)

import rotary

knob = rotary.Encoder(4, 5, steps_per_detent=2, invert=True)
knob.reset(position=10)
print(knob.info())

importrotary

Rotary encoder module.

The rotary module reads common Arduino-style incremental rotary encoder boards, including KY-040 style encoders with CLK, DT, and an optional push switch. The firmware uses GPIO interrupts to track movement, while user code reads position or delta synchronously. Use ``rotary.Encoder(...)`` to create independent encoder objects without manually choosing native channels.

API 18 available

rotary.Encoder(clk_pin: int, dt_pin: int, sw_pin: int = None, steps_per_detent: int = None, pullup: bool = None, active_low: bool = None, invert: bool = None, debounce_ms: int = None) -> rotary_encoder

Create an independent rotary encoder object.

Parameters
Name Type Pass as Required Description
clk_pin int positional or keyword Yes GPIO pin connected to encoder CLK or A.
dt_pin int positional or keyword Yes GPIO pin connected to encoder DT or B.
sw_pin int positional or keyword No Optional GPIO pin connected to the encoder push switch. Defaults to no switch.
steps_per_detent int positional or keyword No Optional encoder transitions per physical click. Defaults to 4 for common KY-040 style encoders.
pullup bool positional or keyword No Optional boolean. Enables internal pull-ups by default.
active_low bool positional or keyword No Optional boolean. Treats the switch as pressed when low by default.
invert bool positional or keyword No Optional boolean. Reverses clockwise/counterclockwise direction.
debounce_ms int positional or keyword No Optional switch debounce time in milliseconds. Defaults to 20.
Returns

rotary_encoder rotary_encoder object.

rotary.Encoder().read() -> int

Read this encoder's current position.

rotary.Encoder().delta(reset=True) -> int

Read movement since the previous delta read.

Parameters
Name Type Pass as Required Description
reset bool positional or keyword No Optional value. Defaults to True.

rotary.Encoder().reset(position=0) -> bool

Reset this encoder's position.

Parameters
Name Type Pass as Required Description
position int positional or keyword No Optional value. Defaults to 0.

rotary.Encoder().direction() -> int: Read last direction

1, -1, or 0.

rotary.Encoder().button() -> bool

Read the current push switch state.

rotary.Encoder().clicked(reset=True) -> bool

Read and optionally clear a debounced click.

Parameters
Name Type Pass as Required Description
reset bool positional or keyword No Optional value. Defaults to True.

rotary.Encoder().info() -> dict

Return this encoder's configuration and state.

rotary.Encoder().close() -> bool

Release this encoder's pins and native slot.

rotary.begin(clk_pin: int, dt_pin: int, sw_pin: int = None, channel: int = None, steps_per_detent: int = None, pullup: bool = None, active_low: bool = None, invert: bool = None, debounce_ms: int = None) -> bool

Initialize a rotary encoder.

Parameters
Name Type Pass as Required Description
clk_pin int positional or keyword Yes GPIO pin connected to encoder CLK or A.
dt_pin int positional or keyword Yes GPIO pin connected to encoder DT or B.
sw_pin int positional or keyword No Optional GPIO pin connected to the encoder push switch. Defaults to no switch.
channel int positional or keyword No Optional rotary channel. Defaults to 0. Supported channels are 0 through 3.
steps_per_detent int positional or keyword No Optional encoder transitions per physical click. Defaults to 4 for common KY-040 style encoders. Use 1 or 2 if your encoder reports too slowly.
pullup bool positional or keyword No Optional boolean. Enables internal pull-ups by default.
active_low bool positional or keyword No Optional boolean. Treats the switch as pressed when low by default, matching common modules wired to ground.
invert bool positional or keyword No Optional boolean. Reverses clockwise/counterclockwise direction if your wiring reports movement backward.
debounce_ms int positional or keyword No Optional switch debounce time in milliseconds. Defaults to 20.
Returns

bool True when the encoder pins and interrupts are configured.

rotary.read(channel: int = None) -> int

Read the current encoder position.

Parameters
Name Type Pass as Required Description
channel int positional or keyword No Optional rotary channel. Defaults to 0.
Returns

int Integer position count.

rotary.delta(channel: int = None, reset: bool = None) -> int

Read movement since the previous delta read.

Parameters
Name Type Pass as Required Description
channel int positional or keyword No Optional rotary channel. Defaults to 0.
reset bool positional or keyword No Optional boolean. Defaults to True, which clears the accumulated delta after reading.
Returns

int Integer movement count. Positive and negative values indicate direction.

rotary.reset(channel: int = None, position: int = None) -> bool

Reset encoder position.

Parameters
Name Type Pass as Required Description
channel int positional or keyword No Optional rotary channel. Defaults to 0.
position int positional or keyword No Optional integer position to store. Defaults to 0.
Returns

bool True when the position and accumulated delta are reset.

rotary.direction(channel: int = None) -> int

Read the last movement direction.

Parameters
Name Type Pass as Required Description
channel int positional or keyword No Optional rotary channel. Defaults to 0.
Returns

int Integer direction: 1 for positive movement, -1 for negative movement, or 0 when no direction has been recorded since reset.

rotary.button(channel: int = None) -> bool

Read the current push switch state.

Parameters
Name Type Pass as Required Description
channel int positional or keyword No Optional rotary channel. Defaults to 0.
Returns

bool True when the optional switch pin is currently pressed.

rotary.clicked(channel: int = None, reset: bool = None) -> bool

Read whether the push switch was pressed since the previous check.

Parameters
Name Type Pass as Required Description
channel int positional or keyword No Optional rotary channel. Defaults to 0.
reset bool positional or keyword No Optional boolean. Defaults to True, which clears the click flag after reading.
Returns

bool True when a debounced press has been recorded.

rotary.detach(channel: int = None) -> bool

Detach a rotary encoder channel.

Parameters
Name Type Pass as Required Description
channel int positional or keyword No Optional rotary channel. Defaults to 0.
Returns

bool True when an initialized channel was detached.

rotary.info(channel: int = None) -> dict

Return rotary encoder state.

Parameters
Name Type Pass as Required Description
channel int positional or keyword No Optional rotary channel. Defaults to 0.
Returns

dict Dict with ``initialized``, ``channel``, ``clk_pin``, ``dt_pin``, ``sw_pin``, ``position``, ``delta``, ``direction``, ``button``, ``clicks``, ``steps_per_detent``, ``pullup``, ``active_low``, ``invert``, and ``debounce_ms`` fields.