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

LDong-Arm · 2020-05-21T15:12:52Z

This replaces #1317.

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

LDong-Arm · 2020-05-21T15:16:44Z

Hi @iriark01 I created this to replace #1317 so we can preview the code. I also addressed some comments from there, please review.

Continuing our discussions, shall we remove debugging & exporting to IDEs from quick start?

iriark01 · 2020-05-21T15:38:45Z

I think we should, yes. If the content is needed, it should be in the debugging area.

It would be a different matter if we had specific debugging info just for the quick start (for example, if Blinky had some commented-out broken lines that people could uncomment so we could walk them through debugging). But since it's standard printf() info we should just point to a good, single-source-of-truth page on printf().

LDong-Arm · 2020-05-21T16:30:45Z

@iriark01 I just removed the debugging pages in my last commit. The existing "Further reading" page of the quick start already links to debugging & serial communication docs, so I'm not adding extra links.

iriark01

Minor edits. I'm also building the branch so I can check that everything renders correctly, but I'll fix rendering issues without going through engineering approval again.

docs/program-setup/serial/serial_communication.md

docs/tools/debug/debug_with_printf.md

LDong-Arm · 2020-05-22T09:53:53Z

It looks like Travis failed because this needs a rebase to have the json fix (#1324):

Validating json ./docs/bare_metal/using_bare_metal.md:57 ...
Expecting property name: line 5 column 13 (char 90)
The command "./check_tools/find_bad_code_snippets.sh" exited with 1.

iriark01 · 2020-05-22T09:57:31Z

But it will be fine once I merge it; the fix is already on "development", right?

LDong-Arm · 2020-05-22T09:59:28Z

But it will be fine once I merge it; the fix is already on "development", right?

True

iriark01 · 2020-05-22T10:51:10Z

So I think we just need Evelyne's review

This is an attempt - I may make further changes

LDong-Arm · 2020-05-26T13:53:00Z

@iriark01 There were a number of merge conflicts since the development branch changed. I tried to rebase this PR myself but I'm not sure if I did it correctly. Could you double check, especially the links/redirect, etc.?

(If I messed things up, please revert to 20eb660, the hash before the rebase.)

Thanks.

iriark01 · 2020-05-26T14:09:50Z

That commit looks fine.

evedon · 2020-05-26T13:48:23Z

docs/program-setup/serial/serial_communication.md


-### Configuring the connection
+- If you have multiple boards connected:
+    1. Run `mbedls` to find the port of the board you want to use.


It's probably worth linking to https://github.com/ARMmbed/mbed-os-tools/blob/master/packages/mbed-ls/README.md

I cannot find any page for mbedls on Mbed OS's documentation site. The info in the link seems outdated as it says "Development moved", and the steps to install this command don't apply anymore since mbedls is now included in Mbed CLI suite.

docs/program-setup/serial/serial_communication.md

evedon · 2020-05-26T14:08:14Z

docs/program-setup/serial/serial_communication.md


-## Minimal Printf
+```
+mbed compile -t <TOOLCHAIN> -m <TARGET> --flash --sterm


You could also show usage of -m detect

It's a nice tip. But -m detect seems like an undocumented feature (not shown in mbed compile --help), so I'm not sure if we should suggest it.

docs/tools/debug/debugging_mbed_os_apps.md

docs/program-setup/serial/serial_communication.md

LDong-Arm · 2020-05-26T15:59:43Z

Hi @evedon, @iriark01, I just addressed latest comments from @evedon, please review the last three commits. Thanks.

docs/program-setup/serial/serial_communication.md

iriark01 · 2020-05-27T06:44:49Z

docs/program-setup/serial/serial_communication.md

+
+<span class="notes">**Notes:**
+- If your application uses a baud rate other than 9600, specify it with `-b <BAUDRATE>` in the command above.
+- This method only works if _one_ board of the TARGET you specify is connected. To work with multiple boards, open a serial terminal manually as described below.</span>


Suggested change

- This method only works if _one_ board of the TARGET you specify is connected. To work with multiple boards, open a serial terminal manually as described below.</span>

<br/>- This method only works for a single board. To work with multiple boards, open a serial terminal manually as described below.</div>

I removed the bit about the target because it implied you could make this work for multiple boards of different targets, and we don't explain that.

As a user this will annoy me. You send me to "Manually opening a serial terminal" which then sends me to "Additional options" which explains how to connect multiple boards. Is there a way we can make this smoother? Since the two things explained in "Additional options" are how to use multiple boards and how to specify a baud rate (which you explained above), I think we can maybe we can do away with that bit. The --help bit can then have its own title or just be mentioned as a tip (we don't have to show output for --help).

I agree we drop the "Additional options" section and replace it with a tip which is more compact.

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

iriark01

Just some tidying of the note - a DIV makes it HTML instead of Markdown so it needs more manual handling

docs/program-setup/serial/serial_communication.md

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

LDong-Arm · 2020-05-27T11:00:49Z

@iriark01 Thanks, the format looks better now

iriark01 · 2020-05-27T11:25:53Z

Let's merge it and I'll clean it up after, because it's a bit funny in the preview. Is that okay?

LDong-Arm · 2020-05-27T11:35:13Z

Sure, sounds good to me

iriark01 · 2020-05-27T11:39:24Z

Thank you very much for this PR!

LDong-Arm · 2020-05-27T13:52:56Z

Thanks for your help too!

LDong-Arm mentioned this pull request May 21, 2020

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

Closed

LDong-Arm requested review from iriark01 and evedon May 21, 2020 15:14

iriark01 suggested changes May 22, 2020

View reviewed changes

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

docs/tools/debug/debug_with_printf.md Outdated Show resolved Hide resolved

docs/tools/debug/debug_with_printf.md Outdated Show resolved Hide resolved

LDong-Arm requested a review from iriark01 May 22, 2020 09:32

iriark01 approved these changes May 22, 2020

View reviewed changes

LDong-Arm and others added 3 commits May 26, 2020 14:36

Update serial communication

6b7d247

Cleaning up links, titles, redirects

6ba3a6c

Tidying up debugging since material moved

6a804f1

This is an attempt - I may make further changes

LDong-Arm force-pushed the serial_comm_cleanup branch from 20eb660 to 6a804f1 Compare May 26, 2020 13:49

LDong-Arm requested a review from iriark01 May 26, 2020 14:09

evedon reviewed May 26, 2020

View reviewed changes

Serial communication: explain mbed compile first; improve explanation

e0ce9f5

LDong-Arm commented May 26, 2020

View reviewed changes

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

Debugging methods: links to printf and serial communication

ca73f8d

evedon approved these changes May 26, 2020

View reviewed changes

debugging_mbed_os_apps.md: serial monitor -> serial terminal

47d9e64

iriark01 suggested changes May 27, 2020

View reviewed changes

LDong-Arm and others added 2 commits May 27, 2020 11:14

Apply suggestions from code review

1255707

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

Fix formatting

556793e

serial communication: convert additional options section to note

eec3871

iriark01 approved these changes May 27, 2020

View reviewed changes

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

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

LDong-Arm commented May 27, 2020

View reviewed changes

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

LDong-Arm and others added 2 commits May 27, 2020 11:54

Apply suggestions from code review

b02ce87

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

Remove < and > unsupported in div

e2a611e

iriark01 merged commit 4138d04 into development May 27, 2020

LDong-Arm deleted the serial_comm_cleanup branch May 27, 2020 13:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

LDong-Arm commented May 21, 2020

LDong-Arm commented May 21, 2020

iriark01 commented May 21, 2020

LDong-Arm commented May 21, 2020

iriark01 left a comment

LDong-Arm commented May 22, 2020

iriark01 commented May 22, 2020

LDong-Arm commented May 22, 2020

iriark01 commented May 22, 2020

LDong-Arm commented May 26, 2020 •

edited

Loading

iriark01 commented May 26, 2020

evedon May 26, 2020

LDong-Arm May 26, 2020

evedon May 26, 2020

LDong-Arm May 26, 2020

LDong-Arm commented May 26, 2020 •

edited

Loading

iriark01 May 27, 2020

iriark01 May 27, 2020

iriark01 May 27, 2020

LDong-Arm May 27, 2020

iriark01 left a comment

LDong-Arm commented May 27, 2020

iriark01 commented May 27, 2020

LDong-Arm commented May 27, 2020

iriark01 commented May 27, 2020

LDong-Arm commented May 27, 2020

	- This method only works if _one_ board of the TARGET you specify is connected. To work with multiple boards, open a serial terminal manually as described below.</span>
	<br/>- This method only works for a single board. To work with multiple boards, open a serial terminal manually as described below.</div>

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

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

Conversation

LDong-Arm commented May 21, 2020

LDong-Arm commented May 21, 2020

iriark01 commented May 21, 2020

LDong-Arm commented May 21, 2020

iriark01 left a comment

Choose a reason for hiding this comment

LDong-Arm commented May 22, 2020

iriark01 commented May 22, 2020

LDong-Arm commented May 22, 2020

iriark01 commented May 22, 2020

LDong-Arm commented May 26, 2020 • edited Loading

iriark01 commented May 26, 2020

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 26, 2020 • edited Loading

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

iriark01 left a comment

Choose a reason for hiding this comment

LDong-Arm commented May 27, 2020

iriark01 commented May 27, 2020

LDong-Arm commented May 27, 2020

iriark01 commented May 27, 2020

LDong-Arm commented May 27, 2020

LDong-Arm commented May 26, 2020 •

edited

Loading

LDong-Arm commented May 26, 2020 •

edited

Loading