Initial commit

doc/behavior.md

@@ -0,0 +1,85 @@
+# Driver Behavior
+
+## Default Mode
+
+The default mode is multitouch scrolling. Run explicitly with:
+
+```bash
+surface-dial-renewed --mode multitouch
+```
+
+Regular wheel mode exists for fallback/testing:
+
+```bash
+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,
+moves both virtual fingers vertically, and ends the touch gesture after no
+rotation has arrived for 2 seconds.
+
+The 2 second hold is intentional. Very slow physical Dial movement can emit
+sparse `REL_DIAL` events. If the virtual fingers are lifted too quickly, libinput
+can treat those sparse movements as many tiny gestures and ignore them. Holding
+the contact makes slow and precise movement accumulate into one gesture.
+
+## 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:
+
+```text
+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:
+
+```text
+org.kde.plasmashell /org/kde/osdService org.kde.osdService.showText
+```
+
+The displayed text is:
+
+```text
+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.