Serial
Note: In Mbed OS 6, this API will be deprecated in favor of BufferedSerial and UnbufferedSerial.
Serial class hierarchy
The Serial interface provides UART functionality. The serial link has two unidirectional 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 uses the Arm Mbed USB port, allowing you to easily communicate with your host PC.
Serial class reference
| 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. More... | |
| Serial (const serial_pinmap_t &static_pinmap, 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. More... | |
| Serial (PinName tx, PinName rx, int baud) | |
| Create a Serial port, connected to the specified transmit and receive pins, with the specified baud. More... | |
| Serial (const serial_pinmap_t &static_pinmap, int baud) | |
| Create a Serial port, connected to the specified transmit and receive pins, with the specified baud. More... | |
| void | baud (int baudrate) |
| Set the baud rate of the serial port. More... | |
| void | format (int bits=8, Parity parity=SerialBase::None, int stop_bits=1) |
| Set the transmission format used by the serial port. More... | |
| void | attach (Callback< void()> func, IrqType type=RxIrq) |
| Attach a function to call whenever a serial interrupt is generated. More... | |
| template<typename T > | |
| void | attach (T *obj, void(T::*method)(), IrqType type=RxIrq) |
| Attach a member function to call whenever a serial interrupt is generated. More... | |
| template<typename T > | |
| void | attach (T *obj, void(*method)(T *), IrqType type=RxIrq) |
| Attach a member function to call whenever a serial interrupt is generated. More... | |
| void | set_break () |
| Generate a break condition on the serial line NOTE: Clear break needs to run at least one frame after set_break is called. More... | |
| void | clear_break () |
| Clear a break condition on the serial line NOTE: Should be run at least one frame after set_break is called. More... | |
| void | send_break () |
| Generate a break condition on the serial line. More... | |
| void | enable_input (bool enable=true) |
| Enable serial input. More... | |
| void | enable_output (bool enable=true) |
| Enable serial output. More... | |
| void | set_flow_control (Flow type, PinName flow1=NC, PinName flow2=NC) |
| Set the flow control type on the serial port. More... | |
| void | set_flow_control (Flow type, const serial_fc_pinmap_t &static_pinmap) |
| Set the flow control type on the serial port. More... | |
| 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. More... | |
| 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. More... | |
| void | abort_write () |
| Abort the on-going write transfer. More... | |
| 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. More... | |
| 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. More... | |
| void | abort_read () |
| Abort the on-going read transfer. More... | |
| int | set_dma_usage_tx (DMAUsage usage) |
| Configure DMA usage suggestion for non-blocking TX transfers. More... | |
| int | set_dma_usage_rx (DMAUsage usage) |
| Configure DMA usage suggestion for non-blocking RX transfers. More... | |
| virtual int | close () |
| Close a file. More... | |
| virtual ssize_t | write (const void *buffer, size_t length) |
| Write the contents of a buffer to a file. More... | |
| virtual ssize_t | read (void *buffer, size_t length) |
| Read the contents of a file into a buffer. More... | |
| virtual off_t | seek (off_t offset, int whence) |
| Move the file position to a given offset from from a given location. More... | |
| virtual off_t | tell () |
| Get the file position of the file. More... | |
| virtual void | rewind () |
| Rewind the file position to the beginning of the file. More... | |
| virtual int | isatty () |
| Check if the file in an interactive terminal device. More... | |
| virtual int | sync () |
| Flush any buffers associated with the file. More... | |
| virtual off_t | size () |
| Get the size of the file. More... | |
| virtual int | truncate (off_t length) |
| Truncate or extend a file. More... | |
| virtual off_t | lseek (off_t offset, int whence) |
| Move the file position to a given offset from a given location. More... | |
| virtual int | fsync () |
| Flush any buffers associated with the FileHandle, ensuring it is up to date on disk. More... | |
| virtual off_t | flen () |
| Find the length of the file. More... | |
| virtual int | set_blocking (bool blocking) |
| Set blocking or nonblocking mode of the file operation like read/write. More... | |
| virtual bool | is_blocking () const |
| Check current blocking or nonblocking mode for file operations. More... | |
| virtual int | enable_input (bool enabled) |
| Enable or disable input. More... | |
| virtual int | enable_output (bool enabled) |
| Enable or disable output. More... | |
| virtual short | poll (short events) const |
| Check for poll event flags You can use or ignore the input parameter. More... | |
| bool | writable () const |
| Definition depends on the subclass implementing FileHandle. More... | |
| bool | readable () const |
| Definition depends on the subclass implementing FileHandle. More... | |
| virtual void | sigio (Callback< void()> func) |
| Register a callback on state change of the file. More... | |
| Protected Member Functions | |
| virtual void | lock () |
| Acquire exclusive access to this object. More... | |
| virtual void | unlock () |
| Release exclusive access to this object. More... | |
Note: On a Windows machine, you will need to install a USB serial driver. See Windows serial configuration.
Serial channels have the following configurable parameters:
- TX and RX Pin - The physical serial transmit and receive pins. You can specify a TX or RX pin as Not Connected (NC) to get Simplex communication, or specify both to get Full Duplex communication.
- Baud Rate - Standard baud rates range from a few hundred bits per second to megabits per second. The default setting for a serial connection on the microcontroller is 9600 baud.
- Data length - Transferred data can be either 7 or 8 bits long. The default setting for a serial connection on the microcontroller is 8 bits.
- Parity - You can add an optional parity bit. The Serial object automatically sets the parity bit to make the number of 1s in the data either odd or even. Parity settings are Odd, Even or None. The default setting for a serial connection on the microcontroller is None.
- Stop Bits - After the transmission of data and parity bits, the Serial object inserts one or two stop bits to "frame" the data. The default setting for a serial connection on the microcontroller is one stop bit.
The default settings for the microcontroller are described as 9600-8-N-1, a common notation for serial port settings.
Serial hello, world
/* mbed Example Program
* Copyright (c) 2006-2014 ARM Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include "mbed.h"
Serial pc(USBTX, USBRX); // tx, rx
int main() {
pc.printf("Hello World!\n\r");
while(1) {
pc.putc(pc.getc() + 1); // echo input back to terminal
}
}
Serial examples
Example one
Write a message to a device at a baud rate of 19200.
#include "mbed.h"
Serial device(USBTX, USBRX); // tx, rx
int main() {
device.baud(19200);
device.printf("Hello World\n");
}
Example two
Provide a serial pass-through between the PC and an external UART.
#include "mbed.h"
//K64F
Serial pc(USBTX, USBRX); // tx, rx
Serial device(MBED_CONF_APP_UART1_TX, MBED_CONF_APP_UART1_RX); // tx, rx
int main() {
while(1) {
if(pc.readable()) {
device.putc(pc.getc());
}
if(device.readable()) {
pc.putc(device.getc());
}
}
}
Related content
- Serial glossary entry.
- Windows serial configuration.