Serial.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2019 ARM Limited
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 #ifndef MBED_SERIAL_H
00018 #define MBED_SERIAL_H
00019 
00020 #include "platform/platform.h"
00021 
00022 #if DEVICE_SERIAL || defined(DOXYGEN_ONLY)
00023 
00024 #include "platform/Stream.h"
00025 #include "drivers/SerialBase.h"
00026 #include "platform/PlatformMutex.h"
00027 #include "platform/NonCopyable.h"
00028 
00029 namespace mbed {
00030 /**
00031  * \defgroup drivers_Serial Serial class
00032  * \ingroup drivers-public-api-uart
00033  * @{
00034  */
00035 
00036 /** @deprecated
00037  * A serial port (UART) for communication with other serial devices
00038  *
00039  * Can be used for Full Duplex communication, or Simplex by specifying
00040  * one pin as NC (Not Connected)
00041  *
00042  * @note Synchronization level: Thread safe
00043  *
00044  * Example:
00045  * @code
00046  * // Print "Hello World" to the PC
00047  *
00048  * #include "mbed.h"
00049  *
00050  * Serial pc(USBTX, USBRX);
00051  *
00052  * int main() {
00053  *     pc.printf("Hello World\n");
00054  * }
00055  * @endcode
00056  */
00057 class
00058     MBED_DEPRECATED_SINCE (
00059         "mbed-os-6.0.0",
00060         "Use printf and puts instead to access the console, BufferedSerial for blocking applications or UnbufferedSerial if bypassing locks in IRQ or short of RAM."
00061     ) Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
00062 
00063 public:
00064 #if DEVICE_SERIAL_ASYNCH
00065     using SerialBase::read;
00066     using SerialBase::write;
00067 #endif
00068 
00069     /** Resolve ambiguities in SerialBase and FileHandle
00070      * (for enable_input and enable_output)
00071      */
00072     using SerialBase::enable_input;
00073     using SerialBase::enable_output;
00074 
00075     /** @deprecated
00076      * Create a Serial port, connected to the specified transmit and receive pins
00077      *
00078      *  @param tx Transmit pin
00079      *  @param rx Receive pin
00080      *  @param name The name of the stream associated with this serial port (optional)
00081      *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE or 9600)
00082      *
00083      *  @note
00084      *    Either tx or rx may be specified as NC (Not Connected) if unused
00085      */
00086     MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
00087     Serial(PinName tx, PinName rx, const char *name = NULL, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
00088 
00089     /** @deprecated
00090      * Create a Serial port, connected to the specified transmit and receive pins
00091      *
00092      *  @param static_pinmap reference to structure which holds static pinmap.
00093      *  @param name The name of the stream associated with this serial port (optional)
00094      *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE or 9600)
00095      *
00096      *  @note
00097      *    Either tx or rx may be specified as NC (Not Connected) if unused
00098      */
00099     MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
00100     Serial(const serial_pinmap_t &static_pinmap, const char *name = NULL, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
00101     MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
00102     Serial(const serial_pinmap_t &&, const char * = NULL, int = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE) = delete; // prevent passing of temporary objects
00103 
00104     /** @deprecated
00105      * Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
00106      *
00107      *  @param tx Transmit pin
00108      *  @param rx Receive pin
00109      *  @param baud The baud rate of the serial port
00110      *
00111      *  @note
00112      *    Either tx or rx may be specified as NC (Not Connected) if unused
00113      */
00114     MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
00115     Serial(PinName tx, PinName rx, int baud);
00116 
00117     /** @deprecated
00118      * Create a Serial port, connected to the specified transmit and receive pins, with the specified baud
00119      *
00120      *  @param static_pinmap reference to structure which holds static pinmap.
00121      *  @param baud The baud rate of the serial port
00122      *
00123      *  @note
00124      *    Either tx or rx may be specified as NC (Not Connected) if unused
00125      */
00126     MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
00127     Serial(const serial_pinmap_t &static_pinmap, int baud);
00128     MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
00129     Serial(const serial_pinmap_t &&, int) = delete; // prevent passing of temporary objects
00130 
00131     /* Stream gives us a FileHandle with non-functional poll()/readable()/writable. Pass through
00132      * the calls from the SerialBase instead for backwards compatibility. This problem is
00133      * part of why Stream and Serial should be deprecated.
00134      */
00135     MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
00136     bool readable()
00137     {
00138         return SerialBase::readable();
00139     }
00140     MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
00141     bool writable()
00142     {
00143         return SerialBase::writeable();
00144     }
00145     MBED_DEPRECATED("The class has been deprecated and will be removed in the future.")
00146     bool writeable()
00147     {
00148         return SerialBase::writeable();
00149     }
00150 
00151 #if !(DOXYGEN_ONLY)
00152 protected:
00153     virtual int _getc();
00154     virtual int _putc(int c);
00155     virtual void lock();
00156     virtual void unlock();
00157 
00158     PlatformMutex _mutex;
00159 #endif
00160 };
00161 
00162 /** @}*/
00163 
00164 } // namespace mbed
00165 
00166 #endif
00167 
00168 #endif