Devices

Devices and verifying a device

Design principle: dofscroll complements the vendor driver instead of duplicating it, see Buttons.

Supported on Linux: models that spacenavd supports. Tested on hardware: SpaceMouse Pro and SpaceMouse Compact (RHEL 9, X11, KDE Plasma). All other models are untested. Full text: docs/devices.md. Button counts: Buttons.

Device description files

devices/*.conf describe how a raw HID report maps to axes and buttons, so more devices can be added without recompiling. The format is the same on every OS; the parser is src/hid_descriptor.cpp. Shipped files:

spacemouse-compact, spacemouse-wireless, spacemouse-pro, spacemouse-pro-wireless, spacemouse-enterprise, spacenavigator (in devices/).

Keys: name, id (vid:pid, repeatable), factory_buttons, axis.<tx|ty|tz|rx|ry|rz>, buttons. Example:

name = SpaceMouse Compact
id = 0x256f:0xc635
factory_buttons = 2
axis.tx = report=1 offset=0 type=s16le
buttons = report=3 offset=0 bits=2

The report layout in the shipped files is the commonly used 3Dconnexion layout and has not been verified on hardware. For Pro, Pro Wireless and Enterprise the raw button bits are not numbered sequentially, so their buttons line is a placeholder. On Linux the daemon gets its data from spacenavd; the Windows and macOS ports use these files.

Verifying a device with hidprobe

dofscroll-hidprobe (built by default on Linux, Windows and macOS, option -DDOFSCROLL_HIDPROBE=OFF to skip) never writes to the device. Linux reads /dev/hidraw*; the Windows installer and ZIP ship dofscroll-hidprobe.exe next to dofscroll.exe, the macOS app has it in dofscroll.app/Contents/Resources/daemon/ (run it from a terminal; the Windows and macOS backends are not tried on hardware yet). --check ends with a RESULT line and exits with 3 when the device opened but sent nothing.

dofscroll-hidprobe --list                 # devices, vid:pid, matching description
dofscroll-hidprobe --descriptor           # report descriptor as hex plus summary
dofscroll-hidprobe --dump --seconds 10    # raw reports with timestamps
dofscroll-hidprobe --check                # live decoded axes/buttons, verdict at the end
dofscroll-hidprobe --guided               # guided run; writes hidprobe-report.txt

--check compares report ids, lengths, axis ranges and button bits against the description. Move every axis to its limits and press every button; unmoved axes are warnings, not failures. --guided writes hidprobe-report.txt; the serial number is replaced by a short hash and the home directory and user name are removed. Read it, then attach it to an issue.

/dev/hidraw* is usually readable by root only: run once with sudo, or add a udev rule with TAG+="uaccess" for your vendor id (3Dconnexion uses 046d and 256f), see the full guide. If no reports arrive, try the other hidraw nodes of the same device with --device.

Verifying descriptors and button counts on real hardware is an open work item, see Roadmap.