00001 /* ---------------------------------------------------------------------------- 00002 * ATMEL Microcontroller Software Support 00003 * ---------------------------------------------------------------------------- 00004 * Copyright (c) 2008, Atmel Corporation 00005 * 00006 * All rights reserved. 00007 * 00008 * Redistribution and use in source and binary forms, with or without 00009 * modification, are permitted provided that the following conditions are met: 00010 * 00011 * - Redistributions of source code must retain the above copyright notice, 00012 * this list of conditions and the disclaimer below. 00013 * 00014 * Atmel's name may not be used to endorse or promote products derived from 00015 * this software without specific prior written permission. 00016 * 00017 * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR 00018 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 00019 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE 00020 * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, 00021 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 00022 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 00023 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 00024 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 00025 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 00026 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 00027 * ---------------------------------------------------------------------------- 00028 */ 00029 00030 /** 00031 * \dir usb/device/hid-keyboard 00032 * 00033 * \section Purpose 00034 * 00035 * This directory provides definitions, structs and functions for a USB HID 00036 * device - USB HID Keyboard driver, to implement an USB keyboard device. 00037 * 00038 * \section Contents 00039 * 00040 * There are three things for the implement of the USB HID Keyboard driver: 00041 * - Implement the USB HID driver structs and functions for the device, 00042 * to initialize, to handle HID-specific requests and dispach 00043 * standard requests in USBD callbacks, to read/write through assigned USB 00044 * endpoints, 00045 * - Create the HID Keyboard device's descriptors that should be passed to 00046 * the USBDDriver instance on initialization, so that the host can 00047 * recognize the device as a USB Keyboard device. 00048 * - Implement methods to update the keyboard keys status, so that host can 00049 * get it through USB. 00050 * 00051 * For more information about what a particular group contains, please refer to 00052 * \ref usbd_hid_key "USB Device HID Keyboard Driver" and 00053 * \ref usbd_hid_kbd_drv "USB Device HID Keyboard Doc". 00054 */ 00055 00056 /** 00057 \page usbd_hid_kbd_drv USB Device HID Keyboard Driver 00058 This page describes how to use the \ref usbd_framework 00059 to produce a USB HID Keyboard driver, which appears as a USB keyboard on host. 00060 00061 Details about the USB and the HID class can be found in the <i>USB specification 00062 2.0</i> and the <i>HID specification 1.11</i>, respectively. 00063 00064 \section References 00065 - \ref usbd_framework 00066 - \ref usbd_enum 00067 - <a href="http://www.usb.org/developers/docs/usb_20_040908.zip"> 00068 Universal Serial Bus Revision 2.0 specification 00069 </a> (.zip file format, size 9.80 MB) 00070 - <a href="http://www.usb.org/developers/devclass_docs/HID1_11.pdf"> 00071 Device Class Definition for HID 1.11</a> 00072 - <a href="http://www.usb.org/developers/devclass_docs/Hut1_12.pdf"> 00073 HID Usage Tables 1.12</a> 00074 00075 \section hid_base HID Basic 00076 See \subpage usb_hid_basic "USB HID Basic". 00077 00078 \section Architecture 00079 See \ref usbd_framework_arch. 00080 00081 \section Descriptors 00082 00083 \subsection dev_desc Device Descriptor 00084 The Device descriptor of an HID device is very basic, since the HID class 00085 code is only specified at the Interface level. Thus, it only contains 00086 standard values, as shown below: 00087 \code 00088 static const USBDeviceDescriptor deviceDescriptor = { 00089 00090 sizeof(USBDeviceDescriptor), 00091 USBGenericDescriptor_DEVICE, 00092 USBDeviceDescriptor_USB2_00, 00093 HIDDeviceDescriptor_CLASS, 00094 HIDDeviceDescriptor_SUBCLASS, 00095 HIDDeviceDescriptor_PROTOCOL, 00096 BOARD_USB_ENDPOINTS_MAXPACKETSIZE(0), 00097 HIDDKeyboardDriverDescriptors_VENDORID, 00098 HIDDKeyboardDriverDescriptors_PRODUCTID, 00099 HIDDKeyboardDriverDescriptors_RELEASE, 00100 1, // Index of manufacturer description 00101 2, // Index of product description 00102 3, // Index of serial number description 00103 1 // One possible configuration 00104 }; 00105 \endcode 00106 Note that the Vendor ID is a special value attributed by the USB-IF 00107 organization. The product ID can be chosen freely by the vendor. 00108 00109 \subsection cfg_desc Configuration Descriptor 00110 Since one interface is required by the HID specification, this must be 00111 specified in the Configuration descriptor. There is no other value of 00112 interest to put here. 00113 \code 00114 // Configuration descriptor 00115 { 00116 sizeof(USBConfigurationDescriptor), 00117 USBGenericDescriptor_CONFIGURATION, 00118 sizeof(HIDDKeyboardDriverConfigurationDescriptors), 00119 1, // One interface in this configuration 00120 1, // This is configuration #1 00121 0, // No associated string descriptor 00122 BOARD_USB_BMATTRIBUTES, 00123 USBConfigurationDescriptor_POWER(100) 00124 }, 00125 \endcode 00126 When the Configuration descriptor is requested by the host (by using the 00127 GET_DESCRIPTOR command), the device must also sent all the related 00128 descriptors, i.e. Interface, Endpoint and Class-Specific descriptors. It is 00129 convenient to create a single structure to hold all this data, for sending 00130 everything in one chunk. In the example software, a 00131 HIDDKeyboardDriverConfigurationDescriptors structure has been declared for 00132 that. 00133 00134 \subsection hid_class_if_desc HID Class Interface Descriptor 00135 Since a keyboard device needs to transmit as well as receive data, two 00136 Interrupt (IN & OUT) endpoints are needed. This must be indicated in the 00137 Interface descriptor. Conversely to the mouse example, the Boot protocol is 00138 not implemented here, since there are more constraints on a keyboard device. 00139 \code 00140 // Interface descriptor 00141 { 00142 sizeof(USBInterfaceDescriptor), 00143 USBGenericDescriptor_INTERFACE, 00144 0, // This is interface #0 00145 0, // This is alternate setting #0 00146 2, // Two endpoints used 00147 HIDInterfaceDescriptor_CLASS, 00148 HIDInterfaceDescriptor_SUBCLASS_NONE, 00149 HIDInterfaceDescriptor_PROTOCOL_NONE, 00150 0 // No associated string descriptor 00151 }, 00152 \endcode 00153 00154 \subsection hid_desc HID Descriptor 00155 While a HID keyboard produces two different reports, one Input and one Output, 00156 only one Report descriptor can be used to describe them. Since having Physical 00157 descriptors is also useless for a keyboard, there will only be one HID class 00158 descriptor specified here. 00159 00160 For a keyboard, the <i>bCountryCode</i> field can be used to specify the language 00161 of the key caps. As this is optional, it is simply set to 00h in the example: 00162 \code 00163 // HID descriptor 00164 { 00165 sizeof(HIDDescriptor), 00166 HIDGenericDescriptor_HID, 00167 HIDDescriptor_HID1_11, 00168 0, // Device is not localized, no country code 00169 1, // One HID-specific descriptor (apart from this one) 00170 HIDGenericDescriptor_REPORT, 00171 HIDDKeyboardDriverDescriptors_REPORTSIZE 00172 }, 00173 \endcode 00174 00175 \subsection hid_report_desc Report Descriptor 00176 Two current reports are defined in the Report descriptor. The first one is 00177 used to notify the host of which keys are pressed, with both modifier keys 00178 (alt, ctrl, etc.) and alphanumeric keys. The second report is necessary for 00179 the host to send the LED (num lock, caps lock, etc.) states. 00180 00181 The Report descriptor starts with the global device functionality, described 00182 with a <b>Usage Page</b> and a <b>Usage</b> items: 00183 \code 00184 const unsigned char hiddReportDescriptor[] = { 00185 00186 HIDReport_GLOBAL_USAGEPAGE + 1, HIDGenericDesktop_PAGEID, 00187 HIDReport_LOCAL_USAGE + 1, HIDGenericDesktop_KEYBOARD, 00188 \endcode 00189 00190 As in the mouse example, the <i>Generic Desktop</i> page is used. This time, the 00191 specific usage is the <i>Keyboard</i> one. An Application collection is then 00192 defined to group the reports together: 00193 \code 00194 HIDReport_COLLECTION + 1, HIDReport_COLLECTION_APPLICATION, 00195 \endcode 00196 00197 The first report to be defined is the modifier keys. They are represented as a 00198 bitmap field, indicating whether or not each key is pressed. A single byte is 00199 used to map keys \#224-231 defined in the <i>HID Usage Tables</i> document: 00200 LeftControl, LeftShift, LeftAlt, LeftGUI (e.g. Windows key), 00201 RightControl, RightShift, RightAlt and RightGUI. 00202 The <i>Keypad</i> usage page must be specified for this report, and since this is a 00203 bitmap value, the data is flagged as <i>Variable</i>: 00204 \code 00205 // Input report: modifier keys 00206 HIDReport_GLOBAL_REPORTSIZE + 1, 1, 00207 HIDReport_GLOBAL_REPORTCOUNT + 1, 8, 00208 HIDReport_GLOBAL_USAGEPAGE + 1, HIDKeypad_PAGEID, 00209 HIDReport_LOCAL_USAGEMINIMUM + 1, 00210 HIDDKeyboardDriverDescriptors_FIRSTMODIFIERKEY, 00211 HIDReport_LOCAL_USAGEMAXIMUM + 1, 00212 HIDDKeyboardDriverDescriptors_LASTMODIFIERKEY, 00213 HIDReport_GLOBAL_LOGICALMINIMUM + 1, 0, 00214 HIDReport_GLOBAL_LOGICALMAXIMUM + 1, 1, 00215 HIDReport_INPUT + 1, HIDReport_VARIABLE, 00216 \endcode 00217 00218 Then, the actual alphanumeric key report is described. This is done by 00219 defining several bytes of data, one for each pressed key. In the example, 00220 up to three keys can be pressed at the same time (and detected) by the user. 00221 Once again, the usage page is set to <i>Keypad</i>. This time however, the data 00222 must be specified as an <i>Array</i>, since the same control (the keypad) produces 00223 several values: 00224 \code 00225 // Input report: standard keys 00226 HIDReport_GLOBAL_REPORTCOUNT + 1, 3, 00227 HIDReport_GLOBAL_REPORTSIZE + 1, 8, 00228 HIDReport_GLOBAL_LOGICALMINIMUM + 1, 00229 HIDDKeyboardDriverDescriptors_FIRSTSTANDARDKEY, 00230 HIDReport_GLOBAL_LOGICALMAXIMUM + 1, 00231 HIDDKeyboardDriverDescriptors_LASTSTANDARDKEY, 00232 HIDReport_GLOBAL_USAGEPAGE + 1, HIDKeypad_PAGEID, 00233 HIDReport_LOCAL_USAGEMINIMUM + 1, 00234 HIDDKeyboardDriverDescriptors_FIRSTSTANDARDKEY, 00235 HIDReport_LOCAL_USAGEMAXIMUM + 1, 00236 HIDDKeyboardDriverDescriptors_LASTSTANDARDKEY, 00237 HIDReport_INPUT + 1, 0 /* Data array */, 00238 \endcode 00239 00240 The LED array is then defined, with the associated usage page. The Report 00241 descriptor is formatted in this order to avoid redefining unchanged <i>Global</i> 00242 items, in order to save memory. This time again, the LED status is reported as 00243 a bitmap field. Three LEDs are used here: Num Lock, Caps Lock and Scroll Lock 00244 (IDs 01h to 03h). It is important to note that this is an <b>Output</b> report: 00245 \code 00246 // Output report: LEDs 00247 HIDReport_GLOBAL_REPORTCOUNT + 1, 3, 00248 HIDReport_GLOBAL_REPORTSIZE + 1, 1, 00249 HIDReport_GLOBAL_USAGEPAGE + 1, HIDLeds_PAGEID, 00250 HIDReport_GLOBAL_LOGICALMINIMUM + 1, 0, 00251 HIDReport_GLOBAL_LOGICALMAXIMUM + 1, 1, 00252 HIDReport_LOCAL_USAGEMINIMUM + 1, HIDLeds_NUMLOCK, 00253 HIDReport_LOCAL_USAGEMAXIMUM + 1, HIDLeds_SCROLLLOCK, 00254 HIDReport_OUTPUT + 1, HIDReport_VARIABLE, 00255 \endcode 00256 00257 Since the previous report only contains 3 bits, the data must be padded to a 00258 multiple of one byte. This is done by using constant Output data, as follows: 00259 \code 00260 // Output report: padding 00261 HIDReport_GLOBAL_REPORTCOUNT + 1, 1, 00262 HIDReport_GLOBAL_REPORTSIZE + 1, 5, 00263 HIDReport_OUTPUT + 1, HIDReport_CONSTANT, 00264 \endcode 00265 00266 The last item, <i>End Collection</i>, is necessary to close the previously opened 00267 <i>Application Collection</i>. 00268 \code 00269 HIDReport_ENDCOLLECTION 00270 }; 00271 \endcode 00272 00273 The Input and Output reports defined by this descriptor can be modeled by the 00274 following structures: 00275 \code 00276 // HID Input Report 00277 typedef struct { 00278 00279 // State of modifier keys. 00280 unsigned char bmModifierKeys:8; 00281 // Key codes of pressed keys. 00282 unsigned char pressedKeys[HIDDKeyboardInputReport_MAXKEYPRESSES]; 00283 00284 } __attribute__ ((packed)) HIDDKeyboardInputReport; // GCC 00285 // HID Output Report 00286 typedef struct { 00287 00288 unsigned char numLockStatus:1, // State of the num. lock LED. 00289 capsLockStatus:1, // State of the caps lock LED. 00290 scrollLockStatus:1, // State of the scroll lock LED. 00291 padding:5; // Padding bits. 00292 00293 } __attribute__ ((packed)) HIDDKeyboardOutputReport; // GCC 00294 \endcode 00295 00296 An instance of each one of the reports is stored in a HIDDKeyboardDriver 00297 structure, which holds the standard class driver and HID keyboard-specific 00298 data. 00299 00300 \subsection hid_phy_desc Physical Descriptor 00301 A Physical descriptor is useless for a keyboard device, so none are defined 00302 in this example. 00303 00304 \subsection endp_desc Endpoint Descriptor 00305 Following the Interface and HID-specific descriptors, the two necessary 00306 endpoints are defined. 00307 \code 00308 // Interrupt IN endpoint descriptor 00309 { 00310 sizeof(USBEndpointDescriptor), 00311 USBGenericDescriptor_ENDPOINT, 00312 USBEndpointDescriptor_ADDRESS( 00313 USBEndpointDescriptor_IN, 00314 HIDDKeyboardDriverDescriptors_INTERRUPTIN), 00315 USBEndpointDescriptor_INTERRUPT, 00316 sizeof(HIDDKeyboardInputReport), 00317 HIDDKeyboardDriverDescriptors_INTERRUPTIN_POLLING 00318 }, 00319 // Interrupt OUT endpoint descriptor 00320 { 00321 sizeof(USBEndpointDescriptor), 00322 USBGenericDescriptor_ENDPOINT, 00323 USBEndpointDescriptor_ADDRESS( 00324 USBEndpointDescriptor_OUT, 00325 HIDDKeyboardDriverDescriptors_INTERRUPTOUT), 00326 USBEndpointDescriptor_INTERRUPT, 00327 sizeof(HIDDKeyboardOutputReport), 00328 HIDDKeyboardDriverDescriptors_INTERRUPTIN_POLLING 00329 } 00330 \endcode 00331 00332 \subsection str_desc String Descriptors 00333 Please refer to \ref usbd_id_str "Usage: USBD VID, PID & Strings". 00334 00335 \section class_spec_req Class-specific requests 00336 A driver request handler should first differentiate between class-specific and 00337 standard requests using the corresponding bits in the <i>bmRequestType</i> field. 00338 In most cases, standard requests can be immediately forwarded to the standard 00339 request handler method; class-specific methods must be decoded and treated by 00340 the custom handler. 00341 00342 \subsection GetDescriptor 00343 Three values have been added by the HID specification for the <b>GET_DESCRIPTOR</b> 00344 request. The high byte of the <i>wValue</i> field contains the type of the 00345 requested descriptor; in addition to the standard types, the HID specification 00346 adds the <b>HID descriptor</b> (21h), the <b>Report descriptor</b> 00347 (22h) and the <b>Physical descriptor</b> (23h) types. 00348 00349 There is no particular action to perform besides sending the descriptor. This 00350 can be done by using the USBD_Write() method, after the requested descriptor has 00351 been identified: 00352 \code 00353 switch (USBGenericRequest_GetRequest(request)) { 00354 00355 case USBGenericRequest_GETDESCRIPTOR: 00356 // Check if this is a HID descriptor, 00357 // otherwise forward it to 00358 // the standard driver 00359 if (!HIDDKeyboardDriver_GetDescriptor( 00360 USBGetDescriptorRequest_GetDescriptorType(request), 00361 USBGenericRequest_GetLength(request))) { 00362 00363 USBDDriver_RequestHandler(&(hiddKeyboardDriver.usbdDriver), 00364 request); 00365 } 00366 break; 00367 00368 default: 00369 USBDDriver_RequestHandler(&(hiddKeyboardDriver.usbdDriver), 00370 request); 00371 } 00372 \endcode 00373 A slight complexity of the GET_DESCRIPTOR and SET_DESCRIPTOR requests is that 00374 those are standard requests, but the standard request handler 00375 (USBDDriver_RequestHandler()) must not always be called to treat them (since 00376 they may refer to HID descriptors). The solution is to first identify 00377 GET/SET_DESCRIPTOR requests, treat the HID-specific cases and, finally, 00378 forward any other request to the standard handler. 00379 00380 In this case, a GET_DESCRIPTOR request for the Physical descriptor is first 00381 forwarded to the standard handler, and STALLed there because it is not 00382 recognized. This is done because the device does not have any Physical 00383 descriptors, and thus, does not need to handle the associated request. 00384 00385 \subsection SetDescriptor 00386 This request is optional and is never issued by most hosts. It is not 00387 implemented in this example. 00388 00389 \subsection GetReport 00390 Since the HID keyboard defines two different reports, the Report Type value 00391 specified by this request (upper byte of the <i>wValue</i> field) must be examined 00392 to decide which report to send. If the type value is 01h, then the Input 00393 report must be returned; if it is 02h, the Output report is requested: 00394 \code 00395 case HIDGenericRequest_GETREPORT: 00396 //------------------------------- 00397 type = HIDReportRequest_GetReportType(request); 00398 length = USBGenericRequest_GetLength(request); 00399 switch (type) { 00400 00401 case HIDReportRequest_INPUT: 00402 00403 // Adjust size and send report 00404 if (length > sizeof(HIDDKeyboardInputReport)) { 00405 00406 length = sizeof(HIDDKeyboardInputReport); 00407 } 00408 USBD_Write(0, // Endpoint #0 00409 &(hiddKeyboardDriver.inputReport), 00410 length, 00411 0, // No callback 00412 0); 00413 break; 00414 00415 case HIDReportRequest_OUTPUT: 00416 00417 // Adjust size and send report 00418 if (length > sizeof(HIDDKeyboardOutputReport)) { 00419 00420 length = sizeof(HIDDKeyboardOutputReport); 00421 } 00422 USBD_Write(0, // Endpoint #0 00423 &(hiddKeyboardDriver.outputReport), 00424 length, 00425 0, // No callback 00426 0); 00427 break; 00428 00429 default: 00430 USBD_Stall(0); 00431 } 00432 break; 00433 \endcode 00434 00435 \subsection SetReport 00436 For an HID keyboard, the <b>SET_REPORT</b> command can be sent by the host to 00437 change the state of the LEDs. Normally, the dedicated Interrupt OUT endpoint 00438 will be used for this; but in some cases, using the default Control endpoint 00439 can save some bandwidth on the host side. 00440 00441 Note that the SET_REPORT request can be directed at the Input report of the 00442 keyboard; in this case, it can be safely discarded, according to the HID 00443 specification. Normally, most host drivers only target the Output report. The 00444 Report Type value is stored in the upper byte of the <i>wValue</i> field. 00445 00446 The length of the data phase to follow is stored in the <i>wLength</i> field of the 00447 request. It should be equal to the total length of the Output report. If it is 00448 different, the report status must still be updated with the received data as 00449 best as possible. 00450 00451 When the reception of the new data is completed, some processing must be done 00452 to enable/disable the corresponding LEDs. This is done in the callback 00453 function passed as an argument to USBD_Read(): 00454 \code 00455 case HIDGenericRequest_SETREPORT: 00456 //------------------------------- 00457 type = HIDReportRequest_GetReportType(request); 00458 length = USBGenericRequest_GetLength(request); 00459 switch(type) { 00460 00461 case HIDReportRequest_INPUT: 00462 // SET_REPORT requests on input reports are ignored 00463 USBD_Stall(0); 00464 break; 00465 00466 case HIDReportRequest_OUTPUT: 00467 // Check report length 00468 if (length != sizeof(HIDDKeyboardOutputReport)) { 00469 00470 USBD_Stall(0); 00471 } 00472 else { 00473 00474 USBD_Read(0, // Endpoint #0 00475 &(hiddKeyboardDriver.outputReport), 00476 length, 00477 (TransferCallback) HIDDKeyboardDriver_ReportReceived, 00478 0); // No argument to the callback function 00479 } 00480 break; 00481 00482 default: 00483 USBD_Stall(0); 00484 } 00485 break; 00486 \endcode 00487 00488 \subsection SetIdle 00489 In this case study, the <b>SET_IDLE</b> request is used to set a delay before a key 00490 is repeated. This is common behavior on keyboard devices. Usually, this delay 00491 is set to about 500 ms by the host. 00492 00493 The only action here is to store the new Idle rate. The management of this 00494 setting must be done in the main function, since Interrupt IN reports are sent 00495 from there. 00496 00497 In practice, it is not necessary to perform any action, apart from sending a 00498 zero-length packet to acknowledge it. The main application however has to make 00499 sure that only new reports are sent by the device. 00500 \code 00501 case HIDGenericRequest_SETIDLE: 00502 //----------------------------- 00503 hiddKeyboardDriver.inputReportIdleRate = 00504 HIDIdleRequest_GetIdleRate(request); 00505 USBD_Write(0, 0, 0, 0, 0); 00506 break; 00507 \endcode 00508 00509 \subsection GetIdle 00510 The only necessary operation for this request is to send the previously saved 00511 Idle rate. This is done by calling the USBD_Write method with the one-byte 00512 variable as its parameter: 00513 \code 00514 case HIDGenericRequest_GETIDLE: 00515 //----------------------------- 00516 USBD_Write(0, &(hiddKeyboardDriver.inputReportIdleRate), 1, 0, 0); 00517 break; 00518 \endcode 00519 00520 \subsection get_set_prot GetProtocol, SetProtocol 00521 This HID keyboard example does not support the Boot protocol, so there is no 00522 need to implement the SET_PROTOCOL and GET_PROTOCOL requests. This means they 00523 can be safely STALLed when received. 00524 00525 \section main_app Main Application 00526 Like the mouse example, the main program must perform two different 00527 operations. First, it has to monitor the physical inputs used as keys. In the 00528 example software, the buttons present on the evaluation boards are used to 00529 produce several modifier and alphanumeric keys. 00530 00531 Also, the main program is in charge of sending reports as they are modified, 00532 taking into account the Idle rate specified by the host. Idle rate management 00533 can be carried out by firing/resetting a timer once a new report is sent; if 00534 the timer expires, this means the Input report has not changed since. 00535 According to the HID specification, a single instance of the report must be 00536 sent in this case. 00537 00538 Finally, the HID specification also defines that if too many keys are pressed 00539 at the same time, the device should report an <i>ErrorRollOver</i> usage value 00540 (01h) in every byte of the key array. This has to be handled by the main 00541 application as well. 00542 00543 */ 00544 00545 /** 00546 \page usbd_hid_mouse_drv USB Device HID Mouse Driver 00547 This page describes how to implement a mouse device using the HID class and 00548 the \ref usbd_framework. Details about the USB and the HID class can 00549 be found in the <i>USB specification 2.0</i> and the <i>HID specification 1.11</i> 00550 documents, respectively. 00551 00552 \section References 00553 - \ref usbd_framework 00554 - \ref usbd_enum 00555 - <a href="http://www.usb.org/developers/docs/usb_20_040908.zip"> 00556 Universal Serial Bus Revision 2.0 specification 00557 </a> (.zip file format, size 9.80 MB) 00558 - <a href="http://www.usb.org/developers/devclass_docs/HID1_11.pdf"> 00559 Device Class Definition for HID 1.11</a> 00560 - <a href="http://www.usb.org/developers/devclass_docs/Hut1_12.pdf"> 00561 HID Usage Tables 1.12</a> 00562 00563 00564 00565 */ 00566 00567 /** 00568 \page usb_hid_basic USB HID Basic 00569 00570 This page gives generic details on the HID class, including its purpose, 00571 architecture and how it is supported by various operating systems. 00572 00573 \section Purpose 00574 00575 The HID class has been specifically designed for Human Interface Devices, 00576 i.e., devices which are manipulated by humans to control a computer or an 00577 electronic device. This includes common peripherals such as a keyboard, a 00578 mouse or a joystick, as well as many other interfaces: remote controllers, 00579 switches, buttons, dedicated game controls, and so on. 00580 00581 It is also possible to use the HID class for devices which do not require 00582 human interaction, but still deliver information in a similar format. For 00583 example, devices like a thermometer or a battery indicator are supported. 00584 00585 In addition, the HID class also makes it possible to not only receive data 00586 from devices but also to send commands to them. Indeed, many devices offer 00587 some kind of display to give back information to the user, e.g., the LEDs on a 00588 keyboard. 00589 00590 Finally, since it is quite simple to send and receive data using the HID 00591 class, it can be used as a generic means of communication between a device 00592 and a host. This is made possible because of the very flexible framework 00593 defined in the HID specification. 00594 00595 In this document, three uses of the HID class will be detailed step-by-step, 00596 each showing one particular feature of the class. The first example shows the 00597 interaction with a simple mouse. In the second example, a keyboard is 00598 implemented to demonstrate the possibility to send data to a peripheral. The 00599 last example explains how to use HID as a simple two-way communication 00600 channel. 00601 00602 \section Architecture 00603 00604 \subsection Interface 00605 An HID device only needs <b>one interface descriptor</b>. It should have the HID 00606 interface class code in its bInterfaceClass field. There are special subclass 00607 and protocol codes to specify if the HID device is a mouse or a keyboard, and 00608 must be supported by the BIOS. In such a case, the interface must be declared 00609 as a Boot Interface, and the type of the device (mouse or keyboard) must be 00610 given in the bInterfaceProtocol field. 00611 00612 \subsection Endpoints 00613 Up to three endpoints can be used with an HID interface. The first two are the 00614 default Control endpoint 0, as well as an Interrupt IN endpoint. They are 00615 mandatory and shall always be declared. An optional Interrupt OUT endpoint can 00616 be added as well. 00617 00618 Endpoint 0 is used for class-specific requests, as well as receiving data from 00619 the host if no Interrupt OUT endpoint has been defined. In addition, the host 00620 can also explicitly request or send report data through this endpoint. 00621 00622 The Interrupt IN and OUT pipes are used for sending asynchronous data to the 00623 host, and to receive low-latency information. 00624 00625 \image html HIDClassArch.png "HID Class Driver Architecture" 00626 00627 \subsection class_spec_desc Class-Specific Descriptors 00628 There are three class-specific descriptors defined in the <i>HID specification 00629 1.11</i>: the HID descriptor, the report descriptor and the physical descriptor. 00630 00631 \subsubsection hid_descr HID Descriptor 00632 The HID descriptor gives information about the HID specification revision 00633 used, the country for which a device is localized, and lists the number of 00634 class-specific descriptors, including their length and type. 00635 00636 HID Descriptor Format 00637 00638 \if doxys_table 00639 ||Field||Size(bytes)||Description 00640 |bLength|1|Total length of the HID descriptor 00641 |bDescriptorType|1|HID descriptor type (21h) 00642 |bcdHID|2|HID specification release number in BCD format 00643 |bCountryCode|1|Code of the country for which the device is located.\n 00644 Should be 0 if the device is not localized. 00645 |bNumDescriptors|1|Number of class-specific descriptors used by the device. 00646 |bDescriptorType|1|Type of the first class-specific descriptor. 00647 |bDescriptorLength|1|Total length of the first class-specific descriptor. 00648 |[bDescriptorType]|1|Type of the second class-specific descriptor. 00649 |[bDescriptorLength]|1|Total length of the second class-specific descriptor. 00650 |...| | 00651 \endif 00652 00653 <table><tr> 00654 <td><b>Field</b></td> 00655 <td><b>Size(bytes)</b></td> 00656 <td><b>Description</b></td></tr> 00657 <tr> 00658 <td>bLength</td> 00659 <td>1</td> 00660 <td>Total length of the HID descriptor</td></tr> 00661 <tr> 00662 <td>bDescriptorType</td> 00663 <td>1</td> 00664 <td>HID descriptor type (21h)</td></tr> 00665 <tr> 00666 <td>bcdHID</td> 00667 <td>2</td> 00668 <td>HID specification release number in BCD format</td></tr> 00669 <tr> 00670 <td>bCountryCode</td> 00671 <td>1</td> 00672 <td>Code of the country for which the device is located.<br>Should be 0 if the device is not localized.</td></tr> 00673 <tr> 00674 <td>bNumDescriptors</td> 00675 <td>1</td> 00676 <td>Number of class-specific descriptors used by the device.</td></tr> 00677 <tr> 00678 <td>bDescriptorType</td> 00679 <td>1</td> 00680 <td>Type of the first class-specific descriptor.</td></tr> 00681 <tr> 00682 <td>bDescriptorLength</td> 00683 <td>1</td> 00684 <td>Total length of the first class-specific descriptor.</td></tr> 00685 <tr> 00686 <td>[bDescriptorType]</td> 00687 <td>1</td> 00688 <td>Type of the second class-specific descriptor.</td></tr> 00689 <tr> 00690 <td>[bDescriptorLength]</td> 00691 <td>1</td> 00692 <td>Total length of the second class-specific descriptor.</td></tr> 00693 <tr> 00694 <td>...</td> 00695 <td> </td> 00696 <td> </td></tr> 00697 </table> 00698 00699 There is always at least one Report descriptor for an HID device, so the 00700 corresponding fields must be present in the HID descriptor. If other 00701 descriptors are defined, they must also be described here. 00702 00703 \subsubsection hid_rep_descr Report Descriptor 00704 A HID device must have at least one <b>Report descriptor</b>. It defines the type 00705 of data manipulated by the device, which is referred to as report. When the 00706 device wants to notify that the cursor has moved, for example, it sends the 00707 corresponding report in the format previously defined in the Report 00708 descriptor. 00709 00710 This descriptor is quite different from others, as it does not have a fixed 00711 table of values. Instead, it is made up of a variable number of items, which 00712 collectively identify the information that a host can expect from or send to 00713 the device. 00714 00715 There are five categories of items: 00716 - <b>Input</b> items, which define the format and type of the data sent by the 00717 device. 00718 - <b>Output</b> items, which define the format and type of the data expected by 00719 the device 00720 - <b>Feature</b> items, which define data sent to or received from the device, 00721 and not intended for the end user, such as configuration parameters. 00722 - <b>Collection</b> items, which identify a set of data as related to the same 00723 group. 00724 - <b>End Collection</b> items, which close other Collection items. 00725 00726 Usually, a Report descriptor defines only one use (report) for a device, e.g., 00727 a mouse. However, it is possible to declare several reports to perform 00728 different tasks, e.g., mouse & keyboard. This is done by assigning a different 00729 <b>Report ID</b> to each report; this makes it possible for the device to send 00730 both reports through the same Interrupt endpoint, while still permitting the 00731 host to correctly identify the data. Using only a single endpoint for several 00732 functionalities is very powerful, as the remaining ones can then be used by 00733 other interfaces (CDC, MSD, etc.) for an even more versatile device. 00734 00735 More details about Report descriptors will be given in the implementation 00736 examples. For more information about the possible items, tags and values, 00737 please refer to the <i>HID specification 1.11.</i> 00738 00739 \subsubsection hid_phy_descr Physical Descriptor 00740 A <b>Physical descriptor</b> can be used to give information about which human body 00741 part is used to activate a particular control. While this is a useless piece 00742 of information for most devices, it can be relevant for complex devices which 00743 provide many similar controls. In such a case, a Physical descriptor allows an 00744 application to assign its functionalities more appropriately; for example, a 00745 game controller often has a large number of buttons, with some of them more 00746 accessible than the others. Those buttons would be assigned the most useful 00747 actions. 00748 00749 Since physical descriptors are not used very often, and are not useful in the 00750 case studies described in this document, they will not be discussed further. 00751 00752 \subsection class_spec_req Class-specific Requests 00753 00754 \subsubsection GetDescriptor 00755 While <b>GET_DESCRIPTOR</b> is a standard request (defined in the }USB 00756 specification 2.0}), new descriptor type values have been added for the HID 00757 class. They make it possible for the host to request the HID descriptor, 00758 Report descriptor and Physical descriptors used by the device. 00759 00760 When requesting a HID-specific descriptor, the <i>wIndex</i> field of the request 00761 must be set to the HID interface number. For standard requests, this field is 00762 either set to 0 or, for String descriptors, to the index of the language ID 00763 used. 00764 00765 \subsubsection SetDescriptor 00766 Similarly, <b>SET_DESCRIPTOR</b> is a standard request with added HID-specific 00767 values. It is used by the host to change the HID descriptors of a device. 00768 This is an optional request, and has few practical uses. 00769 00770 \subsubsection GetReport 00771 The host can explicitly ask the device for a report by using the <b>GET_REPORT</b> 00772 request. However, it should be used primarily to get the state of feature 00773 items and absolute values at initialization time, not for consistent device 00774 polling. 00775 00776 The requested report is identified either by its Report ID (if they are used), 00777 and/or by its type (Input, Output or Feature). 00778 00779 Please note that a GET_REPORT request is different from a GET_DESCRIPTOR 00780 request for the Report descriptor. The latter returns the whole Report 00781 descriptor, i.e., all the items declared. The former returns the data defined 00782 by this descriptor. 00783 00784 \subsubsection SetReport 00785 <b>SET_REPORT</b> is similar to GET_REPORT, except this request is used for 00786 changing the state of a report, instead of simply retrieving it. 00787 00788 For an Input report, this request can either be considered meaningless, or can 00789 be used to reset the current status of a control. For example, it could be 00790 used to calibrate the neutral position of a joystick. 00791 00792 \subsubsection SetIdle 00793 This request is used to specify the minimum amount of time, called <b>Idle rate</b>, 00794 that a device must wait before transmitting a report if its state has 00795 not changed. This means the device must NAK all polls on its Interrupt IN 00796 endpoint until the report state changes, or the guarding period expires. 00797 00798 The SET_IDLE command can either be issued for a particular duration, or for an 00799 undefined period of time. The upper byte of the wValue field is used to 00800 specify this duration. In addition, if the device generates multiple reports, 00801 the Report ID of the target report to affect can be specified in the lower 00802 byte. 00803 00804 In practice, this request is often used with a keyboard to put a small delay 00805 before a key is repeated continuously. For a mouse, it must be set to 0, 00806 meaning that the device should never report an unchanged state. 00807 00808 \subsubsection GetIdle 00809 The GET_IDLE request is issued by the host to retrieve the current Idle rate 00810 of the device. A particular Report can be specified with its Report ID. 00811 00812 \subsubsection GetProtocol 00813 This request returns the protocol currently used by the device. This can 00814 either be the Report protocol (}wValue} set to 0) or the Boot protocol 00815 (}wValue} set to 1). Since a device supporting the Boot protocol can operate 00816 differently depending on which mode it is in, the host system can retrieve or 00817 change this mode with the GET_PROTOCOL and SET_PROTOCOL requests. 00818 00819 This request is only need for devices supporting the Boot protocol. 00820 00821 \subsubsection SetProtocol 00822 Whenever an HID device starts up, it should use the Report protocol by 00823 default. However, the host driver shall still use the SET_PROTOCOL 00824 request to specify if the device should use the Report protocol or the 00825 Boot protocol. 00826 00827 \section host_drv Host Drivers 00828 Most operating systems provide a generic HID driver which automatically 00829 handles standard devices, such as keyboard, mice and joystick. In addition, 00830 the driver can also be used by the application to easily access custom and 00831 vendor-specific devices. 00832 00833 */