USBDevice.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 USBDEVICE_H
00020 #define USBDEVICE_H
00021 
00022 #include "mbed.h"
00023 #include "USBDevice_Types.h"
00024 #include "USBHAL.h"
00025 
00026 class USBDevice: public USBHAL
00027 {
00028 public:
00029     USBDevice(uint16_t vendor_id, uint16_t product_id, uint16_t product_release);
00030     
00031     /*
00032     * Check if the device is configured
00033     *
00034     * @returns true if configured, false otherwise
00035     */
00036     bool configured(void);
00037     
00038     /*
00039     * Connect a device
00040     */
00041     void connect(void);
00042     DEVICE_STATE getDeviceState();
00043     
00044     /*
00045     * Disconnect a device
00046     */
00047     void disconnect(void);
00048     
00049     /*
00050     * Add an endpoint
00051     *
00052     * @param endpoint endpoint which will be added
00053     * @param maxPacket Maximum size of a packet which can be sent for this endpoint
00054     * @returns true if successful, false otherwise
00055     */
00056     bool addEndpoint(uint8_t endpoint, uint32_t maxPacket);
00057 
00058     /*
00059     * Start a reading on a certain endpoint.
00060     * You can access the result of the reading by USBDevice_read
00061     *
00062     * @param endpoint endpoint which will be read
00063     * @param maxSize the maximum length that can be read
00064     * @return true if successful
00065     */
00066     bool readStart(uint8_t endpoint, uint32_t maxSize);
00067     
00068     /*
00069     * Read a certain endpoint. Before calling this function, USBUSBDevice_readStart
00070     * must be called.
00071     *
00072     * Warning: blocking
00073     *
00074     * @param endpoint endpoint which will be read
00075     * @param buffer buffer will be filled with the data received
00076     * @param size the number of bytes read will be stored in *size
00077     * @param maxSize the maximum length that can be read
00078     * @returns true if successful
00079     */
00080     bool readEP(uint8_t endpoint, uint8_t * buffer, uint32_t * size, uint32_t maxSize);
00081     
00082     /*
00083     * Read a certain endpoint.
00084     *
00085     * Warning: non blocking
00086     *
00087     * @param endpoint endpoint which will be read
00088     * @param buffer buffer will be filled with the data received (if data are available) 
00089     * @param size the number of bytes read will be stored in *size
00090     * @param maxSize the maximum length that can be read
00091     * @returns true if successful
00092     */
00093     bool readEP_NB(uint8_t endpoint, uint8_t * buffer, uint32_t * size, uint32_t maxSize);
00094     
00095     /*
00096     * Write a certain endpoint.
00097     *
00098     * Warning: blocking
00099     *
00100     * @param endpoint endpoint to write
00101     * @param buffer data contained in buffer will be write
00102     * @param size the number of bytes to write
00103     * @param maxSize the maximum length that can be written on this endpoint
00104     */
00105     bool write(uint8_t endpoint, uint8_t * buffer, uint32_t size, uint32_t maxSize);
00106     
00107     
00108     /*
00109     * Write a certain endpoint.
00110     *
00111     * Warning: non blocking
00112     *
00113     * @param endpoint endpoint to write
00114     * @param buffer data contained in buffer will be write
00115     * @param size the number of bytes to write
00116     * @param maxSize the maximum length that can be written on this endpoint
00117     */
00118     bool writeNB(uint8_t endpoint, uint8_t * buffer, uint32_t size, uint32_t maxSize);
00119 
00120     
00121     /*
00122     * Called by USBDevice layer on bus reset. Warning: Called in ISR context
00123     *
00124     * May be used to reset state
00125     */
00126     virtual void USBCallback_busReset(void) {};
00127     
00128     /*
00129     * Called by USBDevice on Endpoint0 request. Warning: Called in ISR context
00130     * This is used to handle extensions to standard requests
00131     * and class specific requests
00132     *
00133     * @returns true if class handles this request
00134     */
00135     virtual bool USBCallback_request() { return false; };   
00136     
00137     /*
00138     * Called by USBDevice on Endpoint0 request completion
00139     * if the 'notify' flag has been set to true. Warning: Called in ISR context
00140     *
00141     * In this case it is used to indicate that a HID report has
00142     * been received from the host on endpoint 0
00143     *
00144     * @param buf buffer received on endpoint 0
00145     * @param length length of this buffer
00146     */
00147     virtual void USBCallback_requestCompleted(uint8_t * buf, uint32_t length) {};
00148     
00149     /*
00150     * Called by USBDevice layer. Set configuration of the device.
00151     * For instance, you can add all endpoints that you need on this function.
00152     *
00153     * @param configuration Number of the configuration
00154     */
00155     virtual bool USBCallback_setConfiguration(uint8_t configuration) { return false; };
00156     
00157     /*
00158      * Called by USBDevice layer. Set interface/alternate of the device.
00159      *
00160      * @param interface Number of the interface to be configured
00161      * @param alternate Number of the alternate to be configured
00162      * @returns true if class handles this request
00163      */
00164     virtual bool USBCallback_setInterface(uint16_t interface, uint8_t alternate) { return false; };
00165 
00166     /*
00167     * Get device descriptor. Warning: this method has to store the length of the report descriptor in reportLength.
00168     *
00169     * @returns pointer to the device descriptor
00170     */
00171     virtual uint8_t * deviceDesc();
00172     
00173     /*
00174     * Get configuration descriptor
00175     *
00176     * @returns pointer to the configuration descriptor
00177     */
00178     virtual uint8_t * configurationDesc(){return NULL;};
00179     
00180     /*
00181     * Get string lang id descriptor
00182     *
00183     * @return pointer to the string lang id descriptor
00184     */
00185     virtual uint8_t * stringLangidDesc();
00186     
00187     /*
00188     * Get string manufacturer descriptor
00189     *
00190     * @returns pointer to the string manufacturer descriptor
00191     */
00192     virtual uint8_t * stringImanufacturerDesc();
00193     
00194     /*
00195     * Get string product descriptor
00196     *
00197     * @returns pointer to the string product descriptor
00198     */
00199     virtual uint8_t * stringIproductDesc();
00200     
00201     /*
00202     * Get string serial descriptor
00203     *
00204     * @returns pointer to the string serial descriptor
00205     */
00206     virtual uint8_t * stringIserialDesc();
00207     
00208     /*
00209     * Get string configuration descriptor
00210     *
00211     * @returns pointer to the string configuration descriptor
00212     */
00213     virtual uint8_t * stringIConfigurationDesc();
00214     
00215     /*
00216     * Get string interface descriptor
00217     *
00218     * @returns pointer to the string interface descriptor
00219     */
00220     virtual uint8_t * stringIinterfaceDesc();
00221     
00222     /*
00223     * Get the length of the report descriptor
00224     *
00225     * @returns length of the report descriptor
00226     */
00227     virtual uint16_t reportDescLength() { return 0; };
00228     
00229 
00230 
00231 protected:
00232     virtual void busReset(void);
00233     virtual void EP0setupCallback(void);
00234     virtual void EP0out(void);
00235     virtual void EP0in(void);
00236     virtual void connectStateChanged(unsigned int connected);
00237     virtual void suspendStateChanged(unsigned int suspended);
00238     uint8_t * findDescriptor(uint8_t descriptorType);
00239     CONTROL_TRANSFER * getTransferPtr(void);
00240     
00241     uint16_t VENDOR_ID;
00242     uint16_t PRODUCT_ID;
00243     uint16_t PRODUCT_RELEASE;
00244 
00245 private:
00246     bool addRateFeedbackEndpoint(uint8_t endpoint, uint32_t maxPacket);
00247     bool requestGetDescriptor(void);
00248     bool controlOut(void);
00249     bool controlIn(void);
00250     bool requestSetAddress(void);
00251     bool requestSetConfiguration(void);
00252     bool requestSetFeature(void);
00253     bool requestClearFeature(void);
00254     bool requestGetStatus(void);
00255     bool requestSetup(void);
00256     bool controlSetup(void);
00257     void decodeSetupPacket(uint8_t *data, SETUP_PACKET *packet);
00258     bool requestGetConfiguration(void);
00259     bool requestGetInterface(void);
00260     bool requestSetInterface(void);
00261 
00262     CONTROL_TRANSFER transfer;
00263     USB_DEVICE device;
00264     
00265     uint16_t currentInterface;
00266     uint8_t currentAlternate;
00267 };
00268 
00269 
00270 #endif