Rotary encoder (KY-040)

The KY-040 rotary encoder module, with its own push switch: a shaft that counts clicks either way around.

CLK and DT are the two halves of a quadrature encoder, walking a four-state Gray code as the shaft turns; which way the pair walks is which way the shaft turned. The module carries its own 10 k pull-ups to CLK and DT; SW has none, which is why every sketch reads it with INPUT_PULLUP.

Pins

Pin	What it does
VCC	Supply for the pull-ups.
GND	Common return for all three contacts.
CLK	One half of the quadrature pair.
DT	The other half.
SW	Shorts to ground when the shaft is pressed. Click or hold the knob to press it; drag around the knob or use the scroll wheel to turn it.

Properties

detents: 20, 24 or 30 per revolution, for the on-screen angle. bounce: on by default.

While it runs

Three ways to turn it: drag around the knob (the pointer's bearing about the shaft is the shaft's angle), scroll the wheel over it (one notch is one detent), or drag up and down (for a touch screen, or when the drag starts near the shaft's center, where a bearing means nothing).

What the model gets right

One click of the shaft is a whole cycle of the Gray code (four quarter steps), played out on the timing wheel a few milliseconds apart rather than landing on one timestamp, because a real shaft takes tens of milliseconds to cross a detent and firmware polling in a loop only sees the sequence at all if the states are separated in time. The contacts also chatter, once per quarter step, on by default, because that is the whole lesson: a sketch that watches only for a falling edge on CLK counts three clicks for one.

What it does not model

No mechanical detent feel or click torque beyond the picture. This is the electrical behavior, not the shaft's mechanics.

The turn is played out at a fixed rate. However fast the knob is dragged, the four quarter steps of a click arrive 8 milliseconds apart, and a queue of up to 64 pending clicks drains at that rate, so a fast spin here is a steady 31 clicks a second rather than the acceleration a real shaft gives. A sketch that measures turn speed is measuring this model, not a hand.

The chatter is one extra edge per quarter step, 400 microseconds wide, every time: a fixed pattern rather than the variable burst a real contact makes, and the same on every quarter step. SW does not bounce at all, although the switch under a real KY-040 is a tactile dome and does. The 10 k pull-ups on CLK and DT are the module's own and are modeled; there is no contact resistance drift and no wear.

Common mistakes

Reading CLK on every edge instead of decoding the full quadrature state. mokxi_rotary.h in the firmware library does it the right way, with a sixteen-entry state table, precisely to dodge the chatter this part deliberately models. Turn bounce off in the properties panel when the encoder itself is not the lesson.

See it in action

Ring Simon turns this encoder into the whole game's input. Open it at /templates, and see the parts games are made of for the quadrature diagram.