Skip to content

Commit bb9b660

Browse files
committed
Add UnbufferedSerial API documentation
1 parent b06f979 commit bb9b660

File tree

1 file changed

+56
-0
lines changed

1 file changed

+56
-0
lines changed

docs/api/io/UnbufferedSerial.md

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# UnbufferedSerial
2+
3+
<span class="images">![](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_unbuffered_serial.png)<span>`UnbufferedSerial` class hierarchy</span></span>
4+
5+
The `UnbufferedSerial` class provides UART functionality. It allows sending and receiving bytes of data in a sequence using separate transmit (TXD) and receive pins (RXD). Communication can be between two processors or for sending text to a console.
6+
7+
TXD and RXD can be specified as Not Connected (NC) for simplex (unidirectional) communication or as valid pins for full duplex (bi-directional) communication.
8+
9+
Data is sent/received at a pre-defined speed called baud rate. Standard baud rate include 9600, 119200, 115200 or others.
10+
11+
Pieces of data are transmitted using data packets of configurable sizes divided in different sections which include:
12+
13+
* Start bit: Indicates the start of UART data transmission
14+
* Data frame: Can be 5 to 8 (or 9 if a parity bit is not used) bits long for the actual data being transferred.
15+
* Parity bit: Optional bit, used for data error detection.
16+
* Stop bits: Can be 1 to 2 bits long to signal the end of a data packet.
17+
18+
The `UnbufferedSerial` class maps targets underlying serial communication functions. See the [porting guide](../porting/serial-port.html) for target serial support.
19+
20+
Unlike the `BufferedSerial` class with which it shares a similar API, the `UnbufferedSerial` class has no lock as it reads one byte at a time and is therefore suitable for use in interrupt handlers with the RTOS. It can however be used to write multiple bytes at once by locking the API usage in the RTOS.
21+
22+
## Configuration
23+
24+
The following parameters can be configured at object instantiation:
25+
26+
- _TXD_
27+
- _RXD_
28+
- _Baud rate_ - defaults to the value configured in `mbed-os/platform/mbed_lib.json`.
29+
30+
The following parameters can be configured after an `UnbufferedSerial` object instantiation.
31+
32+
- _Baud rate_
33+
- _Data frame length_
34+
- _Parity bit_
35+
- _Stop bits_
36+
37+
The default settings for a microcontroller are described as _9600-8-N-1_, a common notation for serial port settings.
38+
39+
Additionally, hardware flow control can also be configured if necessary.
40+
41+
You can view more information about the configurable settings and functions in the class reference.
42+
43+
## Class reference
44+
45+
[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/classmbed_1_1_unbuffered_serial.html)
46+
47+
<span class="notes">**Note**: On a Windows machine, you need to install a USB serial driver. See [Windows serial configuration](../tutorials/serial-communication.html#windows-serial-driver).</span>
48+
49+
## Example
50+
51+
[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/UnbufferedSerial/)](https://os.mbed.com/teams/mbed_example/code/UnbufferedSerial/file/112a40a5991a/main.cpp)
52+
53+
54+
### Mbed OS usage
55+
56+
Common use cases for `UnbufferedSerial` are IRQ heavy UART operations, such as the [BLE cordio in the transport driver](https://github.com/ARMmbed/mbed-os/blob/master/features/FEATURE_BLE/targets/TARGET_CORDIO/driver/H4TransportDriver.cpp#L62).

0 commit comments

Comments
 (0)