A while ago I was looking at Rust-based parsing of HID reports but, surprisingly, outside of C wrappers and the usual cratesquatting I couldn't find anything ready to use. So I figured, why not write my own, NIH style. Yay! Gave me a good excuse to learn API design for Rust and whatnot. Anyway, the result of this effort is the hidutils collection of repositories which includes commandline tools like hid-recorder and hid-replay but, more importantly, the hidreport (documentation) and hut (documentation) crates. Let's have a look at the latter two.
Both crates were intentionally written with minimal dependencies, they currently only depend on thiserror and arguably even that dependency can be removed.
HID Usage Tables (HUT)
As you know, HID Fields have a so-called "Usage" which is divided into a Usage Page (like a chapter) and a Usage ID. The HID Usage tells us what a sequence of bits in a HID Report represents, e.g. "this is the X axis" or "this is button number 5". These usages are specified in the HID Usage Tables (HUT) (currently at version 1.5 (PDF)). The hut crate is generated from the official HUT json file and contains all current HID Usages together with the various conversions you will need to get from a numeric value in a report descriptor to the named usage and vice versa. Which means you can do things like this:
let gd_x = GenericDesktop::X;
let usage_page = gd_x.usage_page();
assert!(matches!(usage_page, UsagePage::GenericDesktop));
Or the more likely need: convert from a numeric page/id tuple to a named usage.
let usage = Usage::new_from_page_and_id(0x1, 0x30); // GenericDesktop / X
println!("Usage is {}", usage.name());
90% of this crate are the various conversions from a named usage to the numeric value and vice versa. It's a huge crate in that there are lots of enum values but the actual functionality is relatively simple.
hidreport - Report Descriptor parsing
The hidreport crate is the one that can take a set of HID Report Descriptor bytes obtained from a device and parse the contents. Or extract the value of a HID Field from a HID Report, given the HID Report Descriptor. So let's assume we have a bunch of bytes that are HID report descriptor read from the device (or sysfs) we can do this:
let rdesc: ReportDescriptor = ReportDescriptor::try_from(bytes).unwrap();
I'm not going to copy/paste the code to run through this report descriptor but suffice to day it will give us access to the input, output and feature reports on the device together with every field inside those reports. Now let's read from the device and parse the data for whatever the first field is in the report (this is obviously device-specific, could be a button, a coordinate, anything):
let input_report_bytes = read_from_device();
let report = rdesc.find_input_report(&input_report_bytes).unwrap();
let field = report.fields().first().unwrap();
match field {
Field::Variable(var) => {
let val: u32 = var.extract(&input_report_bytes).unwrap().into();
println!("Field {:?} is of value {}", field, val);
},
_ => {}
}
The full documentation is of course on
docs.rs and I'd be happy to take suggestions on how to improve the API and/or add features not currently present.
hid-recorder
The hidreport and hut crates are still quite new but we have an existing test bed that we use regularly. The venerable hid-recorder tool has been rewritten twice already. Benjamin Tissoires' first version was in C, then a Python version of it became part of hid-tools and now we have the third version written in Rust. Which has a few nice features over the Python version and we're using it heavily for e.g. udev-hid-bpf debugging and development. An examle output of that is below and it shows that you can get all the information out of the device via the hidreport and hut crates.
$ sudo hid-recorder /dev/hidraw1
# Microsoft Microsoft® 2.4GHz Transceiver v9.0
# Report descriptor length: 223 bytes
# 0x05, 0x01, // Usage Page (Generic Desktop) 0
# 0x09, 0x02, // Usage (Mouse) 2
# 0xa1, 0x01, // Collection (Application) 4
# 0x05, 0x01, // Usage Page (Generic Desktop) 6
# 0x09, 0x02, // Usage (Mouse) 8
# 0xa1, 0x02, // Collection (Logical) 10
# 0x85, 0x1a, // Report ID (26) 12
# 0x09, 0x01, // Usage (Pointer) 14
# 0xa1, 0x00, // Collection (Physical) 16
# 0x05, 0x09, // Usage Page (Button) 18
# 0x19, 0x01, // UsageMinimum (1) 20
# 0x29, 0x05, // UsageMaximum (5) 22
# 0x95, 0x05, // Report Count (5) 24
# 0x75, 0x01, // Report Size (1) 26
... omitted for brevity
# 0x75, 0x01, // Report Size (1) 213
# 0xb1, 0x02, // Feature (Data,Var,Abs) 215
# 0x75, 0x03, // Report Size (3) 217
# 0xb1, 0x01, // Feature (Cnst,Arr,Abs) 219
# 0xc0, // End Collection 221
# 0xc0, // End Collection 222
R: 223 05 01 09 02 a1 01 05 01 09 02 a1 02 85 1a 09 ... omitted for previty
N: Microsoft Microsoft® 2.4GHz Transceiver v9.0
I: 3 45e 7a5
# Report descriptor:
# ------- Input Report -------
# Report ID: 26
# Report size: 80 bits
# | Bit: 8 | Usage: 0009/0001: Button / Button 1 | Logical Range: 0..=1 |
# | Bit: 9 | Usage: 0009/0002: Button / Button 2 | Logical Range: 0..=1 |
# | Bit: 10 | Usage: 0009/0003: Button / Button 3 | Logical Range: 0..=1 |
# | Bit: 11 | Usage: 0009/0004: Button / Button 4 | Logical Range: 0..=1 |
# | Bit: 12 | Usage: 0009/0005: Button / Button 5 | Logical Range: 0..=1 |
# | Bits: 13..=15 | ######### Padding |
# | Bits: 16..=31 | Usage: 0001/0030: Generic Desktop / X | Logical Range: -32767..=32767 |
# | Bits: 32..=47 | Usage: 0001/0031: Generic Desktop / Y | Logical Range: -32767..=32767 |
# | Bits: 48..=63 | Usage: 0001/0038: Generic Desktop / Wheel | Logical Range: -32767..=32767 | Physical Range: 0..=0 |
# | Bits: 64..=79 | Usage: 000c/0238: Consumer / AC Pan | Logical Range: -32767..=32767 | Physical Range: 0..=0 |
# ------- Input Report -------
# Report ID: 31
# Report size: 24 bits
# | Bits: 8..=23 | Usage: 000c/0238: Consumer / AC Pan | Logical Range: -32767..=32767 | Physical Range: 0..=0 |
# ------- Feature Report -------
# Report ID: 18
# Report size: 16 bits
# | Bits: 8..=9 | Usage: 0001/0048: Generic Desktop / Resolution Multiplier | Logical Range: 0..=1 | Physical Range: 1..=12 |
# | Bits: 10..=11 | Usage: 0001/0048: Generic Desktop / Resolution Multiplier | Logical Range: 0..=1 | Physical Range: 1..=12 |
# | Bits: 12..=15 | ######### Padding |
# ------- Feature Report -------
# Report ID: 23
# Report size: 16 bits
# | Bits: 8..=9 | Usage: ff00/ff06: Vendor Defined Page 0xFF00 / Vendor Usage 0xff06 | Logical Range: 0..=1 | Physical Range: 1..=12 |
# | Bits: 10..=11 | Usage: ff00/ff0f: Vendor Defined Page 0xFF00 / Vendor Usage 0xff0f | Logical Range: 0..=1 | Physical Range: 1..=12 |
# | Bit: 12 | Usage: ff00/ff04: Vendor Defined Page 0xFF00 / Vendor Usage 0xff04 | Logical Range: 0..=1 | Physical Range: 0..=0 |
# | Bits: 13..=15 | ######### Padding |
##############################################################################
# Recorded events below in format:
# E: . [bytes ...]
#
# Current time: 11:31:20
# Report ID: 26 /
# Button 1: 0 | Button 2: 0 | Button 3: 0 | Button 4: 0 | Button 5: 0 | X: 5 | Y: 0 |
# Wheel: 0 |
# AC Pan: 0 |
E: 000000.000124 10 1a 00 05 00 00 00 00 00 00 00
