HID Sensor Usage Tables - USB.org

103 HID Sensor Usages
Because these structures are large (a PROPERTYKEY is 20 bytes, the GUID_OR_PROPERTYKEY struct
is 30 bytes), this leaves only a modest amount of available space in the Report for the data value itself
(leaves 43 bytes when using a PROPERTYKEY, and leaves 33 bytes when using a
GUID_OR_PROPERTYKEY struct).
In many cases, this may be acceptable. But this provides a practical limit of packing only a single Item in a
Report. And some Items have a native size (narrow character strings, wide character strings, response
curve structs, rotation matrix structs) that may no longer fit at all.
To mitigate this, a strategy called the Generic Enumerator is introduced, whereby all the bulky
“indentifying information” (specifically GUID_OR_PROPERTYKEY structs) are taken out of their
“inline” positions and grouped together in their own dedicated HID top level collection.
The HID Report Descriptor for this new top level collection is as follows:
// Complete HID report descriptor
const unsigned char enumerator_report_descriptor[] = {
HID_USAGE_PAGE_SENSOR,
HID_USAGE_SENSOR_TYPE_OTHER_GENERIC,
HID_COLLECTION(Application),
HID_REPORT_ID(1),
};
// Report ID 0x01: ENUMERATOR INPUT report
// Data Field 1: Enumerator Table Row Index. Read-Only.
// On a HID GET INPUT, auto-post-increments (use HID SET FEATURE to set the start row).
HID_USAGE_SENSOR_DATA_ENUMERATOR_TABLE_ROW_INDEX,
HID_LOGICAL_MIN_16(0x00, 0x00),
HID_LOGICAL_MAX_16(0xff, 0xff),
HID_REPORT_SIZE(16),
HID_REPORT_COUNT(1),
HID_INPUT(Const_Var_Abs),
// Data Field 2: Enumerator Table Row Data. Read-Only.
// Contents defined by GUID_OR_PROPERTYKEY struct (which is 30 bytes long).
HID_USAGE_SENSOR_DATA_GENERIC_GUID_OR_PROPERTYKEY,
HID_LOGICAL_MIN_8(0x00),
HID_LOGICAL_MAX_8(0xff),
HID_REPORT_SIZE(8),
HID_REPORT_COUNT(30),
HID_INPUT(Const_Arr_Abs),
// Report ID 0x01: ENUMERATOR FEATURE report
// Property 1: Enumerator Table Row Index. Read/Write.
// On a HID SET FEATURE, used to set the start row.
HID_USAGE_SENSOR_PROPERTY_ENUMERATOR_TABLE_ROW_INDEX,
HID_LOGICAL_MIN_16(0x00, 0x00),
HID_LOGICAL_MAX_16(0xff, 0xff),
HID_REPORT_SIZE(16),
HID_REPORT_COUNT(1),
HID_FEATURE(Data_Var_Abs),
// Property 2: Enumerator Table Row Count. Read-Only.
// On a HID GET FEATURE, used to get the total count of Table Rows.
HID_USAGE_SENSOR_PROPERTY_ENUMERATOR_TABLE_ROW_COUNT,
HID_LOGICAL_MIN_16(0x00, 0x00),
HID_LOGICAL_MAX_16(0xff, 0xff),
HID_REPORT_SIZE(16),
HID_REPORT_COUNT(1),
HID_FEATURE(Const_Var_Abs),
HID_END_COLLECTION
The Generic Enumerator must be the first top level collection. The Report ID for the Input Report and
Feature Report must be 0x01.
The platform driver uses these pre-defined values to “bootstrap” itself by:
Performing a HID Get Feature request to read the
HID_USAGE_SENSOR_PROPERTY_ENUMERATOR_TABLE_ROW_COUNT;
Performing a HID Set Feature request to reset the
HID_USAGE_SENSOR_PROPERTY_ENUMERATOR_TABLE_ROW_INDEX to zero.
Performing a loop for
HID_USAGE_SENSOR_PROPERTY_ENUMERATOR_TABLE_ROW_COUNT times of: