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-transfer 00032 * 00033 * \section Purpose 00034 * 00035 * This directory provides definitions, structs and functions for a USB HID 00036 * device - USB HID Transfer driver, to implement an USB HID compatible 00037 * device for customized data transmitting. 00038 * 00039 * \section Contents 00040 * 00041 * There are three things for the implement of the USB HID Transfer driver: 00042 * - Implement the USB HID driver structs and functions for the device, 00043 * to initialize, to handle HID-specific requests and dispach 00044 * standard requests in USBD callbacks, to read/write through assigned USB 00045 * endpoints, 00046 * - Create the HID Transfer device's descriptors that should be passed to 00047 * the USBDDriver instance on initialization, so that the host can 00048 * recognize the device as a USB Transfer device. 00049 * - Implement methods to read/write data through interrupt endpoints, so that 00050 * host and device can exchange data. 00051 * 00052 * For more information about what a particular group contains, please refer to 00053 * "USB HID Transfer". 00054 */ 00055 00056 /** 00057 \page usbd_hid_xfr_drv USB Device HID %Transfer Driver 00058 This page describes how to use the \ref usbd_framework to produce a USB 00059 HID %Transfer driver, which appears as a USB HID complient device 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_basic HID Basic 00076 See \ref usb_hid_basic "USB HID Basic". 00077 00078 \section Architecture 00079 See \ref usbd_framework_arch "USB Device Framework Architecture". 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 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 \ref 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_rep_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 + 2, 0xFF, 0xFF, // Vendor-defined 00187 HIDReport_LOCAL_USAGE + 1, 0xFF, // Vendor-defined 00188 \endcode 00189 00190 An Application collection is then defined to group the reports together: 00191 \code 00192 HIDReport_COLLECTION + 1, HIDReport_COLLECTION_APPLICATION, 00193 \endcode 00194 00195 The first report to be defined is the input report, all data in the buffer 00196 is vendor defined: 00197 \code 00198 // Input report: Vendor-defined 00199 HIDReport_LOCAL_USAGE + 1, 0xFF, // Vendor-defined usage 00200 HIDReport_GLOBAL_REPORTCOUNT + 1, HIDDTransferDriver_REPORTSIZE, 00201 HIDReport_GLOBAL_REPORTSIZE + 1, 8, 00202 HIDReport_GLOBAL_LOGICALMINIMUM + 1, (unsigned char) -128, 00203 HIDReport_GLOBAL_LOGICALMAXIMUM + 1, (unsigned char) 127, 00204 HIDReport_INPUT + 1, 0, // No Modifiers 00205 \endcode 00206 00207 The output report is then defined, data is for the user to decode: 00208 \code 00209 // Output report: vendor-defined 00210 HIDReport_LOCAL_USAGE + 1, 0xFF, // Vendor-defined usage 00211 HIDReport_GLOBAL_REPORTCOUNT + 1, HIDDTransferDriver_REPORTSIZE, 00212 HIDReport_GLOBAL_REPORTSIZE + 1, 8, 00213 HIDReport_GLOBAL_LOGICALMINIMUM + 1, (unsigned char) -128, 00214 HIDReport_GLOBAL_LOGICALMAXIMUM + 1, (unsigned char) 127, 00215 HIDReport_OUTPUT + 1, 0, // No Modifiers 00216 \endcode 00217 00218 The last item, <i>End Collection</i>, is necessary to close the previously opened 00219 <i>Application Collection</i>. 00220 \code 00221 HIDReport_ENDCOLLECTION 00222 }; 00223 \endcode 00224 00225 The input report and output report are all user defined. We define the first 00226 byte as bit map of push buttons and LEDs, remaining bytes as data. 00227 00228 \subsection hid_phy_desc Physical Descriptor 00229 A Physical descriptor is useless for a general transfer device, so none is 00230 defined in this example. 00231 00232 \subsection hid_ep_desc Endpoint Descriptor 00233 Following the Interface and HID-specific descriptors, the two necessary 00234 endpoints are defined. 00235 \code 00236 // Interrupt IN endpoint descriptor 00237 { 00238 sizeof(USBEndpointDescriptor), 00239 USBGenericDescriptor_ENDPOINT, 00240 USBEndpointDescriptor_ADDRESS( 00241 USBEndpointDescriptor_IN, 00242 HIDDKeyboardDriverDescriptors_INTERRUPTIN), 00243 USBEndpointDescriptor_INTERRUPT, 00244 sizeof(HIDDKeyboardInputReport), 00245 HIDDKeyboardDriverDescriptors_INTERRUPTIN_POLLING 00246 }, 00247 // Interrupt OUT endpoint descriptor 00248 { 00249 sizeof(USBEndpointDescriptor), 00250 USBGenericDescriptor_ENDPOINT, 00251 USBEndpointDescriptor_ADDRESS( 00252 USBEndpointDescriptor_OUT, 00253 HIDDKeyboardDriverDescriptors_INTERRUPTOUT), 00254 USBEndpointDescriptor_INTERRUPT, 00255 sizeof(HIDDKeyboardOutputReport), 00256 HIDDKeyboardDriverDescriptors_INTERRUPTIN_POLLING 00257 } 00258 \endcode 00259 00260 \subsection hid_str_desc String Descriptors 00261 Please refer to \ref usbd_id_str "Usage: USBD VID, PID & Strings". 00262 00263 \section class_spec_req Class-specific requests 00264 A driver request handler should first differentiate between class-specific and 00265 standard requests using the corresponding bits in the <i>bmRequestType</i> field. 00266 In most cases, standard requests can be immediately forwarded to the standard 00267 request handler method; class-specific methods must be decoded and treated by 00268 the custom handler. 00269 00270 \subsection GetDescriptor 00271 Three values have been added by the HID specification for the <b>GET_DESCRIPTOR</b> 00272 request. The high byte of the <i>wValue</i> field contains the type of the 00273 requested descriptor; in addition to the standard types, the <b>HID specification</b> 00274 adds the <b>HID descriptor</b> (21h), the <b>Report descriptor</b> 00275 (22h) and the <b>Physical descriptor</b> (23h) types. 00276 00277 There is no particular action to perform besides sending the descriptor. This 00278 can be done by using the USBD_Write() method, after the requested descriptor has 00279 been identified: 00280 \code 00281 switch (USBGenericRequest_GetRequest(request)) { 00282 00283 case USBGenericRequest_GETDESCRIPTOR: 00284 // Check if this is a HID descriptor, 00285 // otherwise forward it to 00286 // the standard driver 00287 if (!HIDDKeyboardDriver_GetDescriptor( 00288 USBGetDescriptorRequest_GetDescriptorType(request), 00289 USBGenericRequest_GetLength(request))) { 00290 00291 USBDDriver_RequestHandler(&(hiddKeyboardDriver.usbdDriver), 00292 request); 00293 } 00294 break; 00295 00296 default: 00297 USBDDriver_RequestHandler(&(hiddKeyboardDriver.usbdDriver), 00298 request); 00299 } 00300 \endcode 00301 A slight complexity of the GET_DESCRIPTOR and SET_DESCRIPTOR requests is that 00302 those are standard requests, but the standard request handler 00303 (USBDDriver_RequestHandler()) must not always be called to treat them (since 00304 they may refer to HID descriptors). The solution is to first identify 00305 GET/SET_DESCRIPTOR requests, treat the HID-specific cases and, finally, 00306 forward any other request to the standard handler. 00307 00308 In this case, a GET_DESCRIPTOR request for the Physical descriptor is first 00309 forwarded to the standard handler, and STALLed there because it is not 00310 recognized. This is done because the device does not have any Physical 00311 descriptors, and thus, does not need to handle the associated request. 00312 00313 \subsection SetDescriptor 00314 This request is optional and is never issued by most hosts. It is not 00315 implemented in this example. 00316 00317 \subsection GetReport 00318 Since the HID keyboard defines two different reports, the Report Type value 00319 specified by this request (upper byte of the <i>wValue</i> field) must be examined 00320 to decide which report to send. If the type value is 01h, then the Input 00321 report must be returned; if it is 02h, the Output report is requested: 00322 \code 00323 case HIDGenericRequest_GETREPORT: 00324 //------------------------------- 00325 type = HIDReportRequest_GetReportType(request); 00326 length = USBGenericRequest_GetLength(request); 00327 switch (type) { 00328 00329 case HIDReportRequest_INPUT: 00330 00331 // Adjust size and send report 00332 if (length > sizeof(HIDDKeyboardInputReport)) { 00333 00334 length = sizeof(HIDDKeyboardInputReport); 00335 } 00336 USBD_Write(0, // Endpoint #0 00337 &(hiddKeyboardDriver.inputReport), 00338 length, 00339 0, // No callback 00340 0); 00341 break; 00342 00343 case HIDReportRequest_OUTPUT: 00344 00345 // Adjust size and send report 00346 if (length > sizeof(HIDDKeyboardOutputReport)) { 00347 00348 length = sizeof(HIDDKeyboardOutputReport); 00349 } 00350 USBD_Write(0, // Endpoint #0 00351 &(hiddKeyboardDriver.outputReport), 00352 length, 00353 0, // No callback 00354 0); 00355 break; 00356 00357 default: 00358 USBD_Stall(0); 00359 } 00360 break; 00361 \endcode 00362 00363 \subsection SetReport 00364 For an HID keyboard, the <b>SET_REPORT</b> command can be sent by the host to 00365 change the state of the LEDs. Normally, the dedicated Interrupt OUT endpoint 00366 will be used for this; but in some cases, using the default Control endpoint 00367 can save some bandwidth on the host side. 00368 00369 Note that the SET_REPORT request can be directed at the Input report of the 00370 keyboard; in this case, it can be safely discarded, according to the HID 00371 specification. Normally, most host drivers only target the Output report. The 00372 Report Type value is stored in the upper byte of the <i>wValue</i> field. 00373 00374 The length of the data phase to follow is stored in the <i>wLength</i> field of the 00375 request. It should be equal to the total length of the Output report. If it is 00376 different, the report status must still be updated with the received data as 00377 best as possible. 00378 00379 When the reception of the new data is completed, some processing must be done 00380 to enable/disable the corresponding LEDs. This is done in the callback 00381 function passed as an argument to USBD_Read(): 00382 \code 00383 case HIDGenericRequest_SETREPORT: 00384 //------------------------------- 00385 type = HIDReportRequest_GetReportType(request); 00386 length = USBGenericRequest_GetLength(request); 00387 switch(type) { 00388 00389 case HIDReportRequest_INPUT: 00390 // SET_REPORT requests on input reports are ignored 00391 USBD_Stall(0); 00392 break; 00393 00394 case HIDReportRequest_OUTPUT: 00395 // Check report length 00396 if (length != sizeof(HIDDKeyboardOutputReport)) { 00397 00398 USBD_Stall(0); 00399 } 00400 else { 00401 00402 USBD_Read(0, // Endpoint #0 00403 &(hiddKeyboardDriver.outputReport), 00404 length, 00405 (TransferCallback) HIDDKeyboardDriver_ReportReceived, 00406 0); // No argument to the callback function 00407 } 00408 break; 00409 00410 default: 00411 USBD_Stall(0); 00412 } 00413 break; 00414 \endcode 00415 00416 \subsection SetIdle 00417 In this case study, the <b>SET_IDLE</b> request is used to set a delay before a key 00418 is repeated. This is common behavior on keyboard devices. Usually, this delay 00419 is set to about 500 ms by the host. 00420 00421 The only action here is to store the new Idle rate. The management of this 00422 setting must be done in the main function, since Interrupt IN reports are sent 00423 from there. 00424 00425 In practice, it is not necessary to perform any action, apart from sending a 00426 zero-length packet to acknowledge it. The main application however has to make 00427 sure that only new reports are sent by the device. 00428 \code 00429 case HIDGenericRequest_SETIDLE: 00430 //----------------------------- 00431 hiddKeyboardDriver.inputReportIdleRate = 00432 HIDIdleRequest_GetIdleRate(request); 00433 USBD_Write(0, 0, 0, 0, 0); 00434 break; 00435 \endcode 00436 00437 \subsection GetIdle 00438 The only necessary operation for this request is to send the previously saved 00439 Idle rate. This is done by calling the USBD_Write method with the one-byte 00440 variable as its parameter: 00441 \code 00442 case HIDGenericRequest_GETIDLE: 00443 //----------------------------- 00444 USBD_Write(0, &(hiddKeyboardDriver.inputReportIdleRate), 1, 0, 0); 00445 break; 00446 \endcode 00447 00448 \subsection get_set_prot GetProtocol, SetProtocol 00449 This HID keyboard example does not support the Boot protocol, so there is no 00450 need to implement the SET_PROTOCOL and GET_PROTOCOL requests. This means they 00451 can be safely STALLed when received. 00452 00453 \section main_app Main Application 00454 Like the mouse example, the main program must perform two different 00455 operations. First, it has to monitor the physical inputs used as keys. In the 00456 example software, the buttons present on the evaluation boards are used to 00457 produce several modifier and alphanumeric keys. 00458 00459 Also, the main program is in charge of sending reports as they are modified, 00460 taking into account the Idle rate specified by the host. Idle rate management 00461 can be carried out by firing/resetting a timer once a new report is sent; if 00462 the timer expires, this means the Input report has not changed since. 00463 According to the HID specification, a single instance of the report must be 00464 sent in this case. 00465 00466 Finally, the HID specification also defines that if too many keys are pressed 00467 at the same time, the device should report an <i>ErrorRollOver</i> usage value 00468 (01h) in every byte of the key array. This has to be handled by the main 00469 application as well. 00470 00471 */