SAMV71 Xplained Ultra Software Package 1.5

hid-transfer.dir

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 */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines