Learning USB Hid in Linux Part 4 - Usage Page, Usages, Report Size and Report Count

Report Descriptor defines the format and use of the data in the HID's report. Report descriptor needs to be flexible enough to handle devices with different purposes. Data should use a concise format to keep from wasting storage space in the device or bus time when the data transmit. HID Report descriptors achieve both goals by using a format that's more complex and less readable than a more verbose format might be.

A usage provides information to an application developer about the intended meaning and use of a particular item described in the Report Descriptor.

HID Usages are organized into usage pages of related control.  A usage page value is an unsigned 16-bit value.
Eg: Generic Desktop Control, Game Controls, LEDs, Buttons etc

In the context of usage page, usage id indicates a usage in the usage page. A value of zero is reserved. A Usage ID is an unsigned 16-bit value.

The combination of Usage page and Usage ID uniquely identifies a specific Usage in the Usage Tables.

Examples:
     0001 0030 // Generic Desktop, X
     0001 0082 // Generic Desktop, System Sleep
     0003 0005 // VR Controls, Head Tracker
     0003 0006 // VR Controls, Head Mounted Display
     0007 0030 // Keyboard, Keyboard 1 and !4

Note how the usage ID in the last item is the same as the first one, Adding Usage page differentiates the actual usage.

The usage pages and usages are values published in the HID Usage Table Specification.

So, for Mouse on Desktop.
Usage Page: Generic desktop controls (01h)
Usage : Mouse (Mouse (02h, application collection))

A report descriptor begins with a usage page item that describes the general function of all of the reports that follow. For instance, in a report descriptor describing reports for a USB keyboard or a USB mouse, such as the one found in the USB mouse example in this document, designers would use the “Generic Desktop” usage page. Reports contained in defined usage pages have defined usages, which provide more specific information about the report contents. For example, a keyboard would use the “Keyboard” usage for its “Generic Desktop” usage page.

Report Size: Indicates how many bits are in each reported data item.
Report Count: Indicates how many data items the report contains.

To report X, Y Coordinates of mouse:
Usage Page (Generic Desktop)
Usage(X)
Report Size (16)
Usage Page (Generic Desktop)
Usage(Y)
Report Size (16)

This tells the host: X and Y both have 16 bits. So, if we get 4-byte Report from the device, we know two bytes are for X, two bytes for Y coordinate.

Global Items: HID was invented when storage was costly, and they can't afford to waste any bits. HID makes use of so-called Global items, once those are set their values applies to all following items until changed.
E.g. Usage Page, Report Size.

So, the above report descriptor can be implemented as:

Usage Page (Generic Desktop)
Usage (X)
Usage (Y)
Report Count (2)
Report Size (16)
Input (Variable, Relative)


Data values are further described by designating each data item as input, output or feature.

Input: means data travel from device to host
Output: means data travel from host to device
Feature: means data travel in either direction

Data items can also be designated as variable or constant.

Variable: Values can be read or written.
Constant: Values are read-only.

Another often-used designation indicates
Absolute: Value contained in a report is measured from a fixed origin
Relative: Value has no fixed reference and instead describes the changes of value since the last report.

References:

1. https://docs.microsoft.com/en-us/windows-hardware/drivers/hid/hid-usages#usage-page
2. http://who-t.blogspot.com/2018/12/understanding-hid-report-descriptors.html
3. https://www.silabs.com/documents/public/application-notes/AN249.pdf