From 0a46c6a3eeb55177da48529058cd8d28dc503a16 Mon Sep 17 00:00:00 2001
From: Jiacheng Guo <guojiacheng@espressif.com>
Date: Tue, 11 Jan 2022 15:36:50 +0800
Subject: [PATCH] openthread: update README

---
 .../openthread/extension_command/README.md    | 124 +++++-------------
 examples/openthread/ot_br/README.md           |  58 +++++++-
 examples/openthread/ot_cli/README.md          |   6 +-
 3 files changed, 87 insertions(+), 101 deletions(-)

diff --git a/examples/openthread/extension_command/README.md b/examples/openthread/extension_command/README.md
index 113f5932dd..664a44bf0d 100644
--- a/examples/openthread/extension_command/README.md
+++ b/examples/openthread/extension_command/README.md
@@ -1,15 +1,16 @@
-# Openthread Extension Command
+# Openthread Extension Commands
 
-The Openthread Extension Command is a series of command lines extended from [OpenThread CLI](https://github.com/openthread/openthread/blob/main/src/cli/README.md). 
-Openthread Extension Command doesn't run alone, it needs to be used in conjunction with these examples:
+The ESP OpenThread examples provide a series of extension commands in addition to the standard [OpenThread CLI](https://github.com/openthread/openthread/blob/main/src/cli/README.md).
+The extension commands are available in the following examples:
 * [ot_cli](../ot_cli)
 * [ot_br](../ot_br)
 
-## How to use the example
+## Enabling the extension commands
 
-Run the configuration command `idf.py menuconfig` to enable the operations you need for your example: `OpenThread Extension CLI` -> `Enable Espressif's extended features`.
+To enable OpenThread extension commands, the following Kconfig option needs to be enabled:
+`OpenThread Extension CLI` -> `Enable Espressif's extended features`.
 
-## OT Extension Command Line List
+## Commands
 
 * [iperf](#iperf)
 * [tcpsockclient](#tcpsockclient)
@@ -20,40 +21,39 @@ Run the configuration command `idf.py menuconfig` to enable the operations you n
 
 ### iperf
 
-Iperf is a tool for active measurements of the maximum achievable bandwidth on Thread network, which is based TCP and UDP.
+Iperf is a tool for performing TCP or UDP throughput on the Thread network.
+
+For running iperf, you need to have two Thread devices on the same network.
+
+* General Options
 
-Print the iperf help:
 ```bash
 iperf
 ---iperf parameter---
 -s                  :     server mode, only receive
 -u                  :     upd mode
--V                  :     use IPV6 address  
+-V                  :     use IPV6 address
 -c <addr>           :     client mode, only transmit
 -i <interval>       :     seconds between periodic bandwidth reports
 -t <time>           :     time in seconds to transmit for (default 10 secs)
 -p <port>           :     server port to listen on/connect to
 -l <len_send_buf>   :     the lenth of send buffer
 ---example---
-create a tcp server :     iperf -s -i 3 -p 5001 -t 60 
+create a tcp server :     iperf -s -i 3 -p 5001 -t 60
 create a udp client :     iperf -c <addr> -u -i 3 -t 60 -p 5001 -l 512
 Done
 ```
 
-Create an iperf TCP service for 20 seconds, with printing logs for each 3 seconds, at the port 5001:
+* Typical usage
+
+For measuring the TCP throughput, first create an iperf service on one node:
 ```bash
 > iperf -V -s -t 20 -i 3 -p 5001
 Done
 ```
 
-For UDP service:
-```bash
-> iperf -V -u -s -t 20 -i 3 -p 5001
-Done
-```
+Then create an iperf client connecting to the service on another node. Here we use `fdde:ad00:beef:0:a7c6:6311:9c8c:271b` as the example service address.
 
-
-Create an iperf TCP client connecting to `fdde:ad00:beef:0:a7c6:6311:9c8c:271b`(the iperf server address) for 30 seconds, with printing logs for each second, at the port 5001, with 85 length of each packets:
 ```bash
 > iperf -V -c fdde:ad00:beef:0:a7c6:6311:9c8c:271b -t 20 -i 1 -p 5001 -l 85
 Done
@@ -68,22 +68,18 @@ Done
    0-   20 sec       0.05 Mbits/sec
 ```
 
-For UDP client:
+For measuring the UDP throughput, first create an iperf service similarly:
+
 ```bash
-> iperf -V -u -c fdde:ad00:beef:0:a7c6:6311:9c8c:271b -t 20 -i 1 -p 5001 -l 85
+> iperf -V -u -s -t 20 -i 3 -p 5001
 Done
 ```
 
-### tcpsockclient
-
-Used for creating a tcp client.
+Then create an iperf client:
 
 ```bash
-> tcpsockclient fdde:ad00:beef:0:a7c6:6311:9c8c:271b
+> iperf -V -u -c fdde:ad00:beef:0:a7c6:6311:9c8c:271b -t 20 -i 1 -p 5001 -l 85
 Done
-ot_socket: Socket created, connecting to fdde:ad00:beef:0:a7c6:6311:9c8c:271b:12345
-ot_socket: Successfully connected
-...
 ```
 
 ### tcpsockserver
@@ -98,12 +94,12 @@ I (1310225) ot_socket: Socket bound, port 12345
 I (1310225) ot_socket: Socket listening, timeout is 30 seconds
 ```
 
-### udpsockclient
+### tcpsockclient
 
-Used for creating a udp client.
+Used for creating a tcp client.
 
 ```bash
-> udpsockclient fdde:ad00:beef:0:a7c6:6311:9c8c:271b
+> tcpsockclient fdde:ad00:beef:0:a7c6:6311:9c8c:271b
 Done
 ot_socket: Socket created, connecting to fdde:ad00:beef:0:a7c6:6311:9c8c:271b:12345
 ot_socket: Successfully connected
@@ -122,70 +118,14 @@ I (1310225) ot_socket: Socket bound, port 12345
 I (1310225) ot_socket: Socket listening, timeout is 30 seconds
 ```
 
-### wifi
+### udpsockclient
 
-Get help for wifi command:
+Used for creating a udp client. Note that the client shall be connected to the same Thread network as the server.
 
 ```bash
-> wifi                   
----wifi parameter---                                                                                                                      
-connect                                                                                                                                                                                                                                                                             
--s                   :     wifi ssid                                                                                                                                                                                                                                                
--p                   :     wifi psk                                 
----example---                                                                                                                             
-join a wifi:                           
-ssid: threadcertAP                                                   
-psk: threadcertAP    :     wifi connect -s threadcertAP -p threadcertAP                                                                   
-state                :     get wifi state, disconnect or connect
----example---                                                                                                                             
-get wifi state       :     wifi state                                                                                                     
-Done                                                                                                                                      
-```
-
-Join a wifi with ssid: threadcertAP and psk: threadcertAP:
-
-```bash
-> wifi connect -s threadcertAP -p threadcertAP                                                                                            
-ssid: threadcertAP                                                                                                                        
-psk: threadcertAP                  
-I (11331) wifi:wifi driver task: 3ffd06e4, prio:23, stack:6656, core=0                                                                    
-I (11331) system_api: Base MAC address is not set                                                                                         
-I (11331) system_api: read default base MAC address from EFUSE                                                                            
-I (11341) wifi:wifi firmware version: 45c46a4                                                                                             
-I (11341) wifi:wifi certification version: v7.0                                                                                           
-
-
-..........
-
-I (13741) esp_netif_handlers: sta ip: 192.168.3.10, mask: 255.255.255.0, gw: 192.168.3.1                                                  
-W (13771) wifi:<ba-add>idx:0 (ifx:0, 02:0f:c1:32:3b:2b), tid:0, ssn:2, winSize:64
-wifi sta is connected successfully                       
-Done                                                       
-```
-
-Get the state of the WiFi:
-
-```bash
-> wifi state                                                
-connected                                                    
+> udpsockclient fdde:ad00:beef:0:a7c6:6311:9c8c:271b
 Done
+ot_socket: Socket created, connecting to fdde:ad00:beef:0:a7c6:6311:9c8c:271b:12345
+ot_socket: Successfully connected
+...
 ```
-
-## Extension command example
-
-### TCP and UDP Example
-
-Before running this example, a thread network with a Leader and a router( or child) needs to be set up.
-
-On the leader device, start a TCP or UDP server, on router device, start a TCP or UDP client.
-
-(note: replace the parameter of the `tcpsockclient` or `udpsockclient` with the leader's IPv6 address)
-
-### Iperf Example
-
-Example for using iperf:
-
-Before running iperf, a thread network with a Leader and a router( or child) needs to be set up.
-
-On the leader device, start iperf TCP or UDP server, on the router device, start iperf TCP or UDP client.
-
diff --git a/examples/openthread/ot_br/README.md b/examples/openthread/ot_br/README.md
index 52275d854f..e59d9485dc 100644
--- a/examples/openthread/ot_br/README.md
+++ b/examples/openthread/ot_br/README.md
@@ -34,7 +34,7 @@ Enable `OPENTHREAD_BR_AUTO_START`, configure the `CONFIG_EXAMPLE_WIFI_SSID` and
 The device will connect to Wi-Fi and form a Thread network automatically after bootup.
 
 - Manual mode
-Disable `OPENTHREAD_BR_AUTO_START`, and use the CLI command to configure the Wi-Fi and form Thread network manually.
+Disable `OPENTHREAD_BR_AUTO_START` and enable `OPENTHREAD_CLI_ESP_EXTENSION`. `wifi` command will be added for connecting the device to the Wi-Fi network.
 
 ### Build, Flash, and Run
 
@@ -43,12 +43,58 @@ Build the project and flash it to the board, then run monitor tool to view seria
 ```
 idf.py -p PORT build flash monitor
 ```
-If the OPENTHREAD_BR_AUTO_START option is enabled, The device will be connected to the configured Wi-Fi and Thread network automatically then act as the border router.
+If the `OPENTHREAD_BR_AUTO_START` option is enabled, The device will be connected to the configured Wi-Fi and Thread network automatically then act as the border router.
 
-Otherwise, you need to manually configure the Wi-Fi and Thread network with CLI command.
+Otherwise, you need to manually configure the networks with CLI commands.
 
-For connecting to Wi-Fi, you can refer to [extension_command](../extension_command/README.md) about `wifi` command.
-For forming Thread network, you can refer to [ot_cli_README](../ot_cli/README.md).
+`wifi` command can be used to configure the Wi-Fi network.
+
+```bash
+> wifi
+--wifi parameter---
+connect
+-s                   :     wifi ssid
+-p                   :     wifi psk
+---example---
+join a wifi:
+ssid: threadcertAP
+psk: threadcertAP    :     wifi connect -s threadcertAP -p threadcertAP
+state                :     get wifi state, disconnect or connect
+---example---
+get wifi state       :     wifi state
+Done
+```
+
+To join a Wi-Fi network, please use the `wifi connect` command:
+
+```bash
+> wifi connect -s threadcertAP -p threadcertAP
+ssid: threadcertAP
+psk: threadcertAP
+I (11331) wifi:wifi driver task: 3ffd06e4, prio:23, stack:6656, core=0
+I (11331) system_api: Base MAC address is not set
+I (11331) system_api: read default base MAC address from EFUSE
+I (11341) wifi:wifi firmware version: 45c46a4
+I (11341) wifi:wifi certification version: v7.0
+
+
+..........
+
+I (13741) esp_netif_handlers: sta ip: 192.168.3.10, mask: 255.255.255.0, gw: 192.168.3.1
+W (13771) wifi:<ba-add>idx:0 (ifx:0, 02:0f:c1:32:3b:2b), tid:0, ssn:2, winSize:64
+wifi sta is connected successfully
+Done
+```
+
+To get the state of the Wi-Fi network:
+
+```bash
+> wifi state
+connected
+Done
+```
+
+For forming the Thread network, please refer to the [ot_cli_README](../ot_cli/README.md).
 
 ## Example Output
 
@@ -70,7 +116,7 @@ I(8159) OPENTHREAD:[NOTE]-MLE-----: Role Detached -> Leader
 ```
 ## Using the border agent feature
 
-You need to ot-commissioner on the host machine and another Thread end device running OpenThread cli.
+You need to build ot-commissioner on the host machine and another Thread end device running OpenThread cli.
 
 You can find the guide to build and run ot-commissioner [here](https://openthread.io/guides/commissioner/build).
 
diff --git a/examples/openthread/ot_cli/README.md b/examples/openthread/ot_cli/README.md
index 02689cb306..4be53dd0fc 100644
--- a/examples/openthread/ot_cli/README.md
+++ b/examples/openthread/ot_cli/README.md
@@ -117,11 +117,11 @@ Done
 ```
 The second device has joined the Thread network as a router (or a child).
 
-## Extension command example
+## Extension commands
 
-You can refer to [extension command](../extension_command/README.md) for how to use the extension commands.
+You can refer to the [extension command](../extension_command/README.md) about the extension commands.
 
-these examples are supported by ot_cli:
+The following examples are supported by `ot_cli`:
 
 * TCP and UDP Example
 * Iperf Example