Update serial communication and clean up duplicated & outdated info #1317

LDong-Arm · 2020-05-15T12:03:50Z

Replaced by #1326 to allow previewing.

This PR is created to

replace third party serial software with the simple mbed sterm command
use printf() (instead of serial classes) for debug printing
clarify that buffered/unbuffered serial classes can capture keyboard inputs
remove/refactor duplicated information in multiple documents

The following files are refactored:

serial_communication.md - This is the guide for serial communication (mbed sterm, ...) with updated information.
quick-start-cli-debug.md, quick-start-online-debug.md - In the quick start guides, replace third-party serial software with mbed sterm.
debug_intro.md - As a guide for exporting project to IDE, mbed sterm does not really belong there.
debug_with_printf.md - This is now a pure printf guide that does not duplicate info in serial communication.

Note: minimal-printf is linked in debug_with_printf.md as before. Also, it's now the default printf implementation (ARMmbed/mbed-os#12233) so we shouldn't need to reiterate much in my opinion.

docs/program-setup/serial/serial_communication.md

docs/quick-start/quick-start-cli-debug.md

docs/quick-start/quick-start-online-debug.md

docs/quick-start/quick-start-cli-debug.md

docs/quick-start/quick-start-online-debug.md

Co-authored-by: Hugues Kamba <41612201+hugueskamba@users.noreply.github.com>

LDong-Arm

@hugueskamba Thanks for the suggestions, I'll address them

docs/program-setup/serial/serial_communication.md

LDong-Arm · 2020-05-19T13:39:05Z

Hi @iriark01, this PR cleans up outdated info and refactors duplications in multiple docs, would you please have a look? Thanks

docs/program-setup/serial/serial_communication.md

evedon

I did not see the reference to minimal-printf in debug_with_printf.md. If it is not there, then we should add a link.

evedon · 2020-05-19T16:02:29Z

docs/quick-start/quick-start-online-debug.md

@@ -1,25 +1,21 @@
-<h1 id="debug-ide-qs">Debugging the quick start</h1>
+<h1 id="debug-ide-qs">Debugging with the Online Compiler</h1>


There is a lot of similarities with cli debug. I think it would be better to combine the two pages.
What do you think @iriark01 ?

I personally agree - the quick start pages are rather brief, maybe CLI and online compiler can go into different sections of one page

People using one tool don't like having to read through instructions/info for another tool. And sometimes they don't even realise it's there so they assume it's missing.

@iriark01 I understand if the instructions are quite different and long. In this case it is rather short and it would remove the duplication. I thought you combined instructions for blinky bare metal ; this would be another example of combined instructions.

The current documentation layout on the website

Quick start |- Introduction |- Online with the online compiler |- Importing and compiling the code |- Debugging with the online compiler * |- Offline with Mbed CLI |- Setting up and compiling the code |- Debugging with Mbed CLI * |- Further reading * what this PR touches

Maybe, we can rename both "Debugging with ..." to "Exporting to a desktop IDE", and factor out "Using printf" (and how to drag & drop an image) into a separate page "Debugging"? It would still look natural in my personal opinion.

I combined bare metal and the full profile, but not into the same tool. The tools are seen as very separate beasts - Mbed Studio actually has its own site.

I would argue that the problem here is that there's no real value to having either of these pages in the quick start. Debugging and exporting are both covered in much greater detail elsewhere in the docs.

@LDong-Arm please can you use a branch on this repo rather than a fork? That will generate a preview of the docs site with your changes, which will make this discussion much easier.

LDong-Arm · 2020-05-19T16:32:16Z

I did not see the reference to minimal-printf in debug_with_printf.md. If it is not there, then we should add a link.

It already contains

