Merge branch 'bugfix/uart_examples_match_template' into 'master'

examples: Fix UART examples to match the template

See merge request idf/esp-idf!3642

examples/peripherals/uart_async_rxtxtasks/README.md

@@ -1,21 +1,65 @@
-UART asynchronous example, that uses separate RX and TX tasks
-=============================================================
+# UART Asynchronous Example with Separate Receive and Transfer Tasks
 
-Starts two FreeRTOS tasks:
-  - One task for transmitting 'Hello world' via the UART.
-  - One task for receiving from the UART.
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
 
-If you'd like to see your ESP32 receive something, simply short
-TXD_PIN and RXD_PIN. By doing this data transmitted on TXD_PIN will
-be received on RXD_PIN. See the definitions of TXD_PIN and RXD_PIN
-in ./main/uart_async_rxtxtasks_main.c.
+This example demonstrates how two asynchronous tasks can use the same UART interface for communication. One can use
+this example to develop more complex applications for serial communication.
 
-The output for such configuration will look as follows: 
+The example starts two FreeRTOS tasks:
+1. The first task periodically transmits `Hello world` via the UART.
+2. The second task task listens, receives and prints data from the UART.
 
+## How to use example
+
+### Hardware Required
+
+The example can be run on any commonly available ESP32 development board. You will need a USB cable to connect the
+development board to a computer, and a simple one-wire cable for shorting two pins of the board.
+
+### Setup the Hardware
+
+The `RXD_PIN` and `TXD_PIN` which are configurable in the code (by default `GPIO4` and `GPIO5`) need to be shorted in
+order to receive back the same data which were sent out.
+
+### Configure the project
+
+```
+make menuconfig
 ```
+or
+```
+idf.py menuconfig
+```
+
+* Set serial port under Serial Flasher Options.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+make -j4 flash monitor
+```
+or
+```
+idf.py flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+You will receive the following repeating output from the monitoring console:
+```
+...
 I (3261) TX_TASK: Wrote 11 bytes
 I (4261) RX_TASK: Read 11 bytes: 'Hello world'
 I (4261) RX_TASK: 0x3ffb821c   48 65 6c 6c 6f 20 77 6f  72 6c 64                 |Hello world|
 ...
 ```
-The third line above prints received data in hex format, that comes handy to display non printable data bytes.
+
+## Troubleshooting
+
+If you do not see any output from `RX_TASK` then check if you have the `RXD_PIN` and `TXD_PIN` pins shorted on the board.

examples/peripherals/uart_echo/README.md

@@ -1,10 +1,20 @@
 # UART Echo Example
 
-This is an example which echoes any data it receives on UART1 back to the sender.
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
 
-## Setup
+This example demonstrates how to utilize UART interfaces of ESP32 by echoing back to the sender any data received on
+UART1.
 
-1. Connect an external serial interface to an ESP32 board. The external interface should have 3.3V outputs. You may use e.g. 3.3V compatible USB-to-serial dongle:
+## How to use example
+
+### Hardware Required
+
+The example can be run on any ESP32 development board connected to a PC with a single USB cable for flashing and
+monitoring. The external interface should have 3.3V outputs. You may use e.g. 3.3V compatible USB-to-Serial dongle.
+
+### Setup the Hardware
+
+Connect the external serial interface to the ESP32 board as follows.
 
   | ESP32 Interface | #define | ESP32 Pin | External UART Pin |
   | --- | --- | --- | --- |
@@ -12,25 +22,52 @@ This is an example which echoes any data it receives on UART1 back to the sender
   | Receive Data (RxD) | ECHO_TEST_RXD | GPIO5 | TxD |
   | Ground | n/a | GND | GND |
 
