USBSerial.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 USBSERIAL_H
00019 #define USBSERIAL_H
00020 
00021 #include "USBCDC.h"
00022 #include "platform/Stream.h"
00023 #include "Callback.h"
00024 
00025 /**
00026  * \defgroup drivers_USBSerial USBSerial class
00027  * \ingroup drivers-public-api-usb
00028  * @{
00029  */
00030 
00031 /**
00032 * USBSerial example
00033 *
00034 * @code
00035 * #include "mbed.h"
00036 * #include "USBSerial.h"
00037 *
00038 * //Virtual serial port over USB
00039 * USBSerial serial;
00040 *
00041 * int main(void) {
00042 *
00043 *    while(1)
00044 *    {
00045 *        serial.printf("I am a virtual serial port\n");
00046 *        wait(1);
00047 *    }
00048 * }
00049 * @endcode
00050 */
00051 class USBSerial: public USBCDC, public mbed::Stream {
00052 public:
00053 
00054     /**
00055     * Basic constructor
00056     *
00057     * Construct this object optionally connecting and blocking until it is ready.
00058     *
00059     * @note Do not use this constructor in derived classes.
00060     *
00061     * @param connect_blocking true to perform a blocking connect, false to start in a disconnected state
00062     * @param vendor_id Your vendor_id (default: 0x1f00)
00063     * @param product_id Your product_id (default: 0x2012)
00064     * @param product_release Your product_release (default: 0x0001)
00065     *
00066     */
00067     USBSerial(bool connect_blocking = true, uint16_t vendor_id = 0x1f00, uint16_t product_id = 0x2012, uint16_t product_release = 0x0001);
00068 
00069     /**
00070     * Fully featured constructor
00071     *
00072     * Construct this object with the supplied USBPhy and parameters. The user
00073     * this object is responsible for calling connect() or init().
00074     *
00075     * @note Derived classes must use this constructor and call init() or
00076     * connect() themselves. Derived classes should also call deinit() in
00077     * their destructor. This ensures that no interrupts can occur when the
00078     * object is partially constructed or destroyed.
00079     *
00080     * @param phy USB phy to use
00081     * @param vendor_id Your vendor_id (default: 0x1f00)
00082     * @param product_id Your product_id (default: 0x2012)
00083     * @param product_release Your product_release (default: 0x0001)
00084     *
00085     */
00086     USBSerial(USBPhy *phy, uint16_t vendor_id = 0x1f00, uint16_t product_id = 0x2012, uint16_t product_release = 0x0001);
00087 
00088     /**
00089      * Destroy this object
00090      *
00091      * Any classes which inherit from this class must call deinit
00092      * before this destructor runs.
00093      */
00094     virtual ~USBSerial();
00095 
00096     /**
00097     * Send a character. You can use puts, printf.
00098     *
00099     * @param c character to be sent
00100     * @returns true if there is no error, false otherwise
00101     */
00102     virtual int _putc(int c);
00103 
00104     /**
00105     * Read a character: blocking
00106     *
00107     * @returns character read
00108     */
00109     virtual int _getc();
00110 
00111     /**
00112     * Check the number of bytes available.
00113     *
00114     * @returns the number of bytes available
00115     */
00116     uint8_t available();
00117 
00118     /**
00119     * Check if the terminal is connected.
00120     *
00121     * @returns connection status
00122     */
00123     bool connected();
00124 
00125     /** Determine if there is a character available to read
00126      *
00127      *  @returns
00128      *    1 if there is a character available to read,
00129      *    0 otherwise
00130      */
00131     int readable()
00132     {
00133         return available() ? 1 : 0;
00134     }
00135 
00136     /** Determine if there is space available to write a character
00137      *
00138      *  @returns
00139      *    1 if there is space to write a character,
00140      *    0 otherwise
00141      */
00142     int writeable()
00143     {
00144         return 1;    // always return 1, for write operation is blocking
00145     }
00146 
00147     /**
00148      *  Attach a member function to call when a packet is received.
00149      *
00150      *  @param tptr pointer to the object to call the member function on
00151      *  @param mptr pointer to the member function to be called
00152      */
00153     template<typename T>
00154     void attach(T *tptr, void (T::*mptr)(void))
00155     {
00156         USBCDC::lock();
00157 
00158         if ((mptr != NULL) && (tptr != NULL)) {
00159             rx = mbed::Callback<void()>(tptr, mptr);
00160         }
00161 
00162         USBCDC::unlock();
00163     }
00164 
00165     /**
00166      * Attach a callback called when a packet is received
00167      *
00168      * @param fptr function pointer
00169      */
00170     void attach(void (*fptr)(void))
00171     {
00172         USBCDC::lock();
00173 
00174         if (fptr != NULL) {
00175             rx = mbed::Callback<void()>(fptr);
00176         }
00177 
00178         USBCDC::unlock();
00179     }
00180 
00181     /**
00182      * Attach a Callback called when a packet is received
00183      *
00184      * @param cb Callback to attach
00185      */
00186     void attach(mbed::Callback<void()> &cb)
00187     {
00188         USBCDC::lock();
00189 
00190         rx = cb;
00191 
00192         USBCDC::unlock();
00193     }
00194 
00195     /**
00196      * Attach a callback to call when serial's settings are changed.
00197      *
00198      * @param fptr function pointer
00199      */
00200     void attach(void (*fptr)(int baud, int bits, int parity, int stop))
00201     {
00202         USBCDC::lock();
00203 
00204         _settings_changed_callback = fptr;
00205 
00206         USBCDC::unlock();
00207     }
00208 
00209 protected:
00210     virtual void data_rx();
00211     virtual void line_coding_changed(int baud, int bits, int parity, int stop)
00212     {
00213         assert_locked();
00214 
00215         if (_settings_changed_callback) {
00216             _settings_changed_callback(baud, bits, parity, stop);
00217         }
00218     }
00219 
00220 private:
00221     mbed::Callback<void()> rx;
00222     void (*_settings_changed_callback)(int baud, int bits, int parity, int stop);
00223 };
00224 
00225 /** @}*/
00226 
00227 #endif