<span class="notes">**Note:** For printf-related memory considerations, please read our documentation about [printf and reducing memory](../apis/platform-tutorials.html#printf-and-reducing-memory).</span>

which explains minimal-printf. It's not introduced by this PR.

Co-authored-by: Hugues Kamba <41612201+hugueskamba@users.noreply.github.com>

iriark01 · 2020-05-20T07:50:52Z

So is this ready for me, or still waiting on engineering?

LDong-Arm · 2020-05-20T09:33:25Z

So is this ready for me, or still waiting on engineering?

It's ready for you to review, thanks

docs/program-setup/serial/serial_communication.md

iriark01 · 2020-05-20T12:02:51Z

docs/program-setup/serial/serial_communication.md

 - Read input from the host PC keyboard.
- Communicate with applications and programming languages running on the host PC that can communicate with a serial port. Examples are Perl, Python and Java.
+- Communicate with applications running on the host computer to exchange data.


It needs to be either "host computer" or "host PC" consistently. Although I might just go with "PC" or "computer" - does the word "host" really clarify anything?

It's a leftover from the old documentation, I'll remove it

docs/program-setup/serial/serial_communication.md

iriark01 · 2020-05-20T12:05:15Z

docs/program-setup/serial/serial_communication.md

- [PuTTY](http://www.chiark.greenend.org.uk/~sgtatham/putty/).
- Some Windows PCs come with **Hyperterminal** installed.
+Messages printed after this point will be displayed, restart the application using the board's reset button or press `Ctrl + B` on the serial terminal.
+The console prints "Hello World!" to the terminal after the reset.


We haven't used the word "console" until now. What does it refer to?

Good catch, it should be "example"

docs/program-setup/serial/serial_communication.md

docs/quick-start/quick-start-cli-debug.md

iriark01 · 2020-05-20T12:10:41Z

docs/quick-start/quick-start-online-debug.md


-1. **On Windows**:
+<span class="notes">**Note:** Unless otherwise specified, `printf` defaults to a baud rate of `9600` on Mbed OS. You can modify this value in the `mbed_app.json` file. To configure your terminal client to this baud rate, change the speed option when selecting the port. You can view the [configuration options page](../reference/configuration.html) to learn more about how to configure OS-level options.</span>


This is sort of related to my earlier question about baud rate

LDong-Arm · 2020-05-21T12:58:30Z

@iriark01 Thanks for the suggestions, I will move the work to a branch in this repo

Co-authored-by: Irit Arkin <irit.arkin@arm.com>

LDong-Arm added 4 commits May 15, 2020 12:37

Update serial communication

c3f4b37

Quick start: use mbed sterm instead of third-party monitors

7f461a1

Usage of serial comm does not belong to "Exporting your project"

0a55715

Remove duplicated and outdated info of serial comm from printf page

7dbd02e

hugueskamba reviewed May 15, 2020

View reviewed changes

Apply suggestions from @hugueskamba

7f8ba37

Co-authored-by: Hugues Kamba <41612201+hugueskamba@users.noreply.github.com>

LDong-Arm commented May 19, 2020

View reviewed changes

docs/program-setup/serial/serial_communication.md Show resolved Hide resolved

docs/program-setup/serial/serial_communication.md Outdated Show resolved Hide resolved

docs/program-setup/serial/serial_communication.md Outdated Show resolved Hide resolved

Improvements based on comments from @hugueskamba

04e7a53

LDong-Arm requested review from hugueskamba, evedon and iriark01 May 19, 2020 13:36

iriark01 self-assigned this May 19, 2020

hugueskamba reviewed May 19, 2020

View reviewed changes

docs/program-setup/serial/serial_communication.md Outdated Show resolved Hide resolved

evedon reviewed May 19, 2020

View reviewed changes

Fix missing determiner "a" in serial_communication

91fbd10

Co-authored-by: Hugues Kamba <41612201+hugueskamba@users.noreply.github.com>

iriark01 suggested changes May 20, 2020

View reviewed changes

Apply suggestions from @iriark01

128f5a8

Co-authored-by: Irit Arkin <irit.arkin@arm.com>

LDong-Arm mentioned this pull request May 21, 2020

Update serial communication and clean up duplicated & outdated info #1326

Merged

LDong-Arm closed this May 21, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update serial communication and clean up duplicated & outdated info #1317

Update serial communication and clean up duplicated & outdated info #1317

LDong-Arm commented May 15, 2020 •

edited

Loading

LDong-Arm left a comment

LDong-Arm commented May 19, 2020

evedon left a comment

evedon May 19, 2020

LDong-Arm May 19, 2020

iriark01 May 20, 2020

evedon May 20, 2020

LDong-Arm May 20, 2020

iriark01 May 20, 2020

LDong-Arm commented May 19, 2020

iriark01 commented May 20, 2020

LDong-Arm commented May 20, 2020

iriark01 May 20, 2020

LDong-Arm May 21, 2020

iriark01 May 20, 2020

LDong-Arm May 21, 2020 •

edited

Loading

iriark01 May 20, 2020

LDong-Arm commented May 21, 2020

		@@ -1,25 +1,21 @@
		<h1 id="debug-ide-qs">Debugging the quick start</h1>
		<h1 id="debug-ide-qs">Debugging with the Online Compiler</h1>


		1. On Windows:
		<span class="notes">Note: Unless otherwise specified, `printf` defaults to a baud rate of `9600` on Mbed OS. You can modify this value in the `mbed_app.json` file. To configure your terminal client to this baud rate, change the speed option when selecting the port. You can view the [configuration options page](../reference/configuration.html) to learn more about how to configure OS-level options.</span>

Update serial communication and clean up duplicated & outdated info #1317

Update serial communication and clean up duplicated & outdated info #1317

Conversation

LDong-Arm commented May 15, 2020 • edited Loading

LDong-Arm left a comment

Choose a reason for hiding this comment

LDong-Arm commented May 19, 2020

evedon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LDong-Arm commented May 19, 2020

iriark01 commented May 20, 2020

LDong-Arm commented May 20, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LDong-Arm May 21, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LDong-Arm commented May 21, 2020

LDong-Arm commented May 15, 2020 •

edited

Loading

LDong-Arm May 21, 2020 •

edited

Loading