Chapter 11 286 reports, the BIOS sends the HID-specific Set Protocol request to request to use the boot protocol. When the full HID drivers have been loaded, the driver can use Set Protocol to cause the device to switch from the boot protocol to the report protocol, which uses the report formats defined in the report descriptor. If the HID doesn’t support a boot protocol, bInterfaceSubclass = 00h. *+&%NCUU&GUETKRVQT The HID class descriptor (Table 11-2) identifies additional descriptors for HID communications. The class descriptor has seven or more fields depending on the number of additional descriptors. 4GRQTV&GUETKRVQTU A report descriptor defines the format and use of the data in the HID’s reports. If the device is a mouse, the data reports mouse movements and button clicks. If the device is a relay controller, the data specifies which relays to open and close. The descriptor format is flexible enough for use with devices with varied functions. A report descriptor is a class-specific descriptor. The host retrieves the descrip- tor by sending a Get Descriptor request to the interface with the wValue field containing 22h in the high byte. Listing 11-2 is a basic report descriptor that defines an Input report, an Output report, and a Feature report. The device sends two bytes of vendor-defined data in the Input report. The host sends two bytes of vendor-defined data in the Output report. The Feature report is two bytes of vendor-defined data that the host can send to the device or request from the device. Basic report descriptors similar to this example can serve many HIDs with ven- dor-specific functions. For a loop-back test, device firmware can copy received data from an Input report into an Output report to send back to the host. For a “lights and switches” application, firmware can use received Input report data to control LEDs and use Output reports to send logic states read at switches. Each item in the report descriptor consists of a byte that identifies the item and one or more bytes containing the item’s data. The HID specification defines item types that a report can contain. Here is the function of each item in the example report descriptor: The Usage Page item (06h) specifies the general function of the device, such as generic desktop control, game control, or alphanumeric display. In the example Human Interface Devices: Using Control and Interrupt Transfers 287 descriptor, the Usage Page is the vendor-defined value FFA0h. The HID Usage Tables document provides values for different Usage Pages. Vendor-defined Usage Pages use the range FF00h–FFFFh. The Usage item (09h) specifies the function of an individual report in a Usage Page. For example, Usages available for generic desktop controls include mouse, joystick, and keyboard. Because the example’s Usage Page is vendor-defined, all of the Usages in the Usage Page are vendor-defined also. In the example, the Usage is 01h. The Collection (Application) item (A1h) begins a group of items that together perform a single function, such as keyboard or mouse. Each report descriptor must have an application collection. The Collection contains three reports. Each report has these items: A vendor-defined Usage applies to the data in the report. A Logical Minimum and Logical Maximum specify the range of values that the report can contain. Table 11-2: The HID class descriptor specifies the length of the report descriptor. 1HHUGV FGEKOCN (KGNF 5K\G D[VGU &GUETKRVKQP 0 bLength 1 Descriptor size in bytes. 1 bDescriptorType 1 This descriptor’s type: 21h to indicate the HID class. 2 bcdHID 2 HID specification release number (BCD). 4 bCountryCode 1 Numeric expression identifying the country for localized hardware (BCD) or 00h. 5 bNumDescriptors 1 Number of subordinate report and physical descriptors. 6 bDescriptorType 1 The type of a class-specific descriptor that follows. (A report descriptor (required) is type 22h.) 7 wDescriptorLength 2 Total length of the descriptor identified above. 9 bDescriptorType 1 Optional. The type of a class-specific descriptor that follows. A physical descriptor is type 23h. 10 wDescriptorLength 2 Total length of the descriptor identified above. Present only if bDescriptorType is present immediately above. May be followed by additional wDescriptorType and wDescriptorLength fields to identify additional physical descriptors. Chapter 11 288 The Report Size item indicates how many bits are in each reported data item. In the example, each data item is eight bits. The Report Count item indicates how many data items the report contains. In the example, each report contains two data items. In the final item, the first byte specifies whether the report is an Input report (81h), Output report (91h), or Feature report (B1h). The second byte con- tains additional information about the report data, such as whether the val- ues are relative or absolute. 06 FFA0 Usage Page (vendor-defined) 09 01 Usage (vendor-defined) A1 01 Collection (Application) 09 03 Usage (vendor-defined) 15 00 Logical Minimum (0) 26 00FF Logical Maximum (255) 95 02 Report Size (8 bits) 75 08 Report Count (2) 81 02 Input (Data, Variable, Absolute) 09 04 Usage (vendor-defined) 15 00 Logical Minimum (0) 26 00FF Logical Maximum (255) 75 08 Report Size (8 bits) 95 02 Report Count (2) 91 02 Output (Data, Variable, Absolute) 09 05 Usage (vendor-defined) 15 00 Logical Minimum (0) 26 00FF Logical Maximum (255) 75 08 Report Size (8 bits) 95 02 Report Count (2) B1 02 Feature (Data, Variable, Absolute) C0 End Collection Listing 11-2: This report descriptor defines an Input report, an Output report, and a Feature report. Each report transfers two vendor-defined bytes. All values are hexadecimal. Human Interface Devices: Using Control and Interrupt Transfers 289 An End Collection item (C0h) closes the Application Collection. These are the basics. Chapter 12 has more about report formats. *+&URGEKHKE4GSWGUVU The HID specification defines six HID-specific requests (Table 11-3). Table 11-3: The HID class defines six HID-specific requests. 4GSWGUV 0WODGT 4GSWGUV &CVC 5QWTEG &CVC UVCIG Y8CNWG JKIJ D[VG NQYD[VG Y+PFGZ &CVC .GPIVJ D[VGU Y.GPIVJ &CVC 5VCIG %QPVGPVU 4GSWKTGF! 01h Get Report device report type, Report ID interface report length report yes 02h Get Idle device 00h, Report ID interface 0001h idle duration no 03h Get Protocol device 0000h interface 0001h protocol yes for HIDs that support a boot protocol 09h Set Report host report type, Report ID interface report length report no 0Ah Set Idle no Data stage idle duration, Report ID interface – – no, except for keyboards using the boot protocol 0Bh Set Protocol no Data stage 00h, protocol interface – – yes for HIDs that support a boot protocol Chapter 11 290 )GV4GRQTV Purpose: The host requests an Input or Feature report from a HID using a control transfer. Request Number (bRequest): 01h Source of Data: device Data Length (wLength): length of the report Contents of wValue field: The high byte contains the report type (01h = Input, 03h = Feature), and the low byte contains the Report ID. The default Report ID is zero. Contents of wIndex field: the number of the interface the request is directed to. Contents of data packet in the Data stage: the report Comments: The HID specification says that all HIDs must support this request. A host may enumerate and communicate with a HID that doesn’t support the request, but future editions of the operating system might enforce the requirement. See also Set Report. )GV+FNG Purpose: The host reads the current Idle rate from a HID. Request Number (bRequest): 02h Source of Data: device Data Length (wLength): 0001h Contents of wValue field: The high byte is 00h. The low byte indicates the Report ID the request applies to. If the low byte is 00h, the request applies to all of the HID’s Input reports. Contents of wIndex field: the number of the interface that supports this request. Contents of data packet in the Data stage: the Idle rate, expressed in units of 4 ms. Comments: HIDs aren’t required to support this request. See Set Idle for more details. Human Interface Devices: Using Control and Interrupt Transfers 291 )GV2TQVQEQN Purpose: The host learns whether the boot or report protocol is currently active in the HID. Request Number (bRequest): 03h Source of Data: device Data Length (wLength): 0001h Contents of wValue field: 0000h Contents of wIndex field: the number of the interface that supports this request. Contents of data packet in the Data stage: the protocol (00h = boot protocol, 01h = report protocol). Comments: Boot devices must support this request. See also Set Protocol. 5GV4GRQTV Purpose: The host sends an Output or Feature report to a HID using a control trans- fer. Request Number (bRequest): 09h Source of Data: host Data Length (wLength): length of the report Contents of wValue field: The high byte contains the report type (02h = Output, 03h = Feature), and the low byte contains the Report ID. The default Report ID is zero. Contents of wIndex field: the number of the interface the request is directed to. Contents of data packet in the Data stage: the report. Comments: If a HID interface doesn’t have an Interrupt OUT endpoint or if the host complies only with version 1.0 of the HID specification, this request is the only way the host can send data to the HID. HIDs aren’t required to support this request. See also Get Report. Chapter 11 292 5GV+FNG Purpose: saves bandwidth by limiting the reporting frequency of an interrupt IN end- point when the data hasn’t changed since the last report. Request Number (bRequest): 0Ah Data Length (wLength): 0000h Contents of wValue field: The high byte sets the duration, or the maximum amount of time between reports. A value of 00h means that the HID will send a report only when the report data has changed. The low byte indicates the Report ID that the request applies to. If the low byte is 00h, the request applies to all of the HID’s Input reports. Contents of wIndex field: the number of the interface that supports this request. Comments: The duration is in units of 4 ms, which gives a range of 4–1,020 ms. No matter what the duration value, if the report data has changed since the last Input report sent, on receiving an interrupt IN token packet, the HID sends the data. If the data hasn’t changed and the duration time hasn’t elapsed since the last report, the HID returns NAK. If the data hasn’t changed and the duration time has elapsed since the last report, the HID sends report data. A duration value of 00h indicates an infinite duration: the HID sends a report only if the report data has changed and otherwise returns NAK. On enumerating a HID, the Windows HID driver attempts to set the idle rate to 00h. HIDs aren’t required to support this request except for keyboards using the boot protocol. Not all device controllers have hardware support for the Idle rate though firmware can support the feature with help from a hardware timer. A HID can refuse the request by returning STALL. See also Get Idle. 5GV2TQVQEQN Purpose: The host specifies whether the HID should use the boot or report protocol. Request Number (bRequest): 0Bh Data Length (wLength): 0000h Contents of wValue field: the protocol (0000h = boot protocol, 0001h = report pro- tocol). Contents of wIndex field: the number of the interface that supports this request. Comments: Boot devices must support this request. See also Get Protocol. Human Interface Devices: Using Control and Interrupt Transfers 293 6TCPUHGTTKPI&CVC When enumeration is complete, the host has identified the device interface as a HID, established pipes with the interface’s endpoints, and learned the report formats for sending and receiving data. The host can then request reports using interrupt IN transfers and control transfers with Get Report requests. The device also has the option to support receiving reports using interrupt OUT transfers and control transfers with Set Report requests. 9TKVKPI(KTOYCTG Many firmware compilers provide HID examples, perhaps because all major operating systems provide host HID drivers and HID firmware is less complex than what’s required for many other classes. 2$2 PIC BASIC PRO includes code for a mouse and a generic HID that sends and receives reports using interrupt transfers. Supporting the HID Get Report or Set Report requests would require added support in assembly code. % Microchip provides HID example code for the PIC18F4550 and other Micro- chip microcontrollers for the MPLAB C18 compiler. Microchip’s USB Frame- work includes mouse and generic HID examples. The code supports sending and receiving reports using interrupt transfers. See www.Lvr.com for a generic HID example that supports exchanging reports via both interrupt and control transfers. 6QQNU Another option for users of Microchip controllers is HIDmaker FS from Trace Systems, Inc. A software wizard asks questions about your device and generates firmware to implement the Input, Output, and Feature reports you specify. The wizard supports the PICBASIC PRO compiler as well as the Microchip MPLAB C18, CCS C, and HI-TECH C compilers. The wizard can generate PC application code to access the HID in several programming languages. The HIDmaker Test Suite includes two other tools. The AnyHID application displays report descriptors and enables exchanging data with attached and enu- merated HIDs (except system mice and keyboards). USBwatch is a low-budget USB analyzer for HIDs. To use the analyzer, you add the provided code to your Chapter 11 294 device firmware and connect the device’s asynchronous serial port to a PC’s serial port via RS-232 or a USB/COM-port adapter. The firmware writes debugging data to the serial port for display by the USBwatch application. USBwatch can display enumeration and application data. You can also define your own messages for firmware to send at locations you select in your code. 295 *WOCP+PVGTHCEG&GXKEGU 4GRQTVU Chapter 11 introduced the reports that HIDs use to exchange data. A report can be a basic buffer of bytes or a complex assortment of items with assigned functions and units. This chapter shows how to create reports to fit specific applications. 4GRQTV5VTWEVWTG The report descriptor provides information about the data the HID sends and receives. The descriptor identifies the device’s function and can specify uses and units for the report data. Controls and data items describe values to be trans- ferred in one or more reports. A control is a button, switch, or other physical entity that operates or regulates an aspect of a device. Everything else is a data item. For vendor-specific devices intended for use with a single application, the appli- cation often knows in advance the type, size, and order of the data in a report so there’s no need to obtain this information from the device. For example, when the vendor of a data-acquisition unit creates an application for use with the . to a PC’s serial port via RS-232 or a USB/ COM-port adapter. The firmware writes debugging data to the serial port for display by the USBwatch application. USBwatch can display enumeration and. exchanging data with attached and enu- merated HIDs (except system mice and keyboards). USBwatch is a low-budget USB analyzer for HIDs. To use the analyzer, you add the provided code to your Chapter. Devices: Using Control and Interrupt Transfers 293 6TCPUHGTTKPI&CVC When enumeration is complete, the host has identified the device interface as a HID, established pipes with the interface’s