Jan Axelson, USB Complete

Подождите немного. Документ загружается.

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.

*+&URGEKHKE4GSWGUVU

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

NQYD[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

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

)GV4GRQTV

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

)GV2TQVQEQN

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.

5GV4GRQTV

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.

5GV2TQVQEQN

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.

4GRQTV5VTWEVWTG

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