USBHID.h

00001 /* Copyright (c) 2010-2011 mbed.org, MIT License
00002 *
00003 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
00004 * and associated documentation files (the "Software"), to deal in the Software without
00005 * restriction, including without limitation the rights to use, copy, modify, merge, publish,
00006 * distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
00007 * Software is furnished to do so, subject to the following conditions:
00008 *
00009 * The above copyright notice and this permission notice shall be included in all copies or
00010 * substantial portions of the Software.
00011 *
00012 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
00013 * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00014 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
00015 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00016 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00017 */
00018 
00019 #ifndef USB_HID_H
00020 #define USB_HID_H
00021 
00022 /* These headers are included for child class. */
00023 #include "USBEndpoints.h"
00024 #include "USBDescriptor.h"
00025 #include "USBDevice_Types.h"
00026 
00027 #include "USBHID_Types.h"
00028 #include "USBDevice.h"
00029 
00030 /**
00031  * USBHID example
00032  * @code
00033  * 
00034  * //We declare a USBHID device. Input, Output, and Feature reports have a length of 8 bytes
00035  * USBHID hid(8, 8, 8,0x1234,0x0006, 0x0001,true);
00036  * HID_REPORT tempReport;
00037  
00038  * void MycallbackSetReport(HID_REPORT *report){
00039  *     printf("Report: ");
00040  *             for(int i = 0; i < report->length; i++) {
00041  *                 printf("%x ", report->data[i]);
00042  *             }
00043  *     printf("\r\n");
00044  * };
00045  * 
00046  * bool SetTempReport(HID_REPORT *report){
00047  *         for (int i = 0; i < report->length; i++) {
00048  *             report->data[i] = rand() & 0xff;
00049  *         }
00050  *     return true;
00051  * };
00052  *  
00053  * int main(void) {
00054  *     printf("Starting==>\r\n");
00055  *     hid.callbackSetOutputReport=&MycallbackSetReport;    
00056  *     tempReport.length=8;
00057 
00058  *     while (1) {
00059  *        SetTempReport(&tempReport);
00060  *        hid.FillInputReport(&tempReport);        
00061  *        wait(2.2);
00062  *     }
00063  * }
00064  * 
00065  * @endcode
00066  */
00067 
00068 class USBHID: public USBDevice {
00069 public:
00070 
00071     /**
00072     * Constructor
00073     *
00074     * @param output_report_length Maximum length of a sent report (up to 64 bytes) (default: 64 bytes)
00075     * @param input_report_length Maximum length of a received report (up to 64 bytes) (default: 64 bytes)
00076     * @param report_report_length Maximum length of a received report (up to 64 bytes) (default: 64 bytes)
00077     * @param vendor_id Your vendor_id
00078     * @param product_id Your product_id
00079     * @param product_release Your preoduct_release
00080     * @param connect Connect the device
00081     */
00082     USBHID(uint8_t output_report_length , uint8_t input_report_length , uint8_t feature_report_length , uint16_t vendor_id , uint16_t product_id , uint16_t product_release , bool connect );
00083     /**
00084     * Constructor
00085     * default constructor to maintain backwards compatibility. 
00086     *
00087     * @param output_report_length Maximum length of a sent report (up to 64 bytes) (default: 64 bytes)
00088     * @param input_report_length Maximum length of a received report (up to 64 bytes) (default: 64 bytes)
00089     * @param report_report_length Maximum length of a received report (up to 64 bytes) (default: 64 bytes)
00090     * @param vendor_id Your vendor_id
00091     * @param product_id Your product_id
00092     * @param product_release Your preoduct_release
00093     * @param connect Connect the device
00094     */
00095     USBHID(uint8_t output_report_length = 64, uint8_t input_report_length = 64, uint16_t vendor_id = 0x1234, uint16_t product_id = 0x0006, uint16_t product_release = 0x0001, bool connect = true);
00096 
00097 
00098     /**
00099     * Send a Report. warning: blocking
00100     * legacy method retained for backward compatability
00101     *
00102     * @param report Report which will be sent (a report is defined by all data and the length)
00103     * @returns true if successful
00104     */
00105     bool send(HID_REPORT *report);
00106     
00107     
00108     /**
00109     * Send a Report. warning: non blocking
00110     * legacy method retained for backward compatability
00111     *
00112     * @param report Report which will be sent (a report is defined by all data and the length)
00113     * @returns true if successful
00114     */
00115     bool sendNB(HID_REPORT *report);
00116     
00117     /**
00118     * Read a report: blocking
00119     * legacy method retained for backward compatability
00120     *
00121     * @param report pointer to the report to fill
00122     * @returns true if successful
00123     */
00124     bool read(HID_REPORT * report);
00125     
00126     /**
00127     * Read a report: non blocking
00128     * legacy method retained for backward compatability
00129     *
00130     * @param report pointer to the report to fill
00131     * @returns true if successful
00132     */
00133     bool readNB(HID_REPORT * report);
00134     
00135     /**
00136     * Provide the ability to Fill the inputReport. Report transfer is automatic if the data changes
00137     *
00138     * @param HID_REPORT
00139     * @returns true if succsful
00140     * The devloper should always use FillReport, The IDLE logic will send a report if the value has changed, or if the idle period expires.
00141     */
00142     bool FillInputReport(HID_REPORT *report);
00143     
00144     /**
00145     * Provide the ability to Fill the featureReport. 
00146     *
00147     * @param HID_REPORT
00148     * @returns true if succsful
00149     */
00150     bool FillFeatureReport(HID_REPORT *report);
00151     
00152     
00153     /**
00154     * Callback pointers to functions
00155     *
00156     * @param report pointer to the report to fill
00157     * These allow a user program to hook on get_report/set_report actions for each type.
00158     */
00159     void (*callbackSetInputReport)(HID_REPORT *report);
00160     /**
00161     * Callback pointers to functions
00162     *
00163     * @param report pointer to the report to fill
00164     * These allow a user program to hook on get_report/set_report actions for each type.
00165     */
00166     bool (*callbackGetInputReport)(HID_REPORT *report);
00167     /**
00168     * Callback pointers to functions
00169     *
00170     * @param report pointer to the report to fill
00171     * These allow a user program to hook on get_report/set_report actions for each type.
00172     */
00173     void (*callbackSetOutputReport)(HID_REPORT *report);
00174     /**
00175     * Callback pointers to functions
00176     *
00177     * @param report pointer to the report to fill
00178     * These allow a user program to hook on get_report/set_report actions for each type.
00179     */
00180     bool (*callbackGetOutputReport)(HID_REPORT *report);
00181     /**
00182     * Callback pointers to functions
00183     *
00184     * @param report pointer to the report to fill
00185     * These allow a user program to hook on get_report/set_report actions for each type.
00186     */
00187     void (*callbackSetFeatureReport)(HID_REPORT *report);
00188     /**
00189     * Callback pointers to functions
00190     *
00191     * @param report pointer to the report to fill
00192     * These allow a user program to hook on get_report/set_report actions for each type.
00193     */
00194     bool (*callbackGetFeatureReport)(HID_REPORT *report);
00195     
00196     /**
00197     * This function should be private, but is exposed to allow a developer to reenable IDLE values > zero after windows sets the value to zero. 
00198     *    This is due to microsoft windows HID driver not implementing IOCTL_HID_SET_POLL_FREQUENCY_MSEC/IOCTL_HID_GET_POLL_FREQUENCY_MSEC
00199     */
00200     virtual void SetReportIdle(uint16_t wValue);
00201     uint8_t protocolState;
00202     
00203 
00204 protected:
00205     uint16_t reportLength;
00206     
00207     /*
00208     * Get the Report descriptor
00209     *
00210     * @returns pointer to the report descriptor
00211     */
00212     virtual uint8_t * reportDesc();
00213 
00214     /*
00215     * Get the length of the report descriptor
00216     *
00217     * @returns the length of the report descriptor
00218     */
00219     virtual uint16_t reportDescLength();
00220 
00221     /*
00222     * Get string product descriptor
00223     *
00224     * @returns pointer to the string product descriptor
00225     */
00226     virtual uint8_t * stringIproductDesc();
00227     
00228     /*
00229     * Get string interface descriptor
00230     *
00231     * @returns pointer to the string interface descriptor
00232     */
00233     virtual uint8_t * stringIinterfaceDesc();
00234     
00235     /*
00236     * Get configuration descriptor
00237     *
00238     * @returns pointer to the configuration descriptor
00239     */
00240     virtual uint8_t * configurationDesc();
00241 
00242 
00243     /*
00244     * HID Report received by SET_REPORT request. Warning: Called in ISR context
00245     * First byte of data will be the report ID
00246     *
00247     * @param report Data and length received
00248     */
00249     static void HID_callbackSetReport(HID_REPORT *report){};
00250     
00251     /*
00252     * HID Report received by GET_REPORT request. Warning: Called in ISR context
00253     * First byte of data will be the report ID
00254     *
00255     * @param report Data and length received
00256     */
00257     static bool HID_callbackGetReport(HID_REPORT *report){return true;};
00258    
00259     /*
00260     * Called by USBDevice on Endpoint0 request. Warning: Called in ISR context
00261     * This is used to handle extensions to standard requests
00262     * and class specific requests
00263     *
00264     * @returns true if class handles this request
00265     */
00266     virtual bool USBCallback_request();
00267     /*
00268     * Called by USBDevice on Endpoint0 request completion
00269     * if the 'notify' flag has been set to true. Warning: Called in ISR context
00270     *
00271     * In this case it is used to indicate that a HID report has
00272     * been received from the host on endpoint 0
00273     *
00274     * @param buf buffer received on endpoint 0
00275     * @param length length of this buffer
00276     */
00277     virtual void USBCallback_requestCompleted(uint8_t * buf, uint32_t length);
00278 
00279     /*
00280     * Called by USBDevice layer. to ensure that control transfers and interupt transfers work on the same reports.
00281     */
00282     virtual bool EP1_OUT_callback();
00283     
00284     /* Called by FillInputReport when data has changed, and transmits the data. */
00285     bool SendReport(void);
00286     
00287     /*
00288     * Called by USBDevice layer.to set configuration
00289     */
00290     virtual bool USBCallback_setConfiguration(uint8_t configuration);
00291     
00292     /* tells SET_IDLE/GET_IDLE where the IDE rate value is. */
00293     
00294     virtual uint8_t * getReportIdlePtr(uint8_t reportID){ return &reportIdleRateInt; };
00295     
00296     
00297 private:
00298    // TODO: HID Reports should be dynamically malloced to save memory and prepare for multi-reports 
00299     HID_REPORT inputReport;
00300     HID_REPORT outputReport;
00301     HID_REPORT featureReport;
00302     uint8_t output_length;
00303     uint8_t input_length;
00304     uint8_t feature_length;
00305  
00306     //TODO: REPORT clsss should be created to handle MULTI-report
00307     //Implementation items for IDLE rate (TICKER)
00308     float reportIdleRate;
00309     uint8_t reportIdleRateInt;
00310     Ticker countDownToReportTrigger;
00311     void ResetIdleTicker(void);
00312     void IdlePeriodReSend(void);
00313    
00314     //Report REPORT data pointer retrieval.
00315     HID_REPORT * GetReportTargetPointer(uint16_t wValue);
00316     //Report Set/GET REPORT callback handlers
00317     bool HIDCallback_GetReportHandler(HID_REPORT *targetPtr);
00318     bool HIDCallback_SetReportHandler(HID_REPORT *targetPtr);
00319 };
00320 
00321 #endif