-2. Compile and load the example to the ESP32 board
-3. Refer to the example and set up a serial terminal program to the same settings as of UART1 in ESP32
-4. Open the external serial interface in the terminal
-5. When typing any character in the terminal you should see it echoed back
-6. Verify if echo indeed comes from ESP32 by disconnecting either 'TxD' or 'RxD' pin. There should be no any echo once any pin is disconnected.
-
-## Using a hardware flow control
-
-This is an optional check to verify if the hardware flow control works. To set it up you need an external serial interface that has RTS and CTS signals. 
-
-1. Connect the extra RTS/CTS signals as below
+Optionally, you can set-up and use a serial interface that has RTS and CTS signals in order to verify that the
+hardware control flow works. Connect the extra signals according to the following table, configure both extra pins in
+the example code by replacing existing `UART_PIN_NO_CHANGE` macros with the appropriate pin numbers and configure
+UART1 driver to use the hardware flow control by setting `.flow_ctrl = UART_HW_FLOWCTRL_CTS_RTS` and adding
+`.rx_flow_ctrl_thresh = 122`.
 
   | ESP32 Interface | #define | ESP32 Pin | External UART Pin |
   | --- | --- | --- | --- |
   | Request to Send (RTS) | ECHO_TEST_RTS | GPIO18 | CTS |
   | Clear to Send (CTS) | ECHO_TEST_CTS | GPIO19 | RTS |
 
-2. Configure both extra pins in the example code by replacing existing `UART_PIN_NO_CHANGE` macros with the above pin numbers
-3. Configure UART1 driver to use the hardware flow control by setting `.flow_ctrl = UART_HW_FLOWCTRL_CTS_RTS` and adding `.rx_flow_ctrl_thresh = 122`
-4. Repeat tests described in 'Setup' above starting from step 3
+### Configure the project
+
+```
+make menuconfig
+```
+or
+```
+idf.py menuconfig
+```
+
+* Set serial port under Serial Flasher Options.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+make -j4 flash monitor
+```
+or
+```
+idf.py flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+Type some characters in the terminal connected to the external serial interface. As result you should see echo in the
+terminal which is used for flashing and monitoring. You can verify if the echo indeed comes from ESP32 by
+disconnecting either `TxD` or `RxD` pin: no characters will appear when typing.
+
+## Troubleshooting
 
-See the README.md file in the upper level 'examples' directory for more information about examples.
+You are not supposed to see the echo in the terminal which is used for flashing and monitoring, but in the other one
+which is connected to UART1.

examples/peripherals/uart_echo_rs485/README.md

@@ -1,14 +1,18 @@
 # UART RS485 Echo Example
 
-This is an example which echoes any data it receives on UART2 back to the sender in the RS485 network. 
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This is an example which echoes any data it receives on UART2 back to the sender in the RS485 network.
 It uses ESP-IDF UART software driver in RS485 half duplex transmission mode and requires external connection of bus drivers.
 The approach demonstrated in this example can be used in user application to transmit/receive data in RS485 networks.
 
-## Hardware required :
-PC + USB Serial adapter connected to USB port + RS485 line drivers + ESP32 WROVER-KIT board. 
+## How to use example
+
+### Hardware Required
+PC + USB Serial adapter connected to USB port + RS485 line drivers + ESP32-WROVER-KIT board.
 The MAX485 line driver is used for example below but other similar chips can be used as well.
 
-### RS485 example connection circuit schematic:
+#### RS485 example connection circuit schematic:
 ```
          VCC ---------------+                               +--------------- VCC
                             |                               |
@@ -16,22 +20,21 @@ The MAX485 line driver is used for example below but other similar chips can be
          RXD <------| RO            |               |             RO|-----> RXD
                     |              B|---------------|B              |
          TXD ------>| DI  MAX485    |    \  /       |    MAX485   DI|<----- TXD
-ESP32 WROVER-KIT    |               |   RS-485 side |               |  SERIAL ADAPTER SIDE
+ESP32-WROVER-KIT    |               |   RS-485 side |               |  SERIAL ADAPTER SIDE
          RTS --+--->| DE            |    /  \       |             DE|---+
                |    |              A|---------------|A              |   |
                +----| /RE           |               |            /RE|---+-- RTS
                     +-------x-------+               +-------x-------+
                             |                               |
-                           ---                             --- 
-```         
-
-## How to setup and use an example:
+                           ---                             ---
+```
 
-### Connect an external RS485 serial interface to an ESP32 board.
+#### Connect an external RS485 serial interface to an ESP32 board
 ```
   ----------------------------------------------------------------------
   | ESP32 Interface       | #define       | ESP32 Pin | External RS485 |
