Initial commit

2026-06-26 15:35:13 +02:00
commit b56dd2a34e
23 changed files with 2407 additions and 0 deletions
@@ -0,0 +1,82 @@
+# Troubleshooting
+
+## Check the Service
+
+```bash
+systemctl --user status surface-dial-renewed.service
+journalctl --user -u surface-dial-renewed.service -n 100 --no-pager
+```
+
+Expected startup lines:
+
+```text
+surface-dial-renewed: running in Multitouch mode
+surface-dial-renewed: dial connected
+```
+
+## Check Raw Dial Rotation
+
+Find the current event node:
+
+```bash
+rg -n -C 8 "Surface Dial System Multi Axis" /proc/bus/input/devices
+```
+
+Then run:
+
+```bash
+sudo evtest /dev/input/eventXX
+```
+
+Rotation should produce:
+
+```text
+type 2 (EV_REL), code 7 (REL_DIAL), value ...
+```
+
+If `REL_DIAL` does not appear, the driver cannot scroll. Reconnect the Dial over
+Bluetooth and check again.
+
+## Wrong Event Node
+
+The Control node is not the rotation node. It looks like:
+
+```text
+Surface Dial System Control
+```
+
+and exposes `KEY_SLEEP`/`KEY_WAKEUP`. Use `Surface Dial System Multi Axis` for
+rotation.
+
+## Haptics Work But Scroll Does Not
+
+Haptics use HID raw access; scrolling uses evdev input plus uinput output.
+Haptics working only proves the HID path works.
+
+Check:
+
+1. Raw `REL_DIAL` events with `evtest`.
+2. Service logs for `dial connected`.
+3. `/dev/uinput` permissions.
+4. Whether `Surface Dial Renewed Touchpad` appears in `/proc/bus/input/devices`.
+
+## Sensitivity OSD Warnings
+
+The service may log messages from `qdbus6` about locale fallback, for example
+`Detected locale "C"`. The OSD still works. This is caused by the systemd user
+service environment lacking a UTF-8 locale variable.
+
+If it becomes noisy, set locale environment for the user service or replace the
+shell-out OSD backend with a direct D-Bus implementation.
+
+## Reconnect Oddities
+
+After Bluetooth reconnects, event numbers can change. Always rediscover with:
+
+```bash
+rg -n -C 8 "Surface Dial" /proc/bus/input/devices
+```
+
+If button events appear but rotation does not, disconnect and reconnect the Dial
+again. The driver cannot synthesize rotation if the kernel is not emitting
+`REL_DIAL`.