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 increasessteps, counter-clockwise decreases it. - Click and hold the center button to press
swPressedtrue; 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 bysteps % 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.

