The official mbed C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

Embed: (wiki syntax)

« Back to documentation index

Serial Class Reference

A serial port (UART) for communication with other serial devices. More...

#include <Serial.h>

Inherits mbed::SerialBase, mbed::Stream, and NonCopyable< Serial >.

Public Member Functions

 Serial (PinName tx, PinName rx, const char *name=NULL, int baud=MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
 Create a Serial port, connected to the specified transmit and receive pins.
 Serial (PinName tx, PinName rx, int baud)
 Create a Serial port, connected to the specified transmit and receive pins, with the specified baud.
bool readable ()
 Determine if there is a character available to read.
bool writeable ()
 Determine if there is space available to write a character.
void baud (int baudrate)
 Set the baud rate of the serial port.
void format (int bits=8, Parity parity=SerialBase::None, int stop_bits=1)
 Set the transmission format used by the serial port.
void attach (Callback< void()> func, IrqType type=RxIrq)
 Attach a function to call whenever a serial interrupt is generated.
template<typename T >
 MBED_DEPRECATED_SINCE ("mbed-os-5.1","The attach function does not support cv-qualifiers. Replaced by ""attach(callback(obj, method), type).") void attach(T *obj
 Attach a member function to call whenever a serial interrupt is generated.
void set_flow_control (Flow type, PinName flow1=NC, PinName flow2=NC)
 Set the flow control type on the serial port.
int write (const uint8_t *buffer, int length, const event_callback_t &callback, int event=SERIAL_EVENT_TX_COMPLETE)
 Begin asynchronous write using 8bit buffer.
int write (const uint16_t *buffer, int length, const event_callback_t &callback, int event=SERIAL_EVENT_TX_COMPLETE)
 Begin asynchronous write using 16bit buffer.
void abort_write ()
 Abort the on-going write transfer.
int read (uint8_t *buffer, int length, const event_callback_t &callback, int event=SERIAL_EVENT_RX_COMPLETE, unsigned char char_match=SERIAL_RESERVED_CHAR_MATCH)
 Begin asynchronous reading using 8bit buffer.
int read (uint16_t *buffer, int length, const event_callback_t &callback, int event=SERIAL_EVENT_RX_COMPLETE, unsigned char char_match=SERIAL_RESERVED_CHAR_MATCH)
 Begin asynchronous reading using 16bit buffer.
void abort_read ()
 Abort the on-going read transfer.
int set_dma_usage_tx (DMAUsage usage)
 Configure DMA usage suggestion for non-blocking TX transfers.
int set_dma_usage_rx (DMAUsage usage)
 Configure DMA usage suggestion for non-blocking RX transfers.
 MBED_DEPRECATED_SINCE ("mbed-os-5.4","Replaced by FileHandle::seek") virtual off_t lseek(off_t offset
 Move the file position to a given offset from a given location.

Protected Member Functions

virtual void lock ()
 Acquire exclusive access to this serial port.
virtual void unlock ()
 Release exclusive access to this serial port.
virtual int close ()
 Close a file.
virtual ssize_t write (const void *buffer, size_t length)
 Write the contents of a buffer to a file.
virtual ssize_t read (void *buffer, size_t length)
 Read the contents of a file into a buffer.
virtual off_t seek (off_t offset, int whence)
 Move the file position to a given offset from from a given location.
virtual off_t tell ()
 Get the file position of the file.
virtual void rewind ()
 Rewind the file position to the beginning of the file.
virtual int isatty ()
 Check if the file in an interactive terminal device.
virtual int sync ()
 Flush any buffers associated with the file.
virtual off_t size ()
 Get the size of the file.

Detailed Description

A serial port (UART) for communication with other serial devices.

Can be used for Full Duplex communication, or Simplex by specifying one pin as NC (Not Connected)

Note:
Synchronization level: Thread safe

Example:

 // Print "Hello World" to the PC

 #include "mbed.h"

 Serial pc(USBTX, USBRX);

 int main() {
     pc.printf("Hello World\n");
 }

Definition at line 53 of file Serial.h.


Constructor & Destructor Documentation

Serial ( PinName  tx,
PinName  rx,
const char *  name = NULL,
int  baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE 
)

Create a Serial port, connected to the specified transmit and receive pins.

Parameters:
txTransmit pin
rxReceive pin
nameThe name of the stream associated with this serial port (optional)
baudThe baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
Note:
Either tx or rx may be specified as NC if unused
Serial ( PinName  tx,
PinName  rx,
int  baud 
)

Create a Serial port, connected to the specified transmit and receive pins, with the specified baud.

Parameters:
txTransmit pin
rxReceive pin
baudThe baud rate of the serial port
Note:
Either tx or rx may be specified as NC if unused

Member Function Documentation

void abort_read (  ) [inherited]

Abort the on-going read transfer.

void abort_write (  ) [inherited]

Abort the on-going write transfer.

void attach ( Callback< void()>  func,
IrqType  type = RxIrq 
) [inherited]

Attach a function to call whenever a serial interrupt is generated.

Parameters:
funcA pointer to a void function, or 0 to set as none
typeWhich serial interrupt to attach the member function to (Seriall::RxIrq for receive, TxIrq for transmit buffer empty)
void baud ( int  baudrate ) [inherited]

Set the baud rate of the serial port.

Parameters:
baudrateThe baudrate of the serial port (default = 9600).
virtual int close (  ) [protected, virtual, inherited]

Close a file.

Returns:
0 on success, negative error code on failure

Implements FileHandle.

void format ( int  bits = 8,
Parity  parity = SerialBase::None,
int  stop_bits = 1 
) [inherited]

Set the transmission format used by the serial port.

Parameters:
bitsThe number of bits in a word (5-8; default = 8)
parityThe parity used (SerialBase::None, SerialBase::Odd, SerialBase::Even, SerialBase::Forced1, SerialBase::Forced0; default = SerialBase::None)
stop_bitsThe number of stop bits (1 or 2; default = 1)
virtual int isatty (  ) [protected, virtual, inherited]

Check if the file in an interactive terminal device.

Returns:
True if the file is a terminal
False if the file is not a terminal
Negative error code on failure

Reimplemented from FileHandle.

virtual void lock (  ) [protected, virtual]

Acquire exclusive access to this serial port.

Reimplemented from SerialBase.

MBED_DEPRECATED_SINCE ( "mbed-os-5.4"  ,
"Replaced by FileHandle::seek"   
) [inherited]

Move the file position to a given offset from a given location.

Parameters:
offsetThe offset from whence to move to
whenceSEEK_SET for the start of the file, SEEK_CUR for the current file position, or SEEK_END for the end of the file.
Returns:
new file position on success, -1 on failure or unsupported
MBED_DEPRECATED_SINCE ( "mbed-os-5.1"  ,
"The attach function does not support cv-qualifiers. Replaced by ""attach(callback(obj, method), type)."   
) [inherited]

Attach a member function to call whenever a serial interrupt is generated.

Parameters:
objpointer to the object to call the member function on
methodpointer to the member function to be called
typeWhich serial interrupt to attach the member function to (Seriall::RxIrq for receive, TxIrq for transmit buffer empty)
int read ( uint8_t *  buffer,
int  length,
const event_callback_t &  callback,
int  event = SERIAL_EVENT_RX_COMPLETE,
unsigned char  char_match = SERIAL_RESERVED_CHAR_MATCH 
) [inherited]

Begin asynchronous reading using 8bit buffer.

The completition invokes registred RX event callback.

Parameters:
bufferThe buffer where received data will be stored
lengthThe buffer length in bytes
callbackThe event callback function
eventThe logical OR of RX events
char_matchThe matching character
int read ( uint16_t *  buffer,
int  length,
const event_callback_t &  callback,
int  event = SERIAL_EVENT_RX_COMPLETE,
unsigned char  char_match = SERIAL_RESERVED_CHAR_MATCH 
) [inherited]

Begin asynchronous reading using 16bit buffer.

The completition invokes registred RX event callback.

Parameters:
bufferThe buffer where received data will be stored
lengthThe buffer length in bytes
callbackThe event callback function
eventThe logical OR of RX events
char_matchThe matching character
virtual ssize_t read ( void *  buffer,
size_t  size 
) [protected, virtual, inherited]

Read the contents of a file into a buffer.

Devices acting as FileHandles should follow POSIX semantics:

* if no data is available, and non-blocking set return -EAGAIN * if no data is available, and blocking set, wait until data is available * If any data is available, call returns immediately

Parameters:
bufferThe buffer to read in to
sizeThe number of bytes to read
Returns:
The number of bytes read, 0 at end of file, negative error on failure

Implements FileHandle.

bool readable (  )

Determine if there is a character available to read.

Returns:
1 if there is a character available to read, 0 otherwise

Reimplemented from SerialBase.

Definition at line 89 of file Serial.h.

virtual void rewind (  ) [protected, virtual, inherited]

Rewind the file position to the beginning of the file.

Note:
This is equivalent to seek(0, SEEK_SET)

Reimplemented from FileHandle.

virtual off_t seek ( off_t  offset,
int  whence 
) [protected, virtual, inherited]

Move the file position to a given offset from from a given location.

Parameters:
offsetThe offset from whence to move to
whenceThe start of where to seek SEEK_SET to start from beginning of file, SEEK_CUR to start from current position in file, SEEK_END to start from end of file
Returns:
The new offset of the file, negative error code on failure

Implements FileHandle.

int set_dma_usage_rx ( DMAUsage  usage ) [inherited]

Configure DMA usage suggestion for non-blocking RX transfers.

Parameters:
usageThe usage DMA hint for peripheral
Returns:
Zero if the usage was set, -1 if a transaction is on-going
int set_dma_usage_tx ( DMAUsage  usage ) [inherited]

Configure DMA usage suggestion for non-blocking TX transfers.

Parameters:
usageThe usage DMA hint for peripheral
Returns:
Zero if the usage was set, -1 if a transaction is on-going
void set_flow_control ( Flow  type,
PinName  flow1 = NC,
PinName  flow2 = NC 
) [inherited]

Set the flow control type on the serial port.

Parameters:
typethe flow control type (Disabled, RTS, CTS, RTSCTS)
flow1the first flow control pin (RTS for RTS or RTSCTS, CTS for CTS)
flow2the second flow control pin (CTS for RTSCTS)
virtual off_t size (  ) [protected, virtual, inherited]

Get the size of the file.

Returns:
Size of the file in bytes

Reimplemented from FileHandle.

virtual int sync (  ) [protected, virtual, inherited]

Flush any buffers associated with the file.

Returns:
0 on success, negative error code on failure

Reimplemented from FileHandle.

virtual off_t tell (  ) [protected, virtual, inherited]

Get the file position of the file.

Note:
This is equivalent to seek(0, SEEK_CUR)
Returns:
The current offset in the file, negative error code on failure

Reimplemented from FileHandle.

virtual void unlock (  ) [protected, virtual]

Release exclusive access to this serial port.

Reimplemented from SerialBase.

int write ( const uint16_t *  buffer,
int  length,
const event_callback_t &  callback,
int  event = SERIAL_EVENT_TX_COMPLETE 
) [inherited]

Begin asynchronous write using 16bit buffer.

The completition invokes registered TX event callback

Parameters:
bufferThe buffer where received data will be stored
lengthThe buffer length in bytes
callbackThe event callback function
eventThe logical OR of TX events
int write ( const uint8_t *  buffer,
int  length,
const event_callback_t &  callback,
int  event = SERIAL_EVENT_TX_COMPLETE 
) [inherited]

Begin asynchronous write using 8bit buffer.

The completition invokes registered TX event callback

Parameters:
bufferThe buffer where received data will be stored
lengthThe buffer length in bytes
callbackThe event callback function
eventThe logical OR of TX events
virtual ssize_t write ( const void *  buffer,
size_t  size 
) [protected, virtual, inherited]

Write the contents of a buffer to a file.

Parameters:
bufferThe buffer to write from
sizeThe number of bytes to write
Returns:
The number of bytes written, negative error on failure

Implements FileHandle.

bool writeable (  )

Determine if there is space available to write a character.

Returns:
1 if there is space to write a character, 0 otherwise

Reimplemented from SerialBase.

Definition at line 97 of file Serial.h.