Skip to content

Commit 2df22e5

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

File tree

2 files changed

+95
-0
lines changed

2 files changed

+95
-0
lines changed

‎docs/api/io/BufferedSerial.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
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+
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.
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 `BufferedSerial` calls the underlying HAL API functions. See the [porting guide](../porting/serial-port.html) for target serial support.
19+
20+
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.
21+
22+
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.
23+
Using intermediary buffers allows it to be used reliably for input from non-interrupt context whilst avoiding excess spinning waiting for transmission buffer space.
24+
25+
The RX and TX buffers are circular buffers with pre-allocated sizes configurable using [`drivers/mbed_lib.json`](https://github.com/ARMmbed/mbed-os/blob/master/drivers/mbed_lib.json).
26+
27+
## Configuration
28+
29+
The following parameters can be configured at object instantiation:
30+
31+
- _TX_
32+
- _RX_
33+
- _Baud rate_ - defaults to the value configured in `mbed-os/platform/mbed_lib.json`.
34+
35+
The following parameters can be configured after an `BufferedSerial` object instantiation.
36+
37+
- _Baud rate_
38+
- _Data frame length_
39+
- _Parity bit_
40+
- _Stop bits_
41+
42+
The default settings for a microcontroller are described as _9600-8-N-1_, a common notation for serial port settings.
43+
44+
Additionally, hardware flow control can also be configured if necessary.
45+
46+
You can view more information about the configurable settings and functions in the class reference.
47+
48+
## Class reference
49+
50+
[![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)
51+
52+
<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>
53+
54+
## Example
55+
56+
[![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)
57+
58+
59+
## Printing to the console
60+
61+
Mbed OS redefines target-dependent I/O functions in the C library to allow the C standard I/O library functions (`s\v\n\printf`, `scanf`, etc) to be used in user application for printing to the console.
62+
63+
The [system I/O retarget code](https://github.com/ARMmbed/mbed-os/blob/master/platform/source/mbed_retarget.cpp) can be configured to be buffered or unbuffered depending on the configuration in [`platform/mbed_lib.json`](https://github.com/ARMmbed/mbed-os/blob/master/platform/mbed_lib.json). When it is buffered, [an instance of a `BufferedSerial` class](https://github.com/ARMmbed/mbed-os/blob/master/platform/source/mbed_retarget.cpp#L340) is used by the retarget code to perform the actual printing. This is where `BufferedSerial`'s `Filehandle` inheritance is used.
64+
65+
66+
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:
67+
68+
[![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)
69+
70+
71+
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: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
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+
You can view more information about the configurable settings and functions in the class reference.
10+
11+
## Class reference
12+
13+
[![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)
14+
15+
<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>
16+
17+
## Example
18+
19+
[![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)
20+
21+
22+
### Mbed OS usage
23+
24+
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)