Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 8 commits into from
Closed

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c3f4b37
Update serial communication
LDong-Arm May 14, 2020
7f461a1
Quick start: use mbed sterm instead of third-party monitors
LDong-Arm May 15, 2020
0a55715
Usage of serial comm does not belong to "Exporting your project"
LDong-Arm May 15, 2020
7dbd02e
Remove duplicated and outdated info of serial comm from printf page
LDong-Arm May 15, 2020
7f8ba37
Apply suggestions from @hugueskamba
LDong-Arm May 19, 2020
04e7a53
Improvements based on comments from @hugueskamba
LDong-Arm May 19, 2020
91fbd10
Fix missing determiner "a" in serial_communication
LDong-Arm May 19, 2020
128f5a8
Apply suggestions from @iriark01
LDong-Arm May 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 44 additions & 36 deletions docs/program-setup/serial/serial_communication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,57 +6,71 @@ The Arm Mbed microcontroller on your board can communicate with a host PC over t

This allows you to:

- Print out messages to a [host PC terminal (useful for debugging)](#terminal-applications).
- Print out messages to a host PC terminal (useful for debugging).
- 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Hello, world
## Hello World - printing messages

This program prints a "Hello World" message that you can view on a [terminal application](#using-terminal-applications). Communication over the USB serial port uses the standard serial interface. Specify the internal (USBTX, USBRX) pins to connect to the serial port routed over USB:
This program prints a "Hello World!" message that you can view on a serial terminal. Mbed OS redirects any `printf()` statements to the board's debug USB serial.

[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_HelloWorld/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_HelloWorld/main.cpp)
[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_STDOUT/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_STDOUT/main.cpp)

### Viewing output in a serial terminal

## Using terminal applications
Serial terminals run on your host PC. They provide an interface where your Mbed board can print and where you can type characters back to your board.

Terminal applications run on your host PC. They provide a window where your Mbed board can print and where you can type characters back to your board.
Mbed CLI provides a serial terminal that is configured with a default baud rate of `9600`. When a single board is connected, run:

<span class="tips">**Serial configuration:** The standard setup for the USB serial port is 9600 baud, 8 bits, 1 stop bit, no parity (9600-8-N-1)</span>
```
mbed sterm
```

### Installing an application for Windows
(If you have multiple boards connected, please refer to [Additional options of mbed sterm](#additional-options-of-mbed-sterm).)

There are many terminal applications for Windows, including:
`mbed sterm` starts message printing.

- [CoolTerm](http://freeware.the-meiers.org/) - this is the application we use in this example. We use it often because it usually "just works".
- [Tera Term](http://sourceforge.jp/projects/ttssh2/files).
- [PuTTY](http://www.chiark.greenend.org.uk/~sgtatham/putty/).
- Some Windows PCs come with **Hyperterminal** installed.
Restart the application using the board's reset button, or by entering <kbd>Ctrl + B</kbd> in the serial terminal.
The console prints "Hello World!" to the terminal after the reset.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@LDong-Arm LDong-Arm May 21, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, it should be "example"


### Configuring the connection
To close the serial terminal, enter <kbd>Ctrl + C</kbd>.

1. Plug in your Mbed board.
1. Open CoolTerm.
1. Click **Connect**. This opens up an 8-n-1 9600 baud connection to the first available serial port. If you have more than one board plugged in, you may need to change the port under **Options > Serial Port > Port**.
<span class="tips">**Tip:** To compile, flash and open a serial terminal in one command line, you can append `--flash --sterm` to `mbed compile`.</span>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems a little out of context.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's better to have a separate (short) section for it


Check your connection parameters:
## Additional options of mbed sterm

1. Select **Options > Serial Port**.
1. You should see 9600 baud, 8 bits, 1 stop bit, no parity (9600-8-N-1).
1. If you do not see your board, click **Re-Scan Peripherals**.
- If you have multiple boards connected:
1. Run `mbedls` to find the port of the board you want to use.
1. Run `mbed sterm -p <PORT>`.

Your terminal program is now configured and connected.
If your application uses a baud rate, specify with `-b <BAUDRATE>` when opening the serial terminal.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If your application uses a baud rate, specify with `-b <BAUDRATE>` when opening the serial terminal.
- If your application uses a baud rate, specify it with `-b <BAUDRATE>` when opening the serial terminal.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't they always use baud rate? Is it just if it's not the default set somewhere? Shouldn't it match the board?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will fix it


## Using terminal applications on Linux
- To list all options, run `mbed sterm -h`:

CoolTerm should work under Linux. If for some reason it doesn't, you can try one of the following:
```
usage: mbed sterm [-h] [-m TARGET] [-p PORT] [-b BAUDRATE] [-e ECHO] [-r] [-v] [-vv]

- [Minicom](https://help.ubuntu.com/community/Minicom).
- [GNU Screen](https://www.gnu.org/software/screen/manual/screen.html).
Open serial terminal to connected target (usually board), or connect to a user-specified COM port

## Minimal Printf
optional arguments:
-h, --help show this help message and exit
-m TARGET, --target TARGET
Compile target MCU. Example: K64F, NUCLEO_F401RE,
NRF51822...
-p PORT, --port PORT Communication port. Default: auto-detect. Specifying
this will also ignore the -m/--target option above.
-b BAUDRATE, --baudrate BAUDRATE
Communication baudrate. Default: 9600
-e ECHO, --echo ECHO Switch local echo on/off. Default: on
-r, --reset Reset the targets (via SendBreak) before opening
terminal.
-v, --verbose Verbose diagnostic output
-vv, --very_verbose Very verbose diagnostic output
```

For low memory devices you may optionally use the [ArmMbed minimal printf library](https://github.com/ARMmbed/minimal-printf).
## Additional examples - reading user inputs

# Additional examples
In addition to printing messages, Mbed OS applications can also read keyboard inputs from the user. This is achievable with the [BufferedSerial](../apis/bufferedserial.html) and [UnbufferedSerial](../apis/unbufferedserial.html) classes.

Use your terminal application to interact with the following examples.

Expand All @@ -80,12 +94,6 @@ Tie pins together to see characters echoed back.

[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_PassCharacters/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_PassCharacters/main.cpp)

## Using stdin, stdout and stderr

By default, the C `stdin`, `stdout` and `stderr file` handles map to the PC serial connection:

[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_STDOUT/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_STDOUT/main.cpp)

## Read to a buffer

[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_ReadToBuffer/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_SerialComm/Serial_ReadToBuffer/main.cpp)
13 changes: 11 additions & 2 deletions docs/quick-start/quick-start-cli-debug.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,21 @@

## Using printf

The easiest way to do basic debugging is to use the `printf` command in your code, then read the output using a serial terminal, such as [PuTTY](http://www.putty.org/) or [CoolTerm](http://freeware.the-meiers.org/).
The easiest way to do basic debugging is to use the `printf` function in your code, then read the output using a serial terminal.

For example, add `printf("Hello World!\n\r");` to the top of your main function, and then recompile the program and flash it to your device.
For example, add `printf("Hello World!\n");` to the top of your main function, and then recompile the program and flash it to your device. To view the output, open a serial terminal:
```
mbed sterm
```

You may need to reset the board, because messages are visible only if printed while the terminal is open.

To close the serial terminal, enter <kbd>Ctrl + C</kbd>.

<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](../program-setup/advanced-configuration.html) to learn more about how to configure OS-level options.</span>

For more `mbed sterm` options, see [Board to PC communication over USB](../tutorials/serial-comm.html).

## Exporting to a desktop IDE

To debug using a desktop IDE such as Keil uVision, IAR or Eclipse, use the `mbed export` command to generate project files.
Expand Down
24 changes: 10 additions & 14 deletions docs/quick-start/quick-start-online-debug.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


## Using printf

The easiest way to do basic debugging is to use the `printf` command in your code, then read the output using a serial terminal, such as [PuTTY](http://www.putty.org/) or [CoolTerm](http://freeware.the-meiers.org/).
The easiest way to do basic debugging is to use the `printf` function in your code, then read the output using a serial terminal.

For example, add `printf("Hello World!\n\r");` to the top of your main function, and then recompile the program and flash it to your device.
For example, add `printf("Hello World!\n");` to the top of your main function, and then recompile the program and flash it to your device. To view the output, open a serial terminal:
```
mbed sterm
```

<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](../program-setup/advanced-configuration.html) to learn more about how to configure OS-level options.</span>
You may need to reset the board, because messages are visible if printed while the terminal is open.

To determine which communication port your board connects to:
To close the serial terminal, press Ctrl + C.

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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


1. Open the Device Manager by pressing <kbr>Windows key</kbr> + <kbr>R</kbr>.
1. Enter `devmgmt.msc`.
1. Click **OK**.
1. Under **Ports (COM & LPT)**: your Mbed board is listed as a `USB Serial Device` next to its COM port.

1. **On Linux**: Run `dmesg | grep tty` from your command-line.

1. **On macOS**: Run `ls /dev/tty.*` from your command-line.
For more options of `mbed sterm`, see [Board to PC communication over USB](../tutorials/serial-comm.html).

## Exporting to a desktop IDE

Expand Down
28 changes: 0 additions & 28 deletions docs/tools/debug/debug_intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,34 +27,6 @@ In your project folder, run:
$ mbed export -i make_gcc_arm -m K64F
```

#### Serial terminal

You can open a serial terminal to the COM port of a connected Mbed target (usually board) using the `mbed sterm` command. If no COM port is specified, Mbed CLI detects the connected Mbed targets and their COM ports.

There are various options to `mbed sterm`:

- `--port <COM port>` to specify system COM port to connect to.
- `--baudrate <numeric>` to select the communication baudrate, where the default value is 9600.
- `--echo <on|off>` to switch local echo (default is `on`).
- `--reset` to reset the connected target by sending Break before opening the serial terminal.

You can also set default port, baudrate and echo mode using the `TERM_PORT`, `TERM_BAUDRATE` and `TERM_ECHO` Mbed CLI configuration options.

The following shortcuts are available within the serial terminal:

- Ctrl+b - Send Break (reset target).
- Ctrl+c - Exit terminal.
- Ctrl+e - Toggle local echo.
- Ctrl+h - Help.
- Ctrl+t - Menu escape key.
- _You can view more shortcuts within the serial terminal's help menu (Ctrl+h)._

You can also add the `--sterm` option to `mbed compile -f` to compile a new program, flash the program or firmware image to the connected target and then open the serial terminal to its COM port:

```
$ mbed compile -t GCC_ARM -m K64F -f --sterm
```

## Building your project

You can now configure your IDE to build this project by setting the build command to:
Expand Down
102 changes: 3 additions & 99 deletions docs/tools/debug/debug_with_printf.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,110 +1,14 @@
# Debugging using printf() statements

An easy way to inspect what your application is doing is to augment your application with log statements. In Arm Mbed, you can use a serial connection to send feedback from your development board back to your computer. This uses the same USB cable that you use to program your device.
An easy way to inspect what your application is doing is to augment your application with `printf()` statements. In Arm Mbed, you can use a serial connection to send feedback from your development board back to your computer.

## Prerequisites

### Windows

Install the serial port driver for your development board:

- For ST boards: [ST Link Driver](https://os.mbed.com/teams/ST/wiki/ST-Link-Driver).
- For all other boards: [Arm Mbed Windows serial port driver](../program-setup/windows-serial-driver.html) - not required for Windows 10.

You also need a serial monitor:

- [TeraTerm](http://sourceforge.jp/projects/ttssh2/files).

### macOS

On macOS, all software comes installed by default.

### Linux

If you do not have it, install [GNU Screen](https://www.gnu.org/software/screen/).

## Getting started

To send data over the serial connection, use the [BufferedSerial](../apis/serial-uart-apis.html) object.

### Example program

This program blinks the LED on your development board and prints a message every time the LED changes state:

[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_Debugging/DebugPrintf_BlinksLED/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_Debugging/DebugPrintf_BlinksLED/main.cpp)


Compile this program, and flash it on your development board. You now can inspect these messages using a serial monitor.

### Seeing the log messages

### Windows

1. Open TeraTerm.
1. Click *File > New Connection*.
1. Select the *Serial* radio button.
1. Choose your development board from the drop-down menu (often called `mbed Serial Port` or `STLink Virtual Port`).
1. Click *OK*.
1. Log messages appear in the main window.

<span class="images">![](../../images/printf1.png)<span>Selecting the COM port</span></span>

<span class="images>"![](../../images/printf2.png)<span>Seeing the output over the serial port</span></span>

<span class="notes">**Note:** Unsure which COM port is used? In the [device manager](http://www.computerhope.com/issues/ch000833.htm), look under the *Ports* section.</span>

### macOS

1. Open a terminal window.
1. Enter `screen /dev/tty.usbm`, and press `Tab` to autocomplete.
1. Press `Enter`.
1. Log messages appear.
1. To exit, press:
- `Ctrl+A`
- `Ctrl+\`
- `y`

### Linux

1. Open a terminal window.
1. Find the handler for your device:

```
$ ls /dev/ttyACM*
/dev/ttyACM0
```

1. Connect to the board by entering `sudo screen /dev/ttyACM0 9600`.
1. Log messages appear.
1. To exit:
1. Press `Ctrl+A`.
1. Enter `quit`.

<span class="notes">**Note:** To avoid using `sudo`, set up a udev rule.</span>

### Setting the baud rate

By default, the speed at which the microcontroller and your computer communicate (the baud rate) is set to 9600 baud. This setting fits most use cases, but you can change it by calling the `baud` function on the serial object:

[![View code](https://www.mbed.com/embed/?url=https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_Debugging/DebugPrintf_SetBaudRate/)](https://github.com/ARMmbed/mbed-os-examples-docs_only/blob/master/Tutorials_Debugging/DebugPrintf_SetBaudRate/main.cpp)


If you change the baud rate on the device, you also need to change it on your serial monitor:

1. Windows:
1. In TeraTerm, go to *Setup > Serial Port*.
1. Change *Baud rate* to 115200.
1. macOS and Linux: Pass the baud rate as the last argument to the `screen` command:

```
$ screen /dev/ttyACM0 115200
```

<span class="images">![](../../images/printf3.png)<span>Changing the baud rate</span></span>
For a tutorial on setting up serial communication, see [Board to PC communication over USB](tutorials/serial-comm.html).

## Printf()

As seen above, you use the `printf()` function to communicate back to the user:
The `printf()` function is the recommended way to communicate back to the user:

1. The `printf()` functions produce output according to a format string (containing format specifiers) and matching value arguments.
2. The microcontroller's universal asynchronous receiver/transmitter (UART) console peripheral "feeds" output from `printf()` into the interface chip.
Expand Down