-  | ----------------------|---------------|-----------| Driver Pin     |
+  |                       |               |           |   Driver Pin   |
+  | ----------------------|---------------|-----------|----------------|
   | Transmit Data (TxD)   | ECHO_TEST_TXD | GPIO23    | DI             |
   | Receive Data (RxD)    | ECHO_TEST_RXD | GPIO22    | RO             |
   | Request To Send (RTS) | ECHO_TEST_RTS | GPIO18    | ~RE/DE         |
@@ -40,27 +43,35 @@ ESP32 WROVER-KIT    |               |   RS-485 side |               |  SERIAL AD
 ```
 Connect USB to RS485 adapter to computer and connect its D+, D- output lines with the D+, D- lines of RS485 line driver connected to ESP32 (See picture above).
 
-### Configure the application
+### Configure the project
 ```
 make menuconfig
 ```
-* Set serial port under Serial Flasher Options to the serial port of ESP32 WROVER-KIT board.
+or
+```
+idf.py menuconfig
+```
+* Set serial port under Serial Flasher Options to the serial port of ESP32-WROVER-KIT board.
 
-### Build and flash software
+### Build and Flash
 Build the project and flash it to the board, then run monitor tool to view serial output:
 ```
 make -j4 flash monitor
 ```
+or
+```
+idf.py flash monitor
+```
 
 (To exit the serial monitor, type ``Ctrl-]``.)
 
 See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
 
-### Setup external terminal software 
-Refer to the example and set up a serial terminal program to the same settings as of UART in ESP32 WROVER-KIT BOARD.
-Open the external serial interface in the terminal. By default if no any symbols received the application sends character "." to check transmission side. 
-When typing message and push send button in the terminal you should see the message "RS485 Received: [ your message ], where your message is the message you sent from terminal.
-Verify if echo indeed comes from ESP32 by disconnecting either 'TxD' or 'RxD' pin. There should be no any "." once TxD pin is disconnected.
+#### Setup external terminal software
+Refer to the example and set up a serial terminal program to the same settings as of UART in ESP32-WROVER-KIT board.
+Open the external serial interface in the terminal. By default if no any symbols are received, the application sends character `.` to check transmission side.
+When typing message and push send button in the terminal you should see the message `RS485 Received: [ your message ]`, where "your message" is the message you sent from terminal.
+Verify if echo indeed comes from ESP32 by disconnecting either `TxD` or `RxD` pin. Once done there should be no any `.` displayed.
 
 ## Example Output
 Example output of the application:
@@ -68,10 +79,10 @@ Example output of the application:
 I (655020) RS485_ECHO_APP: Received 12 bytes:
 [ 0x79 0x6F 0x75 0x72 0x20 0x6D 0x65 0x73 0x73 0x61 0x67 0x65 ]
 ```
-The received message is showed in HEX form in the brackets.
+The received message is showed in hexadecimal form in the brackets.
 
 ## Troubleshooting
-Most of the issues when example software does not show the '.' symbol related to connection errors of external RS485 interface. 
-Check the RS485 interface connection with the environment according to schematic above and restart the application. 
-Then start terminal software and open appropriate serial port.
+When example software does not show the `.` symbol, the issue is most likely related to connection errors of the external RS485 interface.
+Check the RS485 interface connection with the environment according to schematic above and restart the application.
+Then start terminal software and open the appropriate serial port.
 

