Merge branch 'docs/improve_README' into 'master'

zhanzhaocheng · zhanzhaocheng · commit 5aa32d346080 · 2019-07-17T10:52:28.000+08:00
docs(README): Modify the description in the README

See merge request application/esp-mdf!297
diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/README.md b/README.md
@@ -44,13 +44,19 @@ ESP-MDF consists of Utils, Components and Examples (see the below figure). Utils
     - [Mlink](https://docs.espressif.com/projects/esp-mdf/en/latest/api-guides/mlink.html): LAN control module
 
 - **Examples**:
-    - [Function demo](examples/function_demo/): demonstrates how functions can be used
-    - [Development Kit](examples/development_kit/): provides ESP32-MeshKit and ESP32-Buddy application demos
-    - [Aliyun link Kit](examples/maliyun_linkkit/)：ESP32-Mesh access to Alibaba Cloud platform example
-    - Solution: offers a routerless solution, as well as the solutions for indoor positioning, street light control, etc.
-
+- [Function demo](examples/function_demo/): Example of use of each function module
+         - Mwifi: An example of common networking methods: no router, no router. First develop based on this example, then add distribution, upgrade, wireless test and other functions based on it.
+         - Mupgrade: Upgrade example of the device
+         - Mconfig: Example of network configuration of the device
+         - Mcommon: Common Module Example, Event Processing Memory Management Example of Using Information Store
+     - [Console Test] (examples/function_demo/mwifi/console_test): Test the ESP-MESH throughput, network configuration, and packet delay by entering commands through the serial port.
+     - [Wireless Debug](examples/wireless_debug/): ESP-MDF debugging via wireless
+     - [Development Kit](examples/development_kit/): ESP32-MeshKit usage example for research and understanding of ESP-MESH
+     - [Aliyun link Kit](examples/maliyun_linkkit/): Example of ESP-MESH access to Alibaba Cloud platform
 ## Develop with ESP-MDF
 
+You first need to read [ESP-MESH Communication Protocol] (https://docs.espressif.com/projects/esp-idf/en/stable/api-guides/mesh.html) and [ESP-MDF Compilation Guide] ( Https://docs.espressif.com/projects/esp-mdf/en/latest/?badge=latest) and research and learn about ESP-MESH through the ESP32-MeshKit development kit. Secondly, based on [Function demo] (examples/function_demo/) for your project development, when you can encounter problems in development, you can first go to [Official Forum] (https://esp32.com/viewforum.php?f= 21&sid=27bd50a0e45d47b228726ee55437f57e) and [Official GitHub] (https://github.com/espressif/esp-mdf/issues) to find out if a similar problem already exists. If there is no similar problem, you can also ask directly on the website.
+
 ### Development Boards
 
 #### ESP32-MeshKit Development board
@@ -93,7 +99,7 @@ The directory ``~/esp`` will be used further to install the compiling toolchain,
     ```shell
     git clone --recursive https://github.com/espressif/esp-mdf.git
     ```
-    If you clone without the `--recursive` option, please navigate to the esp-mdf directory and run the command `git submodule update --init`
+    If you clone without the `--recursive` option, please navigate to the esp-mdf directory and run the command `git submodule update --init --recursive`
 
 3. **Set up ESP-MDF Path**: Toolchain uses the environment variable ``MDF_PATH`` to access ESP-MDF. The setup of this variable is similar to that of the variable ``IDF_PATH``. Please refer to [`Add IDF_PATH to User Profile`](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/add-idf_path-to-profile.html).
     ```shell
@@ -198,7 +204,7 @@ The directory ``~/esp`` will be used further to install the compiling toolchain,
 ## Related Documentation
 
 * For ESP-MDF related documents, please go to [ESP-MDF Programming Guide](https://docs.espressif.com/projects/esp-mdf/en/latest/?badge=latest).
-* [ESP-MESH](https://esp-idf.readthedocs.io/en/latest/api-guides/mesh.html) is the basic wireless communication protocol for ESP-MDF.
+* [ESP-MESH](https://docs.espressif.com/projects/esp-idf/en/stable/api-guides/mesh.html) is the basic wireless communication protocol for ESP-MDF.
 * [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/stable/) describes Espressif's IoT development framework.
 * To report a bug or request a function, please go to [Issues](https://github.com/espressif/esp-mdf/issues) on GitHub to submit them. Before submitting an issue, please check if it has already been covered.
 * If you want to contribute ESP-MDF related codes, please refer to [Code Contribution Guide](docs/en/contribute/index.rst).
diff --git a/README_cn.md b/README_cn.md
@@ -33,6 +33,8 @@ ESP-MDF 共分为 Utils、Components 和 Examples 三个部分（如下图所示
     - Mcommon：ESP-MDF 各组件之间的共用模块
         - Event loop：ESP-MDF 的事件处理
         - Error Check：ESP-MDF 的错误码管理
+        - Memory Management：ESP-MDF 的内存管理
+        - Information Storage：将配置信息存储到 flash 中
 
 - **Components**：
     - [Mconfig](https://docs.espressif.com/projects/esp-mdf/zh_CN/latest/api-guides/mconfig.html)：配网模块
@@ -42,18 +44,18 @@ ESP-MDF 共分为 Utils、Components 和 Examples 三个部分（如下图所示
 
 - **Examples**：
     - [Function demo](examples/function_demo/)：各个功能模块的使用示例
-    - [Development Kit](examples/development_kit/)：ESP32-MeshKit 和 ESP32-Buddy 使用示例
-    - [Aliyun link Kit](examples/maliyun_linkkit/)：ESP32-Mesh 接入阿里云平台示例
-    - Solution：室内定位、无路由、路灯等解决方案
+        - Mwifi：常见组网方式的示例：无路由器、有路由器。先基于此示例进行开发,而后在其基础上添加配网、升级、无线测试等功能
+        - Mupgrade：设备的升级示例
+        - Mconfig：设备的配网示例
+        - Mcommon：通用模块示例,事件处理 内存管理 信息存储的使用示例
+    - [Console Test](examples/function_demo/mwifi/console_test)：通过串口输入命令的方式，测试 ESP-MESH 吞吐量、网络配置、发包时延。
+    - [Wireless Debug](examples/wireless_debug/)：通过无线的方式进行 ESP-MDF 调试
+    - [Development Kit](examples/development_kit/)：ESP32-MeshKit 使用示例, 用于调研和了解 ESP-MESH
+    - [Aliyun link Kit](examples/maliyun_linkkit/)：ESP-MESH 接入阿里云平台示例
 
 ## 使用 ESP-MDF 进行开发
 
-### 开发流程
-
-1. 您首先需要了解 ESP-MESH 概念，可参考链接：[ESP-MESH](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/api-guides/mesh.html);
-2. 之后，您需要了解[ ESP-MDF 开发框架](https://docs.espressif.com/projects/esp-mdf/en/latest/index.html#)并通过 ESP-MDF 中的[示例](examples)学习使用 ESP-MDF 进行开发,例如：运行 Function demo 目录下的示例学习 ESP-MDF 各个模块;
-3. 您可以在 ESP-MDF 的 examples 目录下找到一系列示例工程，并基于这些示例工程进行您的项目开发;
-4. 当您可以在开发中遇到问题，首先可在[官方论坛](https://esp32.com/viewforum.php?f=21&sid=27bd50a0e45d47b228726ee55437f57e)和[官方 GitHub ](https://github.com/espressif/esp-mdf/issues)上寻找是否已存在类似问题，若不存在类似问题，您也可直接在网站中提问。
+您首先需要详细阅读 [ESP-MESH 通信协议](https://docs.espressif.com/projects/esp-idf/en/stable/api-guides/mesh.html)和[ESP-MDF 编译指南](https://docs.espressif.com/projects/esp-mdf/zh_CN/latest/index.html)，并通过 ESP32-MeshKit 开发套件调研和了解 ESP-MESH。其次基于 [Function demo](examples/function_demo/)进行您的项目开发，当您可以在开发中遇到问题，首先可在[官方论坛](https://esp32.com/viewforum.php?f=21&sid=27bd50a0e45d47b228726ee55437f57e)和[官方 GitHub ](https://github.com/espressif/esp-mdf/issues)上寻找是否已存在类似问题，若不存在类似问题，您也可直接在网站中提问。
 
 ### 开发板指南
 
@@ -93,7 +95,7 @@ ESP32-Buddy 是专为 ESP-MESH 开发测试而设计的开发板。体积小，
     ```shell
     git clone --recursive https://github.com/espressif/esp-mdf.git
     ```
-    > 如果您在没有 `--recursive` 标记的情况下克隆项目，转到 esp-mdf 目录并运行命令 `git submodule update --init`
+    > 如果您在没有 `--recursive` 标记的情况下克隆项目，转到 esp-mdf 目录并运行命令 `git submodule update --init --recursive`
 
 3. **设置 ESP-MDF 路径**：工具链程序使用环境变量 ``MDF_PATH`` 来访问 ESP-MDF，设置它的过程类似于设置 ``IDF_PATH`` 变量，请参阅[`添加 IDF_PATH 到用户配置文件`](https://docs.espressif.com/projects/esp-idf/zh_CN/stable/get-started/add-idf_path-to-profile.html)。
     ```shell
@@ -173,7 +175,7 @@ ESP32-Buddy 是专为 ESP-MESH 开发测试而设计的开发板。体积小，
 * **无需网关**：ESP-MESH 采用去中心化的结构，其无需网关避免了单点故障造成整个网络瘫痪，仅一个 ESP-MESH 设备也能正常工作；
 * **传输更安全**：数据链路层和应用层均可实施加密；
 * **传输更可靠**：两个设备之间的是可靠传输和流控，支持单播、组播和广播；
-* **网络容量大**：ESP-MESH 采用树状结构，单个设备最多直接连接 10 个设备，单个网络可容纳 1000 个节点以上；
+* **网络容量大**：ESP-MESH 采用树状结构，单个设备最多直接连接 10 个设备，单个网络可容纳 1000 个节点；
 * **传输范围广**：两个设备之间的传输距离隔墙 30 m，空旷环境 200 m（测试基于 ESP32-DevKitC）；
     * **智能家居**：即使仅有三五个设备且隔墙也能够组成网络，可以满足家庭环境中，设备数量少无法相互通信的问题；
     * **路灯方案**：可能满足路灯场景中两个相距较远的设备之间的通信。
@@ -189,7 +191,7 @@ ESP32-Buddy 是专为 ESP-MESH 开发测试而设计的开发板。体积小，
 
 ## 相关资源
 
-* 查看 ESP-MDF 项目文档请点击 [ESP-MDF 编程指南](https://docs.espressif.com/projects/esp-mdf/zh_CN/latest/index.html)。
+* [ESP-MDF 编程指南](https://docs.espressif.com/projects/esp-mdf/zh_CN/latest/index.html) 是 ESP-MDF 开发框架的说明文档。
 * [ESP-IDF 编程指南](https://docs.espressif.com/projects/esp-idf/zh_CN/stable/index.html) 是乐鑫物联网开发框架的说明文档。
 * [ESP-MESH](https://docs.espressif.com/projects/esp-idf/en/stable/api-guides/mesh.html) 是 ESP-MDF 的无线通信协议基础。
 * 如您发现 bug 或有功能请求，可在 GitHub 上的 [Issues](https://github.com/espressif/esp-mdf/issues) 提交。请在提交问题之前查看已有的 Issues 中是否已经有您的问题。
diff --git a/examples/function_demo/mwifi/README.md b/examples/function_demo/mwifi/README.md
@@ -1 +1,24 @@
 [[CN]](./README_cn.md)
+
+# Mwifi
+
+This directory contains examples for two common networking modes of ESP-MESH: with router or without router.
+
+In the ESP-MESH networking, there are two ways to generate root node:
+
+1. Automatically selected root node: automatically elected based on the signal strength of the idle node and the router.
+2. Fixed root node: choose a device as the root node in the code, and the remaining devices are non-root nodes
+
+According to the two generation ways of root node, the networking mode can be simply divided into two cases: with router and without router.
+
+## Without router
+
+When there is no router in the case, we can only choose the fixed root node mode. Refer to [No Routing Sample Program] (./no_router)
+
+##With router
+
+When there are routers in the case, we can choose either of the two modes for networking. In the example we use the automatically selected root node. The automatical selection of the root node involves the election process between all idle nodes based on their signal strength with the router, so only in the presence of a router, each idle node will send its MAC address and router RSSI through the Wi-Fi beacon frame. The MAC address is used to uniquely identify each node in the network, and the router RSSI is used to indicate the signal strength of the node reference router. See [routed TCP communication sample program] (./router), [routed MQTT communication sample program] (./mqtt_example)
+
+## Performance Testing
+
+Test the ESP-MESH throughput, network configuration, and packet delay by inputting commands through the serial port. Refer to [Performance Test Sample Program] (./console_test)
diff --git a/examples/function_demo/mwifi/README_cn.md b/examples/function_demo/mwifi/README_cn.md
@@ -17,4 +17,8 @@
 
 ## 有路由器
 
-当环境中存在路由器时，我们可以选择两种方式中的任意一种进行组网。在示例中我们使用自动选择根节点方式。根节点的自动选择涉及所有空闲节点之间基于其与路由器的信号强度的选举过程，所以只能在存在路由器的情况下每个空闲节点将通过 Wi-Fi 信标帧发送其 MAC 地址和路由器 RSSI 值。MAC 地址用于唯一地标识网络中的每个节点，而路由器 RSSI 用于指示节点参考路由器的信号强度。可参考 [有路由示例程序](./router)
+当环境中存在路由器时，我们可以选择两种方式中的任意一种进行组网。在示例中我们使用自动选择根节点方式。根节点的自动选择涉及所有空闲节点之间基于其与路由器的信号强度的选举过程，所以只能在存在路由器的情况下每个空闲节点将通过 Wi-Fi 信标帧发送其 MAC 地址和路由器 RSSI 值。MAC 地址用于唯一地标识网络中的每个节点，而路由器 RSSI 用于指示节点参考路由器的信号强度。可参考 [有路由 TCP 通信示例程序](./router), [有路由 MQTT 通信示例程序](./mqtt_example)
+
+## 性能测试
+
+通过串口输入指令的方式，测试 ESP-MESH 吞吐量 、网络配置 、发包时延等。可参考 [性能测试示例程序](./console_test)
diff --git a/examples/wireless_debug/README.md b/examples/wireless_debug/README.md
@@ -2,7 +2,7 @@
 
 # ESP-NOW Debug Receiver Board Demo
 
-ESP-NOW debug receiver board can receive debugging data from ESP-MESH devices only when the board is on the same Wi-Fi channel with the devices. Meanwhile, if the board is on the same local area network (connected to the same router) with the devices, the board can discover services via mDNS and get basic information of Mesh network, including Mesh ID, root node IP, root node MAC address and etc.  
+ESP-NOW debug receiver board can receive debugging data from ESP-MESH devices only when the board is on the same Wi-Fi channel with the devices.
 
 <div align=center>
 <img src="espnow_debug.png" width="800">
@@ -172,7 +172,6 @@ wireless_debug/
     |Command definition|wifi_sniffer -c <channel (1 ~ 13)>||
     |Command|wifi_sniffer -c|Configure sniffer monitoring channel|
     |Parameter|channel|Channel number|
-    ||| 11 // means to monitor channel 11 |
     |Example|wifi_sniffer -c 11|Sniffer monitors channel 11|
 
 2. Configure the name of the file used to save monitored data packages
@@ -212,11 +211,11 @@ wireless_debug/
     |Command definition|wifi_config -c <channel (1 ~ 13)> -s <ssid> -b <bssid (xx:xx:xx:xx:xx:xx)> -p <password>||
     |Command|wifi_config -c -s -b -p|Wi-Fi configuration|
     |Parameter|channel|Wi-Fi work channel|
-    ||| 11 // means to monitor channel 11 |
     ||ssid|AP SSID|
     ||bssid|AP BSSID|
     ||password|AP password|
     |Example|wifi_config -s "esp-liyin" -p "password"|Wi-Fi sets and connects to the AP with SSID as esp-liyin and password as "password".|
+    |Example|wifi_config -c 11|Configure the working channel of the ESP-MESH device to be 11|
 
 2. Save/erase Wi-Fi configuration information
 
diff --git a/examples/wireless_debug/README_cn.md b/examples/wireless_debug/README_cn.md
@@ -2,7 +2,7 @@
 
 # ESP-NOW debug 接收板示例
 
-ESP-NOW debug 接收板需要和 ESP-MESH 设备处于同一个 Wi-Fi 信道上才可以接收 ESP-MESH 设备发送的调试数据。同时，如果 ESP-NOW debug 接收板和 ESP-MESH 设备处于同一个局域网下（连接同一个路由器），接收板还可以通过 mDNS 设备发现服务获取 Mesh 网络的基本信息，包括：Mesh-ID、根节点 IP、根节点 MAC 地址等。
+ESP-NOW debug 接收板需要和 ESP-MESH 设备处于同一个 Wi-Fi 信道上才可以接收 ESP-MESH 设备发送的调试数据。
 
 <div align=center>
 <img src="espnow_debug.png" width="800">
@@ -171,7 +171,6 @@ wireless_debug/
     |命令定义|wifi_sniffer -c <channel (1 ~ 13)>||
     |指令|wifi_sniffer -c|设置 sniffer 监听信道|
     |参数|channel|信道号|
-    ||| 11 // 监听 11 信道 |
     |示例|wifi_sniffer -c 11|sniffer 监听 11 信道|
 
 2. 设置监听数据包存储文件名
@@ -211,11 +210,11 @@ wireless_debug/
     |命令定义|wifi_config -c <channel (1 ~ 13)> -s <ssid> -b <bssid (xx:xx:xx:xx:xx:xx)> -p <password>||
     |指令|wifi_config -c -s -b -p|Wi-Fi 配置|
     |参数|channel|Wi-Fi 工作信道|
-    ||| 11 // 监听 11 信道 |
     ||ssid|AP 的 SSID|
     ||bssid|AP 的 BSSID|
     ||password|AP 的 密码|
     |示例|wifi_config -s "esp-liyin" -p "password"|Wi-Fi 配置，连接 SSID 为 esp-liyin 密码为 password 的 AP|
+    |示例|wifi_config -c 11|配置 ESP-MESH 设备工作信道为 11|
 
 2. 保存/擦除 Wi-Fi 配置信息
 
