USBHID.h

00001 /*
00002  * Copyright (c) 2018-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef USB_HID_H
00019 #define USB_HID_H
00020 
00021 /* These headers are included for child class. */
00022 #include "USBDescriptor.h"
00023 #include "USBDevice.h"
00024 
00025 #include "USBHID_Types.h"
00026 #include "OperationList.h"
00027 
00028 /**
00029  * \defgroup drivers_USBHID USBHID class
00030  * \ingroup drivers-public-api-usb
00031  * @{
00032  */
00033 
00034 /**
00035  * USBHID example
00036  * @code
00037  * #include "mbed.h"
00038  * #include "USBHID.h"
00039  *
00040  * USBHID hid;
00041  * HID_REPORT recv;
00042  * BusOut leds(LED1,LED2,LED3,LED4);
00043  *
00044  * int main(void) {
00045  *    while (1) {
00046  *        hid.read(&recv);
00047  *        leds = recv.data[0];
00048  *    }
00049  * }
00050  * @endcode
00051  */
00052 
00053 class USBHID: public USBDevice {
00054 public:
00055 
00056     /**
00057     * Basic constructor
00058     *
00059     * Construct this object optionally connecting and blocking until it is ready.
00060     *
00061     * @note Do not use this constructor in derived classes.
00062     *
00063     * @param connect_blocking true to perform a blocking connect, false to start in a disconnected state
00064     * @param output_report_length Maximum length of a sent report (up to 64 bytes)
00065     * @param input_report_length Maximum length of a received report (up to 64 bytes)
00066     * @param vendor_id Your vendor_id
00067     * @param product_id Your product_id
00068     * @param product_release Your product_release
00069     */
00070     USBHID(bool connect_blocking = true, 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);
00071 
00072     /**
00073     * Fully featured constructor
00074     *
00075     * Construct this object with the supplied USBPhy and parameters. The user
00076     * this object is responsible for calling connect() or init().
00077     *
00078     * @note Derived classes must use this constructor and call init() or
00079     * connect() themselves. Derived classes should also call deinit() in
00080     * their destructor. This ensures that no interrupts can occur when the
00081     * object is partially constructed or destroyed.
00082     *
00083     * @param phy USB phy to use
00084     * @param output_report_length Maximum length of a sent report (up to 64 bytes)
00085     * @param input_report_length Maximum length of a received report (up to 64 bytes)
00086     * @param vendor_id Your vendor_id
00087     * @param product_id Your product_id
00088     * @param product_release Your product_release
00089     */
00090     USBHID(USBPhy *phy, uint8_t output_report_length, uint8_t input_report_length, uint16_t vendor_id, uint16_t product_id, uint16_t product_release);
00091 
00092     /**
00093      * Destroy this object
00094      *
00095      * Any classes which inherit from this class must call deinit
00096      * before this destructor runs.
00097      */
00098     virtual ~USBHID();
00099 
00100     /**
00101      * Check if this class is ready
00102      *
00103      * @return true if the device is in the configured state
00104      */
00105     bool ready();
00106 
00107     /**
00108      * Block until this HID device is in the configured state
00109      */
00110     void wait_ready();
00111 
00112     /**
00113     * Send a Report. warning: blocking
00114     *
00115     * @param report Report which will be sent (a report is defined by all data and the length)
00116     * @returns true if successful
00117     */
00118     bool send(const HID_REPORT *report);
00119 
00120 
00121     /**
00122     * Send a Report. warning: non blocking
00123     *
00124     * @param report Report which will be sent (a report is defined by all data and the length)
00125     * @returns true if successful
00126     */
00127     bool send_nb(const HID_REPORT *report);
00128 
00129     /**
00130     * Read a report: blocking
00131     *
00132     * @param report pointer to the report to fill
00133     * @returns true if successful
00134     */
00135     bool read(HID_REPORT *report);
00136 
00137     /**
00138     * Read a report: non blocking
00139     *
00140     * @param report pointer to the report to fill
00141     * @returns true if successful
00142     */
00143     bool read_nb(HID_REPORT *report);
00144 
00145 protected:
00146     uint16_t reportLength;
00147     uint8_t reportDescriptor[27];
00148 
00149     /*
00150     * Get the Report descriptor
00151     *
00152     * @returns pointer to the report descriptor
00153     */
00154     virtual const uint8_t *report_desc();
00155 
00156     /*
00157     * Get the length of the report descriptor
00158     *
00159     * @returns the length of the report descriptor
00160     */
00161     virtual uint16_t report_desc_length();
00162 
00163     /*
00164     * Get string product descriptor
00165     *
00166     * @returns pointer to the string product descriptor
00167     */
00168     virtual const uint8_t *string_iproduct_desc();
00169 
00170     /*
00171     * Get string interface descriptor
00172     *
00173     * @returns pointer to the string interface descriptor
00174     */
00175     virtual const uint8_t *string_iinterface_desc();
00176 
00177     /*
00178     * Get configuration descriptor
00179     *
00180     * @returns pointer to the configuration descriptor
00181     */
00182     virtual const uint8_t *configuration_desc(uint8_t index);
00183 
00184 
00185     /*
00186     * HID Report received by SET_REPORT request. Warning: Called in ISR context
00187     * First byte of data will be the report ID
00188     *
00189     * @param report Data and length received
00190     */
00191     virtual void HID_callbackSetReport(HID_REPORT *report) {};
00192 
00193     /**
00194     * Called when USB changes state
00195     *
00196     * @param new_state The new state of the USBDevice
00197     *
00198     * Warning: Called in ISR context
00199     */
00200     virtual void callback_state_change(DeviceState new_state);
00201 
00202     /*
00203     * This is used to handle extensions to standard requests
00204     * and class specific requests
00205     */
00206     virtual void callback_request(const setup_packet_t *setup);
00207 
00208     /*
00209     * This is used to handle extensions to standard requests
00210     * and class specific requests with a data phase
00211     */
00212     virtual void callback_request_xfer_done(const setup_packet_t *setup, bool aborted);
00213 
00214 
00215     /*
00216     * Called by USBDevice layer. Set configuration of the device.
00217     * For instance, you can add all endpoints that you need on this function.
00218     *
00219     * @param configuration Number of the configuration
00220     * @returns true if class handles this request
00221     */
00222     virtual void callback_set_configuration(uint8_t configuration);
00223 
00224     /*
00225     * Called by USBDevice layer in response to set_interface.
00226     *
00227     * Upon reception of this command endpoints of any previous interface
00228     * if any must be removed with endpoint_remove and new endpoint added with
00229     * endpoint_add.
00230     *
00231     * @param configuration Number of the configuration
00232     *
00233     * Warning: Called in ISR context
00234     */
00235     virtual void callback_set_interface(uint16_t interface, uint8_t alternate);
00236 
00237     /*
00238      * Called when there is a hid report that can be read
00239      */
00240     virtual void report_rx() {}
00241 
00242     /*
00243      * Called when there is space to send a hid report
00244      */
00245     virtual void report_tx() {}
00246 
00247 protected:
00248     usb_ep_t _int_in;
00249     usb_ep_t _int_out;
00250 
00251 private:
00252     void _init(uint8_t output_report_length, uint8_t input_report_length);
00253     void _send_isr();
00254     void _read_isr();
00255 
00256     class AsyncSend;
00257     class AsyncRead;
00258     class AsyncWait;
00259 
00260     OperationList<AsyncWait> _connect_list;
00261     OperationList<AsyncSend> _send_list;
00262     bool _send_idle;
00263     OperationList<AsyncRead> _read_list;
00264     bool _read_idle;
00265 
00266     uint8_t _configuration_descriptor[41];
00267     HID_REPORT _input_report;
00268     HID_REPORT _output_report;
00269     uint8_t _output_length;
00270     uint8_t _input_length;
00271 
00272 
00273 };
00274 
00275 /** @}*/
00276 
00277 #endif