Add UnbufferedSerial and BufferedSerial API documentation #1220

hugueskamba · 2020-02-05T15:19:05Z

Merge only after ARMmbed/mbed-os-examples-docs_only#66

The example code snippet URLs need to be amended prior to merging!

docs/api/io/BufferedSerial.md

docs/api/io/UnbufferedSerial.md

docs/api/io/BufferedSerial.md

docs/api/io/UnbufferedSerial.md

Make initial copy edits, mostly for active voice, correct links and consistent style.

AnotherButler

I've left some edits and queries. Please review my changes to make sure I didn't accidentally change the meaning of anything.

AnotherButler · 2020-02-11T21:51:56Z

docs/api/io/BufferedSerial.md

+
+<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>
+
+The `BufferedSerial` class provides UART functionality. We recommend you use this class for serial data transfers. You can use it to send and receive 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.


What does this last sentence mean?

It means that a device can interface with another device (such as sensors, printers, or another board) to exchange data or to send text to be displayed on a text-based computer interface.

I would either remove the original sentence or replace it with the explanation in your comment.

Thanks. Done.

AnotherButler · 2020-02-11T21:52:21Z

docs/api/io/BufferedSerial.md

+
+Serial channels have the following characteristics:
+
+- TX and RX pins - can be specified as Not Connected (NC) for simplex (unidirectional) communication or as valid pins for full duplex (bidirectional) communication.


Can be specified by whom or by what? You, the user?

I suggest the text from RawSerial: 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.

Can be specified by whom or by what? You, the user?

The user can.

AnotherButler · 2020-02-11T21:52:39Z

docs/api/io/BufferedSerial.md

+Serial channels have the following characteristics:
+
+- TX and RX pins - can be specified as Not Connected (NC) for simplex (unidirectional) communication or as valid pins for full duplex (bidirectional) communication.
+- Baud rate - predefined speed at which data is sent and received. Standard baud rates include 9600, 119200 and 115200.


Who or what sends the data? The BufferedSerial class?

AnotherButler · 2020-02-11T21:53:49Z

docs/api/io/BufferedSerial.md

+
+The `BufferedSerial` calls the underlying HAL API functions. Please see the [porting guide](../porting/serial-port.html) for target serial support.
+
+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.


What do we mean by "the RX is trigged," and who or what trigged it?
Who or what makes the read request?

RX is explained in the first paragraph of the page. It is triggered when receiving data from whatever is connected to that interface (a sensor, a console, etc...).

AnotherButler · 2020-02-11T21:54:17Z

docs/api/io/BufferedSerial.md

+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.
+
+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.
+Using intermediary buffers allows it to be used reliably for input from noninterrupt context while avoiding excess spinning waiting for transmission buffer space.


Using intermediary buffers allows us to use what reliably? The class?

The UART interface.

AnotherButler · 2020-02-11T21:54:57Z

docs/api/io/BufferedSerial.md

+
+The RX and TX buffers are circular buffers with preallocated sizes configurable using the configuration parameters `uart-serial-rxbuf-size` and `uart-serial-txbuf-size`. You can find both configuration parameters in `drivers/mbed_lib.json`.
+
+## Configuration


Are these the same configuration parameters you get by running the --config -v command?

This is to configure a UART interface via the BufferedSerial class for the user application.
Nothing to do with Mbed CLI.

AnotherButler · 2020-02-11T21:55:21Z

docs/api/io/BufferedSerial.md

+
+Mbed OS redefines target-dependent I/O functions in the C library to allow you to use the C standard I/O library functions (`s\v\f\n\printf`, `scanf` and so on) in your application for printing to the console.
+
+You can refigure the system I/O retarget code to be buffered or unbuffered, depending on the configuration of the parameter `stdio-buffered-serial` in `platform/mbed_lib.json`. When it is buffered, the retarget code uses an instance of a `BufferedSerial` class to perform the actual printing. This is where `BufferedSerial`'s `Filehandle` inheritance is used.


Who or what uses the Filehandle inheritance?

It says BufferedSerial's.
You see in the diagram at the top of the page that BufferedSerial inherits from FileHandle. Because it inherits from FileHandle it can be used for the re-target code.

Edit file, mostly for accurate links and active voice.

hugueskamba · 2020-02-14T09:13:32Z

docs/api/io/BufferedSerial.md


 You can view more information about the configurable settings and functions in the class reference.

-## Class reference
+## BufferedSerial class reference


This edit seems redundant since the page is about BufferedSerial.

hugueskamba · 2020-02-14T09:13:52Z

docs/api/io/BufferedSerial.md


+## BufferedSerial examples


This edit seems redundant since the page is about BufferedSerial.

hugueskamba · 2020-02-14T09:20:35Z

