surface-dial-renewed/doc/behavior.md

Driver Behavior

Default Mode

The default mode is multitouch scrolling. Run explicitly with:

surface-dial-renewed --mode multitouch

Regular wheel mode exists for fallback/testing:

surface-dial-renewed --mode wheel

Normal Rotation

Normal Dial rotation emits a synthetic two-finger touchpad scroll through Surface Dial Renewed Touchpad.

The driver starts a virtual two-finger contact on the first rotation event and moves both virtual fingers vertically. Gesture release is dynamic:

• normal and fast rotation releases after about 100ms
• sparse precision movement can stretch release up to 1500ms

The 100ms minimum matches the old driver's multitouch control. The timeout is based on the time gap between rotation events, not the raw delta size. That is important because the Dial can emit delta=1 even during normal fast scrolling. If the virtual fingers are lifted too quickly during sparse movement, libinput can treat those sparse events as many tiny gestures and ignore them. If the hold is too long, page-edge overscroll animations can remain stretched for too long before bouncing back.

The driver keeps the last rotation timestamp even after a virtual touch gesture ends. This matters because sparse precision events can arrive after the 100ms gesture has already been released. The next event still sees the previous event gap and can stretch the new gesture timeout. A gap of 2500ms or more is treated as a real pause and resets back to the 100ms minimum.

Timing is configurable:

surface-dial-renewed --mt-idle-ms 100 --mt-idle-max-ms 1500 --mt-settle-ms 80

--mt-idle-ms controls the fast-scroll minimum release timeout. --mt-idle-max-ms controls the slow/precision maximum release timeout. --mt-settle-ms controls the short stationary frame before the fingers lift.

Sensitivity Selector

Hold the Dial down and rotate to change sensitivity.

• Range: 1/32 through 32/32
• Default: 7/32
• Step threshold: 48 raw Dial units per sensitivity level
• Display: KDE OSD text, falling back to notification
• Haptics: one buzz when entering the selector, one buzz per accepted level

While the button is held, rotation never scrolls. If a multitouch scroll gesture is active when the button is pressed, it is ended before sensitivity adjustment.

Sensitivity Scaling

The sensitivity level maps to milli-pixels per raw Dial unit:

500 + (level - 1) * 250

This means level 1 is 0.5 virtual coordinate units per raw Dial unit, level 7 is 2.0, and level 32 is 8.25.

The driver stores fractional remainders while a gesture is active. A nonzero raw Dial event is rounded away from zero if it would otherwise produce no integer coordinate movement.

Haptics

Haptics are deliberately limited:

• Enter sensitivity selector: buzz once.
• Change sensitivity level: buzz once.

Normal scrolling does not buzz. It was tested and removed because it was distracting and hard to align with physical rotation consistently.

OSD

On KDE, the driver calls:

org.kde.plasmashell /org/kde/osdService org.kde.osdService.showText

The displayed text is:

Surface Dial sensitivity N/32

KDE exposes polished volume/brightness OSD methods, but those are semantically volume/brightness-specific. The generic custom progress API is not callable as a normal method on this system, so the driver uses text OSD instead.