Introduction to HID Concepts

This section introduces Human Interface Devices (or HID). These are typically devices that humans use to directly control the operation of computer systems.

Examples of interactive input devices include:

  • Keyboards and pointing devices such as standard mouse devices, trackballs, and joysticks.
  • Front-panel controls such as knobs, switches, buttons, and sliders.
  • Controls found on devices such as telephones and other consumer electronics.
  • Controls, games, and simulation devices such as data gloves, throttles, steering wheels, and rudder pedals.
  • Sensory data such as accelerometers, gyroscope data.

History of HID

The definition of HID started as a device class over USB. The goal at that time was to define a replacement to PS/2 and create an interface over USB allowing operating systems to build a generic driver for HID devices like keyboards, mice, and game controllers. Prior to HID, devices had to conform to strictly defined protocols for mice and keyboards. All hardware innovations necessitated overloading the use of data in an existing protocol or creation of non-standard hardware that needed its own drivers. The vision of HID started with providing a way for providing basic support for these “boot mode” devices in the operating system but still allowing for hardware vendors differentiation with extensible, standardized and easily programmable interfaces.

Today, HID devices include: alphanumeric displays, barcode readers, volume controls on speakers/headsets, auxiliary displays, sensors, and MRI’s (yes, in hospitals). In addition, many hardware vendors use HID for their proprietary devices.

HID started over USB but was designed in a bus agnostic fashion from the very beginning. It was originally designed for low latency, low bandwidth devices but is flexible and the rate is specified by the underlying transport. The specification for USB was ratified in the late 1990s, however support over additional transports started soon after. Today HID has a standard protocol over multiple transports. The following standards are supported natively in Windows 8:

  • USB
  • Bluetooth
  • Bluetooth LE
  • I2C

Vendor specific transports are also allowed via 3rd party vendor specific transport drivers. More details will be provided in later sections.

HID Concepts

HID is built on a couple of fundamental concepts, a Report Descriptor, and reports. Reports are the actual data blobs that are exchanged between a device and a software client. The Report Descriptor describes the format and meaning of each data blob that it supports.

Top Level Collections

The Report Descriptor will describe one or more Top Level Collections. A Top Level Collection is a grouping of functionality that is targeting a particular software consumer (or type of consumer) of the functionality. The device describes the purpose of each particular Top Level Collection in order to allow consumers of HID functionality to identify Top Level Collections that they might be interested in. For example, a Top Level Collection may be described as a Keyboard, Mouse, Consumer Control, Sensor, Display, etc. In the HID spec, these Top Level Collections are also referred to as Application Collections. In Windows, HIDCLASS will generate a unique PDO for each Top Level Collection described by the Report Descriptor.

Report

When applications and HID devices exchange data, this is done through Reports. There are three report types: Input Reports, Output Reports, and Feature Reports.

Report TypeDescription
Input ReportData blobs that are sent from the HID device to the application, typically when the state of a control changes.
Output ReportData blobs that are sent from the application to the HID device, for example the LEDs on a keyboard.
Feature ReportData blobs that can be manually read and/or written, and are typically related to configuration information.

 

Each Top Level Collection defined in a Report Descriptor can contain 0 or more reports of each type.

Usage Tables

The HID working group publishes a set of documents that make up the HID Usage Tables. This is effectively the dictionary which describes all the published things HID devices can do. These HID Usage Tables contains a list and description of a bunch of Usages. A Usage provides information to an application developer about the intended meaning and use of a particular item described in the Report Descriptor. For example, there is a usage defined for the left button of a mouse. The Report Descriptor can define where in a report an application can find the current state of the mouse’s left button. The Usage Tables are broken up into several name spaces, called Usage Pages. Each Usage Page describes a set of related Usages to help organize the document. The combination of a Usage Page and Usage defines the Usage ID that uniquely identifies a specific usage in the Usage Tables.

The HID Application Programming Interface (API)

There are three categories of HID APIs: device discovery and setup, data movement, and report creation/interpretation.

Device Discovery and Setup

The following list identifies HID API that an application can use to: identify properties of a HID device, and, to establish communication with that device. In addition, an application can use some of these API to identify a Top Level Collection.

  • HidD_GetAttributes
  • HidD_GetHidGuid
  • HidD_GetIndexedString
  • HidD_GetManufacturerString
  • HidD_GetPhysicalDescriptor
  • HidD_GetPreparsedData
  • HidD_GetProductString
  • HidD_GetSerialNumberString
  • HidD_GetNumInputBuffers
  • HidD_SetNumInputBuffers

Data Movement

The following list identifies HID API that an application can use to move data back and forth between the app and a selected device.

  • HidD_GetInputReport
  • HidD_SetFeature
  • HidD_SetOutputReport
  • ReadFile
  • WriteFile

Report Creation and Interpretation

If you are writing a HID app for your own hardware, you have existing knowledge of the size and format of each report issued by your device. In this case, your app can cast the input and output report buffers to structs and consume the data.

If, however, you are writing a HID app that communicates with all devices that expose common functionality (for example, a music app that needs to detect when a play button is pressed), you may not know the size and format of the HID reports. This category of application understands certain Top Level Collections and certain usages.

In order to interpret the reports received from a device, or to create reports to be sent, the application needs to leverage the Report Descriptor in order to determine if and where a particular usage is located in the reports, and potentially the units of values in the reports. This is where HID parsing is required. Windows provides a HID parser for use by drivers and applications. This parser exposes a set of APIs (HidP_*) that can be used to discover the types of usages supported by a device, determine the state of such usages in a report, or to build a report to change the state of a usage in the device.

The following list identifies the HID parser APIs.

  • HidP_GetButtonCaps
  • HidP_GetButtons
  • HidP_GetButtonsEx
  • HidP_GetCaps
  • HidP_GetData
  • HidP_GetExtendedAttributes
  • HidP_GetLinkCollectionNodes
  • HidP_GetScaledUsageValue
  • HidP_GetSpecificButtonCaps
  • HidP_GetSpecificValueCaps
  • HidP_GetUsages
  • HidP_GetUsagesEx
  • HidP_GetUsageValue
  • HidP_GetUsageValueArray
  • HidP_GetValueCaps
  • HidP_InitializeReportForID
  • HidP_IsSameUsageAndPage
  • HidP_MaxDataListLength
  • HidP_MaxUsageListLength
  • HidP_SetButtons
  • HidP_SetData
  • HidP_SetScaledUsageValue
  • HidP_SetUsages
  • HidP_SetUsageValue
  • HidP_SetUsageValueArray
  • HidP_UnsetButtons
  • HidP_UnsetUsages
  • HidP_UsageAndPageListDifference
  • HidP_UsageListDifference

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft