API tools faq
paste
Advertisement
Guest User

usb_function_hid.h

a guest
May 17th, 2012
157
0
Never
Add comment
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
C 12.66 KB | None | 0 0
raw download clone embed print report
  1. /*******************************************************************************
  2.   File Information:
  3.     FileName:       usb_function_hid.h
  4.     Dependencies:   See INCLUDES section
  5.     Processor:      PIC18 or PIC24 USB Microcontrollers
  6.     Hardware:       The code is natively intended to be used on the following
  7.                     hardware platforms: PICDEM™ FS USB Demo Board,
  8.                     PIC18F87J50 FS USB Plug-In Module, or
  9.                     Explorer 16 + PIC24 USB PIM.  The firmware may be
  10.                     modified for use on other USB platforms by editing the
  11.                     HardwareProfile.h file.
  12.     Complier:   Microchip C18 (for PIC18) or C30 (for PIC24)
  13.     Company:        Microchip Technology, Inc.
  14.    
  15.     Software License Agreement:
  16.    
  17.     The software supplied herewith by Microchip Technology Incorporated
  18.     (the “Company”) for its PIC® Microcontroller is intended and
  19.     supplied to you, the Company’s customer, for use solely and
  20.     exclusively on Microchip PIC Microcontroller products. The
  21.     software is owned by the Company and/or its supplier, and is
  22.     protected under applicable copyright laws. All rights are reserved.
  23.     Any use in violation of the foregoing restrictions may subject the
  24.     user to criminal sanctions under applicable laws, as well as to
  25.     civil liability for the breach of the terms and conditions of this
  26.     license.
  27.    
  28.     THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
  29.     WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
  30.     TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  31.     PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
  32.     IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
  33.     CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
  34.    
  35.     Change History:
  36.      Rev   Date         Description
  37.      1.0   11/19/2004   Initial release
  38.      2.1   02/26/2007   Updated for simplicity and to use common
  39.                      coding style
  40.  
  41.   Summary:
  42.     This file contains all of functions, macros, definitions, variables,
  43.     datatypes, etc. that are required for usage with the HID function
  44.     driver. This file should be included in projects that use the HID
  45.     \function driver.  This file should also be included into the
  46.     usb_descriptors.c file and any other user file that requires access to the
  47.     HID interface.
  48.    
  49.    
  50.    
  51.     This file is located in the "\<Install Directory\>\\Microchip\\Include\\USB"
  52.     directory.
  53.  
  54.   Description:
  55.     USB HID Function Driver File
  56.    
  57.     This file contains all of functions, macros, definitions, variables,
  58.     datatypes, etc. that are required for usage with the HID function
  59.     driver. This file should be included in projects that use the HID
  60.     \function driver.  This file should also be included into the
  61.     usb_descriptors.c file and any other user file that requires access to the
  62.     HID interface.
  63.    
  64.     This file is located in the "\<Install Directory\>\\Microchip\\Include\\USB"
  65.     directory.
  66.    
  67.     When including this file in a new project, this file can either be
  68.     referenced from the directory in which it was installed or copied
  69.     directly into the user application folder. If the first method is
  70.     chosen to keep the file located in the folder in which it is installed
  71.     then include paths need to be added so that the library and the
  72.     application both know where to reference each others files. If the
  73.     application folder is located in the same folder as the Microchip
  74.     folder (like the current demo folders), then the following include
  75.     paths need to be added to the application's project:
  76.    
  77.     ..\\Include
  78.    
  79.     ..\\..\\Include
  80.    
  81.     ..\\..\\MicrochipInclude
  82.    
  83.     ..\\..\\\<Application Folder\>
  84.    
  85.     ..\\..\\..\\\<Application Folder\>
  86.    
  87.     If a different directory structure is used, modify the paths as
  88.     required. An example using absolute paths instead of relative paths
  89.     would be the following:
  90.    
  91.     C:\\Microchip Solutions\\Microchip\\Include
  92.    
  93.     C:\\Microchip Solutions\\My Demo Application
  94. *******************************************************************/
  95. #ifndef HID_H
  96. #define HID_H
  97. //DOM-IGNORE-END
  98.  
  99. /** INCLUDES *******************************************************/
  100.  
  101. /** DEFINITIONS ****************************************************/
  102.  
  103. /* Class-Specific Requests */
  104. #define GET_REPORT      0x01
  105. #define GET_IDLE        0x02
  106. #define GET_PROTOCOL    0x03
  107. #define SET_REPORT      0x09
  108. #define SET_IDLE        0x0A
  109. #define SET_PROTOCOL    0x0B
  110.  
  111. /* Class Descriptor Types */
  112. #define DSC_HID         0x21
  113. #define DSC_RPT         0x22
  114. #define DSC_PHY         0x23
  115.  
  116. /* Protocol Selection */
  117. #define BOOT_PROTOCOL   0x00
  118. #define RPT_PROTOCOL    0x01
  119.  
  120. /* HID Interface Class Code */
  121. #define HID_INTF                    0x03
  122.  
  123. /* HID Interface Class SubClass Codes */
  124. #define BOOT_INTF_SUBCLASS          0x01
  125.  
  126. /* HID Interface Class Protocol Codes */
  127. #define HID_PROTOCOL_NONE           0x00
  128. #define HID_PROTOCOL_KEYBOARD       0x01
  129. #define HID_PROTOCOL_MOUSE          0x02
  130.  
  131. /********************************************************************
  132.     Macro:
  133.         BYTE mHIDGetRptRxLength(void)
  134.        
  135.     Description:
  136.         mHIDGetRptRxLength is used to retrieve the number
  137.         of bytes copied to user's buffer by the most
  138.         recent call to HIDRxReport function.
  139.        
  140.     Precondition:
  141.         None
  142.        
  143.     Parameters:
  144.         None
  145.        
  146.     Return Values:
  147.         BYTE : mHIDGetRptRxLength returns hid_rpt_rx_len
  148.        
  149.     Remarks:
  150.         None
  151.  
  152.  *******************************************************************/
  153. #define mHIDGetRptRxLength()        hid_rpt_rx_len
  154.  
  155. /********************************************************************
  156.     Function:
  157.         BOOL HIDTxHandleBusy(USB_HANDLE handle)
  158.        
  159.     Summary:
  160.         Retreives the status of the buffer ownership
  161.  
  162.     Description:
  163.         Retreives the status of the buffer ownership.  This function will
  164.         indicate if the previous transfer is complete or not.
  165.        
  166.         This function will take the input handle (pointer to a BDT entry) and
  167.         will check the UOWN bit.  If the UOWN bit is set then that indicates
  168.         that the transfer is not complete and the USB module still owns the data
  169.         memory.  If the UOWN bit is clear that means that the transfer is
  170.         complete and that the CPU now owns the data memory.  
  171.  
  172.         For more information about the BDT, please refer to the appropriate
  173.         datasheet for the device in use.
  174.        
  175.         Typical Usage:
  176.         <code>
  177.         //make sure that the last transfer isn't busy by checking the handle
  178.         if(!HIDTxHandleBusy(USBInHandle))
  179.         {
  180.             //Send the data contained in the ToSendDataBuffer[] array out on
  181.             //  endpoint HID_EP
  182.             USBInHandle = HIDTxPacket(HID_EP,(BYTE*)&ToSendDataBuffer[0],sizeof(ToSendDataBuffer));
  183.         }
  184.         </code>
  185.  
  186.     PreCondition:
  187.         None.
  188.        
  189.     Parameters:
  190.         USB_HANDLE handle - the handle for the transfer in question.
  191.         The handle is returned by the HIDTxPacket() and HIDRxPacket()
  192.         functions.  Please insure that USB_HANDLE objects are initialized
  193.         to NULL.
  194.        
  195.     Return Values:
  196.         TRUE - the HID handle is still busy
  197.         FALSE - the HID handle is not busy and is ready to send
  198.                 additional data.
  199.        
  200.    Remarks:
  201.         None
  202.  
  203.  *******************************************************************/
  204. #define HIDTxHandleBusy(handle) USBHandleBusy(handle)
  205.  
  206. /********************************************************************
  207.     Function:
  208.         BOOL HIDRxHandleBusy(USB_HANDLE handle)
  209.        
  210.     Summary:
  211.         Retreives the status of the buffer ownership
  212.        
  213.     Description:
  214.         Retreives the status of the buffer ownership.  This function will
  215.         indicate if the previous transfer is complete or not.
  216.        
  217.         This function will take the input handle (pointer to a BDT entry) and
  218.         will check the UOWN bit.  If the UOWN bit is set then that indicates
  219.         that the transfer is not complete and the USB module still owns the data
  220.         memory.  If the UOWN bit is clear that means that the transfer is
  221.         complete and that the CPU now owns the data memory.  
  222.  
  223.         For more information about the BDT, please refer to the appropriate
  224.         datasheet for the device in use.
  225.  
  226.         Typical Usage:
  227.         <code>
  228.         if(!HIDRxHandleBusy(USBOutHandle))
  229.         {
  230.             //The data is available in the buffer that was specified when the
  231.             //  HIDRxPacket() was called.
  232.         }
  233.         </code>
  234.  
  235.     PreCondition:
  236.         None
  237.        
  238.     Parameters:
  239.         None
  240.        
  241.     Return Values:
  242.         TRUE - the HID handle is still busy
  243.         FALSE - the HID handle is not busy and is ready to receive
  244.                 additional data.
  245.        
  246.    Remarks:
  247.         None
  248.  
  249.  *******************************************************************/
  250. #define HIDRxHandleBusy(handle) USBHandleBusy(handle)
  251.  
  252. /********************************************************************
  253.     Function:
  254.         USB_HANDLE HIDTxPacket(BYTE ep, BYTE* data, WORD len)
  255.        
  256.     Summary:
  257.         Sends the specified data out the specified endpoint
  258.  
  259.     Description:
  260.         This function sends the specified data out the specified
  261.         endpoint and returns a handle to the transfer information.
  262.  
  263.         Typical Usage:
  264.         <code>
  265.         //make sure that the last transfer isn't busy by checking the handle
  266.         if(!HIDTxHandleBusy(USBInHandle))
  267.         {
  268.             //Send the data contained in the ToSendDataBuffer[] array out on
  269.             //  endpoint HID_EP
  270.             USBInHandle = HIDTxPacket(HID_EP,(BYTE*)&ToSendDataBuffer[0],sizeof(ToSendDataBuffer));
  271.         }
  272.         </code>
  273.        
  274.     PreCondition:
  275.         None
  276.        
  277.     Parameters:
  278.         ep - the endpoint you want to send the data out of
  279.         data - pointer to the data that you wish to send
  280.         len - the length of the data that you wish to send
  281.        
  282.     Return Values:
  283.         USB_HANDLE - a handle for the transfer.  This information
  284.         should be kept to track the status of the transfer
  285.        
  286.     Remarks:
  287.         None
  288.  
  289.  *******************************************************************/
  290. #define HIDTxPacket USBTxOnePacket
  291.  
  292. /********************************************************************
  293.     Function:
  294.         USB_HANDLE HIDRxPacket(BYTE ep, BYTE* data, WORD len)
  295.        
  296.     Summary:
  297.         Receives the specified data out the specified endpoint
  298.        
  299.     Description:
  300.         Receives the specified data out the specified endpoint.
  301.  
  302.         Typical Usage:
  303.         <code>
  304.         //Read 64-bytes from endpoint HID_EP, into the ReceivedDataBuffer array.
  305.         //  Make sure to save the return handle so that we can check it later
  306.         //  to determine when the transfer is complete.
  307.         USBOutHandle = HIDRxPacket(HID_EP,(BYTE*)&ReceivedDataBuffer,64);
  308.         </code>
  309.  
  310.     PreCondition:
  311.         None
  312.        
  313.     Parameters:
  314.         ep - the endpoint you want to receive the data into
  315.         data - pointer to where the data will go when it arrives
  316.         len - the length of the data that you wish to receive
  317.        
  318.     Return Values:
  319.         USB_HANDLE - a handle for the transfer.  This information
  320.         should be kept to track the status of the transfer
  321.        
  322.     Remarks:
  323.         None
  324.  
  325.  *******************************************************************/
  326. #define HIDRxPacket USBRxOnePacket
  327.  
  328. // Section: STRUCTURES *********************************************/
  329.  
  330. //USB HID Descriptor header as detailed in section
  331. //"6.2.1 HID Descriptor" of the HID class definition specification
  332. typedef struct _USB_HID_DSC_HEADER
  333. {
  334.     BYTE bDescriptorType;   //offset 9
  335.     WORD wDscLength;        //offset 10
  336. } USB_HID_DSC_HEADER;
  337.  
  338. //USB HID Descriptor header as detailed in section
  339. //"6.2.1 HID Descriptor" of the HID class definition specification
  340. typedef struct _USB_HID_DSC
  341. {
  342.     BYTE bLength;           //offset 0
  343.     BYTE bDescriptorType;   //offset 1
  344.     WORD bcdHID;            //offset 2
  345.     BYTE bCountryCode;      //offset 4
  346.     BYTE bNumDsc;           //offset 5
  347.  
  348.  
  349.     //USB_HID_DSC_HEADER hid_dsc_header[HID_NUM_OF_DSC];
  350.     /* HID_NUM_OF_DSC is defined in usbcfg.h */
  351.    
  352. } USB_HID_DSC;
  353.  
  354. /** Section: EXTERNS ********************************************************/
  355. extern BYTE hid_rpt_rx_len;
  356. extern ROM BYTE HIDDescriptor1[];
  357.  
  358. /** Section: PUBLIC PROTOTYPES **********************************************/
  359. void USBCheckHIDRequest(void);
  360.  
  361. #endif //HID_H
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement
Public Pastes
Advertisement
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy.  OK, I Understand
Not a member of Pastebin yet?
Sign Up, it unlocks many cool features!