Crate hidreport 

This crate provides parsing and building of HID Report Descriptors, including the hid module to inspect or build a report descriptor in more detail. Check out the hut crate for known HID Usages to make sense of the various HID fields.

Parsing HID Report Descriptors

Entry point is usually ReportDescriptor::try_from(bytes):

let rdesc: ReportDescriptor = ReportDescriptor::try_from(bytes).unwrap();
for r in rdesc.input_reports() {
    println!("Input Report with report ID: {:?}", r.report_id());
}

let input_report_bytes = read_from_device();
let report = rdesc.find_input_report(&input_report_bytes).unwrap();
println!("This is an input report for report ID: {:?}", report.report_id());
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);
    }
    Field::Array(arr) => {
        let vals: Vec<u32> = arr.extract(&input_report_bytes).unwrap().iter().map(u32::from).collect();
        println!("Field {:?} has values {:?}", field, vals);
    }
    Field::Constant(_) => {
        println!("Field {:?} is <padding data>", field);
    }
}

In this document and unless stated otherwise, a reference to “Section a.b.c” refers to the HID Device Class Definition for HID 1.11.

Building HID Report Descriptors programmatically

This module can be used to build a HID Report Descriptor from scratch via the hid module:

use hut::{self, AsUsagePage, AsUsage};
let builder = ReportDescriptorBuilder::new();
let rdesc: Vec<u8> = builder
       .append(hut::UsagePage::GenericDesktop.into())
       .append(hut::GenericDesktop::Mouse.usage().into())
       .open_collection(CollectionItem::Application)
       .open_collection(CollectionItem::Physical)
       .push()
       .append(LogicalMinimum::from(0).into())
       .append(LogicalMaximum::from(128).into())
       .pop()
       .append(ReportCount::from(2).into())
       .append(ReportSize::from(8).into())
       .append(hut::GenericDesktop::X.usage().into())
       .append(hut::GenericDesktop::Y.usage().into())
       .input(ItemBuilder::new()
              .variable()
              .absolute()
              .input())
       .close_collection()
       .close_collection()
       .build();

See the ReportDescriptorBuilder documentation for more details.

Re-exports

pub use hid::CollectionItem as CollectionType;

pub use types::*;

Modules

hid

A wrapper around the HID Core items. This module handles splitting a report descriptor byte stream into its individual components. Interpretation and/or analysis of the resulting Items is left to the caller.

types

A collection of standalone HID types that exist for type safety only. These are all simple wrappers around their underlying integer data type.

Structs

ArrayField

An ArrayField represents a group of physical controls, see section 6.2.2.5.

Collection

Collections group Fields together into logical or physical groups.

CollectionId

A unique (within this report descriptor) identifier for a collection.

ConstantField

A ConstantField is one that represents a hid::MainItem with Constant data, see Section 6.2.2.4.

FieldId

A unique (within this report descriptor) identifier for a Field.

FieldValue

A wrapper around the value of a Field inside a HID Report’s byte array. This value may be signed, depending on the Field.

ReportDescriptor

A ReportDescriptor is the static set of Items that define how data from the device should be interpreted.

Usage

The usage of a Field defines the interpretation of a data value. See the hut crate for a list of known Usages.

UsageRange

Wrapper around the commonly used UsageMinimum and UsageMaximum.

VariableField

A VariableField represents a single physical control.

Enums

Field

A single field inside a Report.

ParserError

Traits

FieldAttributes

Field attributes, see Main Data Item in Section 6.2.5.

Report

A HID Input, Output or Feature Report.