hid-feature

hid-feature is a commandline tool to show and change Feature Reports on a HID device.

This is a Rust reimplementation of hid-feature from hid-tools

This tool needs read and write access to the /dev/hidraw node, typically this means running it as root.

Usage

Find the device's hidraw node with list-devices:

$ hid-feature list-devices
Available HID devices:
/dev/hidraw5  - Logitech USB Receiver
/dev/hidraw0  - Yubico YubiKey OTP+FIDO+CCID
/dev/hidraw1  - Yubico YubiKey OTP+FIDO+CCID
/dev/hidraw2  - Microsoft Microsoft Optical Mouse with Tilt Wheel

Then look at the device's HID Features and their current values:

$ hid-feature list /dev/hidraw2
Report ┃                      Usage                       ┃ Bits ┃ Bit Range ┃ Value Range ┃ Count ┃ Value ┃ Bytes
━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━
  23   │ Vendor Defined Page 0xFF00 / Vendor Usage 0xff06 │  2   │   8..=9   │    0..=1    │   1   │     1 │ 01
  23   │ Vendor Defined Page 0xFF00 / Vendor Usage 0xff04 │  1   │  12..=12  │    0..=1    │   1   │     0 │ 01
  24   │ Vendor Defined Page 0xFF00 / Vendor Usage 0xff08 │  1   │   8..=8   │    0..=1    │   1   │    -1 │ 01
  18   │ Generic Desktop / Resolution Multiplier          │  2   │   8..=9   │    0..=1    │   1   │     1 │ 01

In this example we can see that Feature Report 18 has a 2-bit value at bits 8 and 9 that is the Resolution Multiplier (used for high-resolution wheel scrolling). It is set to the Logical value 1.

Let's set it to 0 to get clunky scrolling on this device!

To set a given byte in a feature report, set the hexadecimal value or use xx to leave the setting as-is.

$ hid-feature set /dev/hidraw2 --report-id=18 xx 00

In this example, the second byte of the report with ID 18 is set to the value 0x01, all other values are left as-is.

Note that where a byte comprises of multiple different usages, it is the caller's responsibility to compose the byte to the correct value. For example in the Feature Report 23 we can see two vendor-defined usages at bits 8+9 and bit 12, respectively.

# Set bits 8/9 and bit 12 to 1
$ hid-feature set /dev/hidraw2 --report-id=23 xx 11
# Set only bits 8/9 but not bit 12 
$ hid-feature set /dev/hidraw2 --report-id=23 xx 01
# Set only bit 12 but not bits 8/9
$ hid-feature set /dev/hidraw2 --report-id=23 xx 10

To make this easier, the value of the byte(s) the field occupies is printed as hexadecimal value in the list output under the Bytes heading (01)

For example:

  24   │ Vendor Defined Page 0xFF00 / Vendor Usage 0xff08 │  16  │   8..=23   │    0..=65535    │   1   │  43828 │ ab 34