Skip to content

Commit b0e23ec

Browse files
hugueskambahugueskamba
committed
Add UnbufferedSerial and BufferedSerial API documentation
1 parent 922afeb commit b0e23ec

File tree

2 files changed

+101
-0
lines changed

2 files changed

+101
-0
lines changed

‎docs/api/io/BufferedSerial.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# BufferedSerial
2+
3+
<span class="images">![](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_buffered_serial.png)<span>`BufferedSerial` class hierarchy</span></span>
4+
5+
The `BufferedSerial` class provides UART functionality, it is the recommended class for serial data transfers. It allows sending and receiving bytes of data in a sequence using separate transmit (TX) and receive pins (RX). Communication can be between two processors or for sending text to a console.
6+
7+
Serial channels have the following characteristics:
8+
9+
* TX and RX pins - can be specified as Not Connected (NC) for simplex (unidirectional) communication or as valid pins for full duplex (bi-directional) communication.
10+
11+
* Baud rate - pre-defined speed at which data is sent and received. Standard baud rates include 9600, 119200, 115200 or others.
12+
13+
Data is transmitted using packets of configurable sizes divided in different sections which include:
14+
15+
* Start bit: Indicates the start of UART data transmission.
16+
* Data frame: Can be 5 to 8 (or 9 if a parity bit is not used) bits long for the actual data being transferred.
17+
* Parity bit: Optional bit, used for data error detection.
18+
* Stop bits: Can be 1 to 2 bits long to signal the end of a data packet.
19+
20+
The `BufferedSerial` calls the underlying HAL API functions. See the [porting guide](../porting/serial-port.html) for target serial support.
21+
22+
When the RX interrupt is trigged, the `BufferedSerial` class stores the byte(s) available to read from the hardware buffer to an internal intermediary buffer. When a read request is made, the `BufferedSerial` class uses a mutex lock and enters a critical section to read out the number of bytes requested if as many are available in the intermediary buffer.
23+
24+
To transmit multiple bytes, the class uses an intermediary buffer to store the bytes to send and monitors the serial interface to transfer them to the hardware buffer as soon as it is available. However, all bytes are written unbuffered if in a critical section.
25+
Using intermediary buffers allows it to be used reliably for input from non-interrupt context whilst avoiding excess spinning waiting for transmission buffer space.
26+
27+
The RX and TX buffers are circular buffers with pre-allocated sizes configurable using the configuration parameters `uart-serial-rxbuf-size` and `uart-serial-txbuf-size` respectively. Both configuration parameters can be found in `drivers/mbed_lib.json`.
28+
29+
## Configuration
30+
31+
The following parameters can be configured at object instantiation:
32+
33+
- _TX_
34+
- _RX_
35+
- _Baud rate_
36+
37+
The default baud rate value is configured in `mbed-os/platform/mbed_lib.json`.
38+
39+
The following parameters can be configured after an `BufferedSerial` object instantiation.
40+
41+
- _Baud rate_
42+
- _Data frame length_
43+
- _Parity bit_
44+
- _Stop bits_
45+
46+
The default settings for a microcontroller are set as _9600-8-N-1_, a common notation for serial port settings. This denotes a baud rate of nine thousand six hundred (9600), eight data frame length (8), no parity bit (N) and one stop bit (1).
47+
48+
Additionally, hardware flow control can also be configured if necessary.
49+
50+
You can view more information about the configurable settings and functions in the class reference.
51+
52+
## Class reference
53+
54+
[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/mbed-os/development/mbed-os-api-doxy/classmbed_1_1_buffered_serial.html)
55+
56+
<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>
57+
58+
## Example
59+
60+
[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/BufferedSerial/)](https://os.mbed.com/teams/mbed_example/code/BufferedSerial/file/112a40a5991a/main.cpp)
61+
62+
63+
## Printing to the console
64+
65+
Mbed OS redefines target-dependent I/O functions in the C library to allow the C standard I/O library functions (`s\v\f\n\printf`, `scanf`, etc) to be used in user application for printing to the console.
66+
67+
The system I/O retarget code can be configured to be buffered or unbuffered depending on the configuration of the parameter `stdio-buffered-serial` in `platform/mbed_lib.json`. When it is buffered, an instance of a `BufferedSerial` class is used by the retarget code to perform the actual printing. This is where `BufferedSerial`'s `Filehandle` inheritance is used.
68+
69+
70+
Alternatively, if more configuration of the serial interface is needed, an instance of the `BufferedSerial` class can be passed to the system I/O retarget code at run time to be used for printing to the console as shown below:
71+
72+
[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed_example/code/BufferedSerial/)](https://os.mbed.com/teams/mbed_example/code/BufferedSerial_printf/file/112a40a5991a/main.cpp)
73+
74+
75+
Using the standard C I/O library directly is the recommended way to print to the console in Mbed OS.

‎docs/api/io/UnbufferedSerial.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
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 with an API similar to the [`BufferedSerial`](./BufferedSerial.md) class. The classes also share the same default configurations.
6+
7+
Unlike the `BufferedSerial` class, the `UnbufferedSerial` class does not use intermediary buffers to store bytes to transmit to or read from the hardware. The user application is responsible for processing each byte as they are received. The method to read data returns only one byte for every call. It is therefore suitable when more control is required and for use in interrupt handlers with the RTOS. The class can however be used to write multiple bytes at once. Since it does not acquire a mutex lock, care must be taken that only one instance is using the serial port.
8+
9+
For normal blocking application that require a serial channel for something other than the console, `BufferedSerial` will perform better than `UnbufferedSerial` and will cause less CPU load and latency issues. `UnbufferedSerial` should only be used by applications that are short of RAM and cannot afford buffering or need more control of the serial port and use it from IRQ.
10+
11+
You can view more information about the configurable settings and functions in the class reference.
12+
13+
## Class reference
14+
15+
[![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)
16+
17+
<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>
18+
19+
## Example
20+
21+
[![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)
22+
23+
24+
### Mbed OS usage
25+
26+
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)