# Input and Output Protocol

## Physical Dial Input

The driver reads the `Surface Dial System Multi Axis` evdev device.

Find it with:

```bash
rg -n -C 8 "Surface Dial System Multi Axis" /proc/bus/input/devices
```

Then inspect raw data:

```bash
sudo evtest /dev/input/eventXX
```

Expected raw events:

```text
EV_REL / REL_DIAL: rotation
EV_KEY / BTN_0: button press and release
EV_SYN and EV_MSC: ignored framing/scancode events
```

The `Surface Dial System Control` node is not used for scrolling. It exposes
sleep/wakeup-style keys, not rotation.

## Virtual Touchpad

The multitouch output device is named:

```text
Surface Dial Renewed Touchpad
```

It exposes a type-B multitouch touchpad with slots. On gesture start it creates
two active tracking IDs. On movement it moves both slots along the Y axis and
updates the single-touch compatibility `ABS_Y` value.

Important implementation details:

- Two fingers are used because libinput interprets that as scroll.
- `INPUT_PROP_POINTER` is enabled.
- `INPUT_PROP_BUTTONPAD` is intentionally not enabled.
- `BTN_LEFT` is intentionally not exposed.
- Pressure/touch-major/tool-width axes are exposed to look more like a real
  touchpad.

The lack of buttonpad/left-button capability reduces accidental tap/click
interpretation when a scroll gesture is short.

## Gesture Lifecycle

`multitouch_start`

Creates slot 0 and slot 1 with tracking IDs, positions, pressure, touch major,
and two-finger tool state.

`multitouch_move`

Moves both slots to the same new Y position. The driver keeps an accumulated
`mt_position` relative to `MT_BASELINE`.

`multitouch_settle`

Emits one final stationary frame before ending. This reduces the chance that the
final movement is interpreted as a flick.

`multitouch_end`

Sets both tracking IDs to `-1`, releases `BTN_TOUCH` and tool keys, and reports
zero pressure.

## Coordinate Model

`MT_BASELINE` is `10_000`, with coordinates from `0` to `20_000`.

The driver recenters the synthetic gesture if `mt_position` exceeds
`MT_RECENTER_THRESHOLD`. This avoids running into coordinate limits during long
scrolls.

## Virtual Wheel

The fallback wheel device is named:

```text
Surface Dial Renewed Wheel
```

It emits both:

```text
REL_WHEEL
REL_WHEEL_HI_RES
```

Wheel mode is implemented but has not received the same tuning as multitouch
mode.