Serial

mbed OS 2 and mbed OS 5

This is the handbook for mbed OS 2. If you’re working with mbed OS 5, please see the new handbook and API References. For the latest Serial API, please see Serial.

Serial is a generic protocol used by computers and electronic modules to send and receive control information and data. The Serial link has two unidirection channels, one for sending and one for receiving. The link is asynchronous, and so both ends of the serial link must be configured to use the same settings.

One of the Serial connections goes via the mbed USB port, allowing you to easily communicate with your host PC.

Hello World!

Import program

00001 #include "mbed.h"
00002  
00003 Serial pc(USBTX, USBRX); // tx, rx
00004  
00005 int main() {
00006     pc.printf("Hello World!\n");
00007     while(1) {
00008         pc.putc(pc.getc() + 1);
00009     }
00010 }

API

API summary

Import library

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.

Interface

The Serial Interface can be used on supported pins and USBTX/USBRX

/media/uploads/chris/pinout-thumbnails.jpg
See the Pinout page for more details

Note that USBTX/USBRX are not DIP pins; they represent the pins that route to the interface USB Serial port so you can communicate with a host PC.

Note

If you want to send data to a host PC, take a look at:

  • SerialPC - Communicating between mbed and a host PC

Note that on a windows machine, you will need to install a USB Serial driver, see:

Serial channels have a number of configurable parameters:

  • Baud Rate - There are a number of standard baud rates ranging from a few hundred bits per seconds, to megabits per second. The default setting for a Serial connection on the mbed Microcontroller is 9600 baud.
  • Data length - Data transferred can be either 7 or 8 bits long. The default setting for a Serial connection on the mbed Microcontroller is 8 bits.
  • Parity - An optional parity bit can be added. The parity bit will be automatically set to make the number of 1's in the data either odd or even. Parity settings are Odd, Even or None. The default setting for a Serial connection on the mbed microcontroller is for the parity to be set to None.
  • Stop Bits - After data and parity bits have been transmitted, 1 or 2 stop bit is inserted to "frame" the data. The default setting for a Serial connection on the mbed microcontroller is for one stop bit to be added.

The default settings for the mbed microcontroller are described as 9600 8N1, and this is common notation for Serial port settings.

See Also

Reference

Examples

Write a message to a device at a 19200 baud

#include "mbed.h"

Serial device(p9, p10);  // tx, rx

int main() {
    device.baud(19200);
    device.printf("Hello World\n");
}

Provide a serial pass-through between the PC and an external UART

#include "mbed.h"

Serial pc(USBTX, USBRX); // tx, rx
Serial device(p9, p10);  // tx, rx

int main() {
    while(1) {
        if(pc.readable()) {
            device.putc(pc.getc());
        }
        if(device.readable()) {
            pc.putc(device.getc());
        }
    }
}

Attach to RX Interrupt

#include "mbed.h"

DigitalOut led1(LED1);
DigitalOut led2(LED2);

Serial pc(USBTX, USBRX);

void callback() {
    // Note: you need to actually read from the serial to clear the RX interrupt
    printf("%c\n", pc.getc());
    led2 = !led2;
}

int main() {
    pc.attach(&callback);
    
    while (1) {
        led1 = !led1;
        wait(0.5);
    }
}