Merge branch 'doc/readme' into 'master'

doc: update readme

See merge request application/esp-mdf!286

README.md

@@ -15,9 +15,10 @@ ESP-MDF is based on the [ESP-MESH](https://docs.espressif.com/projects/esp-idf/e
 
 * **LAN control**: Network can be controlled by an app, sensor, etc.
 
-* **Various application demos**: It offers comprehensive solutions based on ESP-MESH in the areas of lighting, indoor positioning, etc.
+* **Various application demos**: It offers comprehensive solutions based on ESP-MESH in the areas of lighting, etc.
 
 ## Framework
+
 ESP-MDF consists of Utils, Components and Examples (see the below figure). Utils is the encapsulation and third-party library of ESP-IDF APIs. Components are the ESP-MDF functional modules that use Utils APIs. Examples are the ESP-MESH solutions based on the Components.
 
 <img src="docs/_static/mdf_framework.jpg">
@@ -39,35 +40,40 @@ ESP-MDF consists of Utils, Components and Examples (see the below figure). Utils
 - **Components**:
     - [Mconfig](https://docs.espressif.com/projects/esp-mdf/en/latest/api-guides/mconfig.html): network configuration module
     - [Mupgrade](https://docs.espressif.com/projects/esp-mdf/en/latest/api-guides/mupgrade.html): upgrade module
-    - Mdebug: debugging module
+    - [Mdebug](https://docs.espressif.com/projects/esp-mdf/en/latest/api-guides/mupgrade.html): debugging module
     - [Mlink](https://docs.espressif.com/projects/esp-mdf/en/latest/api-guides/mlink.html): LAN control module
 
 - **Examples**:
-    - Function demo: demonstrates how functions can be used
-    - Development Kit: provides ESP32-MeshKit and ESP32-Buddy application demos
+    - [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.
 
 ## Develop with ESP-MDF
+
 ### Development Boards
-#### ESP32-MeshKit
+
+#### ESP32-MeshKit Development board
+
 ESP32-MeshKit offers a complete [ESP-MESH Lighting Solution](https://www.espressif.com/en/products/software/esp-mesh/overview) (see the below figure), complemented by ESP-Mesh App ([iOS version](https://itunes.apple.com/cn/app/esp-mesh/id1420425921?mt=8) and [Android](https://github.com/EspressifApp/Esp32MeshForAndroid/raw/master/release/mesh.apk)) for research, development and better understanding of ESP-MESH.
 
 <table>
-        <tr>
-            <td ><img src="docs/_static/ESP32-MeshKit_Light.jpg" width="550"><p align=center>ESP32-MeshKit Light</p></td>
-            <td ><img src="docs/_static/ESP32-MeshKit_Sense.jpg" width="600"><p align=center>ESP32-MeshKit Sense</p></td>
-        </tr>
-    </table>
+    <tr>
+        <td ><img src="docs/_static/ESP32-MeshKit_Light.jpg" width="550"><p align=center>ESP32-MeshKit Light</p></td>
+        <td ><img src="docs/_static/ESP32-MeshKit_Sense.jpg" width="600"><p align=center>ESP32-MeshKit Sense</p></td>
+    </tr>
+</table>
 
 * Products:
     * [ESP32-MeshKit-Light](https://www.espressif.com/sites/default/files/documentation/esp32-meshkit-light_user_guide_en.pdf): The RGBCW smart lights that show control results visually. They can be used to test network configuration time, response speed, stability performance, and measure distance, etc.
 
     * [ESP32-MeshKit-Sense](https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP32-MeshKit-Sense_guide_en.md): This kit is equipped with a light sensor as well as a temperature & humidity sensor. It can measure power consumption and develop low power applications. The kit may also be used with ESP-Prog for firmware downloading and debugging.
 
-    * ESP32-MeshKit-Button: Serves as an on/off controller, ready for the development of low power applications. It can be used with ESP-Prog for firmware downloading and debugging (Coming soon).
+    * [ESP32-MeshKit-Button](examples/development_kit/button/docs/ESP32-MeshKit-Button_Schematic.pdf): Serves as an on/off controller, ready for the development of low power applications. It can be used with ESP-Prog for firmware downloading and debugging.
 
-#### ESP32-Buddy
-ESP32-Buddy is a development board specifically designed to test the development of ESP-MESH. With its small size and USB power input, the board can be conveniently used for testing a large number of devices and measure distances between them (Coming soon).
+#### ESP32-Buddy Development board
+
+ESP32-Buddy is a development board specifically designed to test the development of ESP-MESH. With its small size and USB power input, the board can be conveniently used for testing a large number of devices and measure distances between them.
 
 * Functions:
     * 16 MB flash: stores logs
@@ -177,9 +183,11 @@ The directory ``~/esp`` will be used further to install the compiling toolchain,
 * **Wider transmission coverage**: The transmission distance between two devices is 30 m through walls, and 200 m without any obstacles in between (relevant to ESP32-DevKitC).
     * **Smart Home**: Even if there are only three to five devices in your home, they can form a network and communicate with one another through walls.
     * **Street light**: If ESP-MESH is used for the street lighting scenario, two long-distance devices can communicate with each other.
+
 * **High transmission speed**: For Wi-Fi transmission, the speed can reach up to 10 Mbps.
     * **Environment Control System**: Directly transfers the raw data collected by sensors and analyzes mass data for calibration of algorithms, thereby improving sensors' accuracy.
     * **Background Music System**: Both audio and video transmissions are supported.
+
 * **Simultaneously run Wi-Fi and BLE protocol stacks**: ESP32 chips can run both Wi-Fi and BLE protocol stacks side by side and use ESP-MESH as the main network to transmit data, receive BLE probe beacon, send BLE broadcasts and connect BLE devices.
     * **Items tracing**: Monitors the BLE or Wi-Fi data packets from a device at multiple selected spots.
     * **Pedestrian counting**: Through monitoring Wi-Fi probe request frames.
@@ -198,4 +206,3 @@ The directory ``~/esp`` will be used further to install the compiling toolchain,
 * For the hardware documents related to ESP32-MeshKit, please visit [Espressif Website](https://www.espressif.com/en/support/download/documents).
 * ESP32-MeshKit-Light purchase link: [Taobao](https://item.taobao.com/item.htm?spm=a230r.1.14.1.55a83647K8jlrh&id=573310711489&ns=1&abbucket=3#detail).
 * ESP32-Buddy purchase link: Coming soon.
-

README_cn.md

@@ -12,13 +12,13 @@ ESP-MDF 在 [ESP-MESH](https://docs.espressif.com/projects/esp-idf/en/stable/api
 * **稳定升级**：通过断点续传、数据压缩、版本回退和固件检查等机制达到高效升级；
 * **高效调试**：支持指令终端、通过无线进行日志传输和调试等多种调试方式；
 * **局域网控制**：支持 app 控制、传感器控制等；
-* **丰富的示例**：提供了基于 ESP-MESH 的照明、室内定位等综合解决方案。
+* **丰富的示例**：提供了基于 ESP-MESH 的照明等综合解决方案。
 
 ## 框架
 
 ESP-MDF 共分为 Utils、Components 和 Examples 三个部分（如下图所示），他们之间的关系：Utils 是 ESP-IDF APIs 的抽象封装以及第三方库，Components 是基于 Utils APIs 组成的 ESP-MDF 功能模块，Examples 是基于 Components 完成的 ESP-MESH 解决方案。
 
-<img src="docs/_static/mdf_framework.jpg">
+<img src="docs/_static/mdf_framework.jpg" author="Author by Natasha">
 
 - **Utils**：
     - Third Party：第三方的组件
@@ -38,32 +38,44 @@ ESP-MDF 共分为 Utils、Components 和 Examples 三个部分（如下图所示
     - [Mconfig](https://docs.espressif.com/projects/esp-mdf/zh_CN/latest/api-guides/mconfig.html)：配网模块
     - [Mupgrade](https://docs.espressif.com/projects/esp-mdf/zh_CN/latest/api-guides/mupgrade.html)：升级模块
     - Mdebug：调试模块
-    - [Mlink](https://docs.espressif.com/projects/esp-mdf/en/latest/api-guides/mlink.html)：局域网控制模块
+    - [Mlink](https://docs.espressif.com/projects/esp-mdf/zh_CN/latest/api-guides/mlink.html)：局域网控制模块
 
 - **Examples**：
-    - Function demo：各个功能块的使用示例
-    - Development Kit：ESP32-MeshKit 和 ESP32-Buddy 使用示例
+    - [Function demo](examples/function_demo/)：各个功能模块的使用示例
+    - [Development Kit](examples/development_kit/)：ESP32-MeshKit 和 ESP32-Buddy 使用示例
+    - [Aliyun link Kit](examples/maliyun_linkkit/)：ESP32-Mesh 接入阿里云平台示例
     - Solution：室内定位、无路由、路灯等解决方案
 
 ## 使用 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)上寻找是否已存在类似问题，若不存在类似问题，您也可直接在网站中提问。
+
 ### 开发板指南
-#### ESP32-MeshKit
+
+#### ESP32-MeshKit 开发套件
+
 ESP32-MeshKit 包含一整套完整的 [ESP-MESH 的照明解决方案](https://www.espressif.com/zh-hans/products/software/esp-mesh/overview)（如下图所示），可配套 ESP-Mesh App（[iOS 版](https://itunes.apple.com/cn/app/esp-mesh/id1420425921?mt=8)和[安卓版](https://github.com/EspressifApp/Esp32MeshForAndroid/raw/master/release/mesh.apk)）使用，用于调研和了解 ESP-MESH，也可以进行二次开发。
 
 <table>
-        <tr>
-            <td ><img src="docs/_static/ESP32-MeshKit_Light.jpg" width="550"><p align=center>ESP32-MeshKit Light</p></td>
-            <td ><img src="docs/_static/ESP32-MeshKit_Sense.jpg" width="600"><p align=center>ESP32-MeshKit Sense</p></td>
-        </tr>
-    </table>
+    <tr>
+        <td ><img src="docs/_static/ESP32-MeshKit_Light.jpg" width="550"><p align=center>ESP32-MeshKit Light</p></td>
+        <td ><img src="docs/_static/ESP32-MeshKit_Sense.jpg" width="600"><p align=center>ESP32-MeshKit Sense</p></td>
+    </tr>
+</table>
 
 * 产品：
     * [ESP32-MeshKit-Light](https://www.espressif.com/sites/default/files/documentation/esp32-meshkit-light_user_guide_cn.pdf)：RGBCW 智能灯，直观反应控制结果，可用于测试组网时间、响应速度、距离测试、稳定性测试等。
     * [ESP32-MeshKit-Sense](https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP32-MeshKit-Sense_guide_cn.md)：带有光强传感器和温湿度传感器，可用于功耗测量和低功耗应用的开发，可配套使用 ESP-Prog 进行固件烧录和 Debug。
-    * ESP32-MeshKit-Button：作为开关控制，用于低功耗应用的开发，可配套使用 ESP-Prog 进行固件烧录和 Debug（即将上线，敬请期待）。
+    * [ESP32-MeshKit-Button](docs/ESP32-MeshKit-Button_Schematic.pdf)：作为开关控制，用于低功耗应用的开发，可配套使用 ESP-Prog 进行固件烧录和调试。
 
-#### ESP32-Buddy
-ESP32-Buddy 是专为 ESP-MESH 开发测试而设计的开发板。体积小，采用 USB 供电，方便做大数量设备的测试及距离测试（即将上线，敬请期待）。
+#### ESP32-Buddy 开发板
+
+ESP32-Buddy 是专为 ESP-MESH 开发测试而设计的开发板。体积小，采用 USB 供电，方便做大数量设备的测试及距离测试。
 
 * 功能：
     * 16 MB 的 flash：存储运行日志
@@ -186,6 +198,3 @@ ESP32-Buddy 是专为 ESP-MESH 开发测试而设计的开发板。体积小，
 * 关于 ESP32-MeshKit 硬件文档，请至[乐鑫官网](https://www.espressif.com/zh-hans/support/download/documents?keys=&field_technology_tid%5B%5D=18)查看。
 * ESP32-MeshKit-Light 购买链接：[淘宝](https://item.taobao.com/item.htm?spm=a230r.1.14.1.55a83647K8jlrh&id=573310711489&ns=1&abbucket=3#detail)。
 * ESP32-Buddy 购买链接：即将上架。
-
-
-

docs/zh_CN/api-guides/mwifi.rst

@@ -60,7 +60,7 @@ Mwifi (MESH Wi-Fi) 是用于 ESP-MDF 中最重要的一个组件，目的是实
     :alt: communicate_unicast
     :figclass: align-center
 
-> 注: 单播向上发送(子节点发向根节点)有流控,因此是阻塞的, 需要等待发包结束或者出错才能返回
+> 注: 单播向上发送(子节点发向根节点)有流控，因此是阻塞的，需要等待发包结束或者出错才能返回
 
 多播发送
 ^^^^^^^^^^^^^^^^
@@ -92,6 +92,8 @@ Mwifi (MESH Wi-Fi) 是用于 ESP-MDF 中最重要的一个组件，目的是实
 
 在 ESP-MESH 实际应用时，同一个 ESP-MESH 网络中会存在很多设备，并且有很多设备功能类似，在对设备进行控制时，希望批量控制这些设备，这时，就可以将这些功能类似的设备添加到同一个设备组中。
 
+根节点向所有子节点发送数据包，但只有目的组中的节点才能对数据包中的内容进行处理。
+
 .. figure:: ../../_static/Mwifi/device_group.png
     :align: center
     :alt: communicate_broadcast

examples/README.md

@@ -9,8 +9,8 @@ The examples are grouped into subdirectories by category. Each category director
 * `get_started`: contains some very simple examples with minimal functionality.
 * `function_demo`: demonstrates how functions can be used.
 * `development_kit`: provides ESP32-MeshKit and ESP32-Buddy application demos.
-* `maliyun_linkkit`: provides ESP32-MeshKit application demos.
-* `solution`: offers a routerless solution, as well as the solutions for indoor positioning, street light control, etc.
+* `maliyun_linkkit`: ESP32-Mesh access to Alibaba Cloud platform example.
+* `solution`: offers a routerless solution, as well as the solutions for street light control, etc.
 
 # Using Examples
 

examples/development_kit/README.md

@@ -206,4 +206,5 @@ Long press on a certain ESP-MESH device on the list of added devices and in the
 </table>
 
 ## Drivers
-All the hardware drivers for ESP32-MeshKit use the corresponding driver code in [esp-iot-solution](https://github.com/espressif/esp-iot-solution). You can visit this repository for any code update.
+
+All the hardware drivers for ESP32-MeshKit use the corresponding driver code in [esp-iot-solution](https://github.com/espressif/esp-iot-solution). You can visit this repository for any code update.

examples/development_kit/README_cn.md

@@ -74,7 +74,6 @@ ESP-Mesh App 可帮助您调研和了解 ESP-MESH，并进行二次开发。上
 
 * 输入配置信息：
     * **Wi-Fi 名称**：手机所连 Wi-Fi 名称。注意仅支持 2.4 G；
-
     * **Mesh ID**：ESP-MESH 网络唯一标识符，默认为路由器的 Mac 地址，相同的 `Mesh ID` 将组成一个网络；
     * **密码**：Wi-Fi 密码；
     * **More**：点此即可查看和修改有关 ESP-MESH 网络内部的默认配置。更多配置详情，请参照 [ESP-MESH 编程指南](https://docs.espressif.com/projects/esp-idf/zh_CN/stable/api-reference/network/esp_mesh.html)。
@@ -106,6 +105,7 @@ ESP-Mesh App 开始传输配置信息，并进行以下操作：
     </table>
 
 ### 2. 添加设备
+
 如果 App 发现处于配网模式的 ESP-MESH 设备，会自动弹出设备添加框，点击`加入网络`即完成配网。
 
 <table>
@@ -144,6 +144,7 @@ ESP-Mesh App 开始传输配置信息，并进行以下操作：
    </table>
 
 ### 4. “群组”界面
+
 * **默认群组**：App 默认按照设备类型对设备进行分组，默认群组禁止解散
 * **添加群组**：您可以添加自定群组，对设备进行分组控制
 
@@ -155,6 +156,7 @@ ESP-Mesh App 开始传输配置信息，并进行以下操作：
    </table>
 
 ### 5. “我的”界面
+
 * **设置**：App 的版本信息，App 升级及常见问题解答；
 
 * **拓扑结构**：ESP-MESH 网络结构及组网信息。您可以通过长按节点，获取设备的组网信息。
@@ -172,7 +174,6 @@ ESP-Mesh App 开始传输配置信息，并进行以下操作：
 长按已添加设备列表中的 ESP-MESH 设备，在弹出的对话框中选择`固件升级`，选择以下任一方式升级固件：
 
 * 固件拷贝升级：您可以将固件直接拷贝到手机的 `文件管理/手机存储/Espressif/Esp32/upgrade` 文件夹中。
-
 * 远程链接升级：您可以将固件存放在云端（如 GitHub 上）或局域网内创建的 HTTP 服务器，在 App 端输入固件链接地址。
 
 <table>
@@ -184,4 +185,5 @@ ESP-Mesh App 开始传输配置信息，并进行以下操作：
 </table>
 
 ## 驱动说明
-ESP32-MeshKit 的硬件驱动全部使用了 [esp-iot-solution](https://github.com/espressif/esp-iot-solution) 中的相关驱动代码，可通过仓库链接进行代码更新。
+
+ESP32-MeshKit 的硬件驱动全部使用了 [esp-iot-solution](https://github.com/espressif/esp-iot-solution) 中的相关驱动代码，可通过仓库链接进行代码更新。