I've left some edits and queries. Please review my changes to make sure I didn't accidentally change the meaning of anything.

@AnotherButler
I reviewed the edits, and commented on some of them.
I have replied to the review comments and pushed some changes to address them.

evedon · 2020-02-17T09:38:15Z

@AnotherButler Please review after the last edits. Note that the code for the examples has been merged so this PR is ready for merge once you are happy with it.

Delete extra space and extra comma.

hugueskamba requested review from AnotherButler and evedon February 5, 2020 15:19

hugueskamba mentioned this pull request Feb 5, 2020

Add code snippet for UnbufferedSerial and BufferedSerial API documentation ARMmbed/mbed-os-examples-docs_only#66

Merged

AnotherButler added the code dependency label Feb 5, 2020

hugueskamba force-pushed the hk-add-unbuffered-serial-api-doc branch 2 times, most recently from bb9b660 to f5a2ad6 Compare February 6, 2020 13:56

hugueskamba changed the title ~~Add UnbufferedSerial API documentation~~ Add UnbufferedSerial and BufferedSerial API documentation Feb 6, 2020

hugueskamba force-pushed the hk-add-unbuffered-serial-api-doc branch from f5a2ad6 to b14e6f6 Compare February 6, 2020 13:58

evedon reviewed Feb 6, 2020

View reviewed changes

hugueskamba force-pushed the hk-add-unbuffered-serial-api-doc branch 4 times, most recently from 2df22e5 to fb589a8 Compare February 7, 2020 11:21

evedon reviewed Feb 7, 2020

View reviewed changes

Add UnbufferedSerial and BufferedSerial API documentation

b0e23ec

hugueskamba force-pushed the hk-add-unbuffered-serial-api-doc branch from fb589a8 to b0e23ec Compare February 8, 2020 15:19

evedon approved these changes Feb 11, 2020

View reviewed changes

Edit BufferedSerial.md

cbcf750

Make initial copy edits, mostly for active voice, correct links and consistent style.

AnotherButler reviewed Feb 11, 2020

View reviewed changes

Edit UnbufferedSerial.md

5dded9a

Edit file, mostly for accurate links and active voice.

hugueskamba commented Feb 14, 2020

View reviewed changes

Edits based on feedback.

1a6d337

Clarify possible communications with UART interface

0c90ed3

AnotherButler removed the code dependency label Feb 18, 2020

Fix typos in BufferedSerial.md

d46a267

Delete extra space and extra comma.

AnotherButler approved these changes Feb 18, 2020

View reviewed changes

AnotherButler merged commit f9370b4 into development Feb 18, 2020

AnotherButler deleted the hk-add-unbuffered-serial-api-doc branch February 18, 2020 23:05


		<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>

		The `BufferedSerial` class provides UART functionality. We recommend you use this class for serial data transfers. You can use it to send and receive 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.


		Serial channels have the following characteristics:

		- TX and RX pins - can be specified as Not Connected (NC) for simplex (unidirectional) communication or as valid pins for full duplex (bidirectional) communication.


		The `BufferedSerial` calls the underlying HAL API functions. Please see the [porting guide](../porting/serial-port.html) for target serial support.

		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.


		The RX and TX buffers are circular buffers with preallocated sizes configurable using the configuration parameters `uart-serial-rxbuf-size` and `uart-serial-txbuf-size`. You can find both configuration parameters in `drivers/mbed_lib.json`.

		## Configuration


		Mbed OS redefines target-dependent I/O functions in the C library to allow you to use the C standard I/O library functions (`s\v\f\n\printf`, `scanf` and so on) in your application for printing to the console.

		You can refigure the system I/O retarget code to be buffered or unbuffered, depending on the configuration of the parameter `stdio-buffered-serial` in `platform/mbed_lib.json`. When it is buffered, the retarget code uses an instance of a `BufferedSerial` class to perform the actual printing. This is where `BufferedSerial`'s `Filehandle` inheritance is used.

Add UnbufferedSerial and BufferedSerial API documentation #1220

Add UnbufferedSerial and BufferedSerial API documentation #1220

Uh oh!

Conversation

hugueskamba commented Feb 5, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge only after ARMmbed/mbed-os-examples-docs_only#66

The example code snippet URLs need to be amended prior to merging!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugueskamba Feb 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugueskamba Feb 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugueskamba Feb 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugueskamba commented Feb 14, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

evedon commented Feb 17, 2020

Uh oh!

Uh oh!

hugueskamba commented Feb 5, 2020 •

edited

Loading

hugueskamba Feb 14, 2020 •

edited

Loading

hugueskamba Feb 14, 2020 •

edited

Loading

hugueskamba Feb 14, 2020 •

edited

Loading

hugueskamba commented Feb 14, 2020 •

edited

Loading