Rotary Encoder Module (KY-040)

A Rotary Encoder (such as the KY-040) is a digital input device that measures rotation. It converts angular position or motion of a shaft into analog or digital signals.

Sensors13 blocksMicroPythonC++
Rotary Encoder Module (KY-040)

At a glance

Pins and properties exactly as the circuit editor and simulator define this part. The text below explains how to use them.

Pinout

Pinout of the Rotary Encoder Module (KY-040), drawn as in the circuit editor. Select a label to see that pin in the table below.

Pins

Pins of this part
PinLabelType
CLKCLKSignal out
DTDTSignal out
SWSWSignal out
VCC+Power in
GNDGNDGround

Properties

What you can change in the Property Inspector.

Properties of this part
PropertyRange or choicesDefault
Encoder Position (Steps)-100 to 1000
Push Switch (SW)On or offoff

A Rotary Encoder (such as the KY-040) is a digital input device that measures rotation. It converts angular position or motion of a shaft into analog or digital signals. Unlike potentiometers, rotary encoders have no rotation limits, can turn infinitely, and output incremental relative steps instead of absolute positions.


1. Hardware Specifications & Pinout

  • Steps per Revolution: Typically 20 detents (steps) per 360° turn.
  • Integrated Button: Momentary push-button switch (active-low).
  • Pin Configuration:
    • GND: Ground.
    • + / VCC: Power input (3.3V or 5V).
    • CLK (Channel A): Quadrature output clock pin.
    • DT (Channel B): Quadrature output data pin.
    • SW (Switch): Push-button switch output.

2. How it Works (Quadrature Encoding)

A rotary encoder contains a slotted disc and two contact brushes.

  • Quadrature Signals: As the shaft rotates, channels A (CLK) and B (DT) switch HIGH/LOW, generating two square waves offset by a 90° phase shift.
  • Direction Detection:
    • Clockwise (CW): The CLK pin rises first. When CLK transitions from LOW to HIGH, the DT pin is LOW.
    • Counter-Clockwise (CCW): The DT pin rises first. When CLK transitions from LOW to HIGH, the DT pin is HIGH.
  • Interrupt Counting: The microcontroller tracks transitions using external interrupts on the CLK pin. A debounce delay (50ms for knobs, 2ms for motor encoders) is applied to clean up contact bounce noise.

3. Component Properties

The KY-040 now has a real simulated component (ky040_rotary_encoder) — drag it onto the Circuit Canvas from the Components palette. It exposes:

  • Encoder Position (steps) — range -100 to 100, default 0. Each unit is one quadrature phase step, not one full detent — see Section 4's note on the exact relationship.
  • Push Switch (swPressed) — boolean toggle, default false.

All five pins are wired: VCC/GND power the module through real 10kΩ pull-up resistors on CLK/DT/SW (matching the real KY-040's on-board pull-ups per Section 1), and CLK/ DT/SW are genuinely, dynamically driven — not static — see Section 4.


4. Simulator Behavior

With the component placed and the circuit running:

  • Click-drag the knob in a circle to rotate it — a real angular drag (via atan2), not a linear slider. Every ~9° of rotation registers one quadrature phase step (steps ±1); dragging clockwise increases steps, counter-clockwise decreases it.
  • Click and hold the center button to press swPressed true; release to let go.
  • A live text readout shows Pos: <steps> | CLK:<0/1> DT:<0/1> | SW:<0/1> continuously while powered — always-visible, not a hover-only tooltip.

[!NOTE] This simulation genuinely, electrically drives CLK and DT — verified directly by tracing the real quadrature Gray-code table (QUADRATURE_STATES, indexed by steps % 4) against the real firmware's own ISR logic (Section 5's Setup block): every 4 phase steps is one full quadrature cycle — one real detent — and the only CLK-rising edge in that cycle lands with DT at exactly the value the real interrupt handler expects for that direction (LOW for a clockwise cycle, HIGH for counter-clockwise), correctly matching Section 2's own direction table. So dragging the knob a full detent's worth (~36°) genuinely produces one correctly-timed interrupt with the right polarity — unlike several other sensors in this chapter (HC-SR04, TCS3200, HW-827) whose Signal/Echo/Out pins are wired to a static voltage that never changes, this one actually toggles.


5. Supported Blockly Blocks

Drawing the blocks…

Rotary Encoder Module (KY-040) — OMS Parts