examples/peripherals/uart_events/README.md

@@ -1,10 +1,56 @@
 # UART Events Example
 
-This example shows how to use the UART driver to handle special UART events. It also reads data from UART0 directly, and echoes it to console.
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
 
-# How to use it?
+This example shows how to use the UART driver to handle special UART events. It also reads data from `UART0` directly,
+and echoes it back to the monitoring console.
 
-1. Compile and load example from terminl running `make flash monitor`
-2. Being in 'monotor' type samething to see the `UART_DATA` events and the typed data displayed.
+## How to use example
 
-See the README.md file in the upper level 'examples' directory for more information about examples.
+### Hardware Required
+
+The example can be used with any ESP32 development board connected to a computer with a USB cable.
+
+### Configure the project
+
+```
+make menuconfig
+```
+or
+```
+idf.py menuconfig
+```
+
+* Set serial port under Serial Flasher Options.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+make -j4 flash monitor
+```
+or
+```
+idf.py flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+Pushing `a` followed by a `b` on the keyboard will generate the following output:
+```
+...
+I (0) cpu_start: Starting scheduler on APP CPU.
+I (299) uart: queue free spaces: 20
+I (2249) uart_events: uart[0] event:
+I (2249) uart_events: [UART DATA]: 1
+I (2249) uart_events: [DATA EVT]:
+aI (12089) uart_events: uart[0] event:
+I (12089) uart_events: [UART DATA]: 1
+I (12089) uart_events: [DATA EVT]:
+b
+```

examples/peripherals/uart_select/README.md

@@ -1,5 +1,7 @@
 # UART Select Example
 
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
 The UART select example is for demonstrating the use of `select()` for
 synchronous I/O multiplexing on the UART interface. The example waits for a
 character from UART using `select()` until a blocking read without delay or a
@@ -7,7 +9,70 @@ successful non-blocking read is possible.
 
 Please note that the same result can be achieved by using `uart_read_bytes()`
 but the use of `select()` allows to use it together with other virtual
-file system (VFS) drivers, e.g. LWIP sockets. For a more comprehensive example
-please refer to `system/select`.
+file system (VFS) drivers, e.g. LWIP sockets.
+
+This example can be used to develop applications for non-blocking read and write from/to various sources (UART,
+sockets, ...) where a ready resource can be served without being blocked by a busy resource.
+
+For a more comprehensive example please refer to `system/select`.
+
+## How to use example
+
+### Hardware Required
+
+The example can be run on any ESP32 development board connected to a PC with a single USB cable for communication
+through UART.
+
+### Configure the project
+
+```
+make menuconfig
+```
+or
+```
+idf.py menuconfig
+```
+
+* Set serial port under Serial Flasher Options.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+make -j4 flash monitor
+```
+or
+```
+idf.py flash monitor
+```
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+You can see a similar output after flashing and monitoring the application:
+
+```
+...
+I (276) cpu_start: Pro cpu start user code
+I (294) cpu_start: Starting scheduler on PRO CPU.
+I (0) cpu_start: Starting scheduler on APP CPU.
+I (10295) uart_select_example: Timeout has been reached and nothing has been received
+I (15295) uart_select_example: Timeout has been reached and nothing has been received
+I (20295) uart_select_example: Timeout has been reached and nothing has been received
+```
+
+You can push any key on your keyboard to see the result of a successful detection by `select()` and subsequent
+blocking read (without delay). The following output shows the result of pushing `a` on the keyboard:
 
-See the README.md file in the upper level 'examples' directory for more information about examples.
+```
+...
+I (15295) uart_select_example: Timeout has been reached and nothing has been received
+I (20295) uart_select_example: Timeout has been reached and nothing has been received
+I (20945) uart_select_example: Received: a
+I (25955) uart_select_example: Timeout has been reached and nothing has been received
+...
+```