From 2d4e0a4496a1199b57c4d2f4d9fecafbf6272396 Mon Sep 17 00:00:00 2001 From: Krzysztof Budzynski Date: Thu, 10 Sep 2020 22:29:24 +0800 Subject: [PATCH] docs: Add explanation of hello_world folder contents --- docs/en/get-started/index.rst | 23 +++++----- docs/zh_CN/get-started/index.rst | 2 +- examples/get-started/hello_world/README.md | 51 +++++++++++++++++++++- 3 files changed, 61 insertions(+), 15 deletions(-) diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index 2aa1d6799e..d48c823a8c 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -50,17 +50,16 @@ Hardware: Software: +You have a choice to either download and install the following software manually -.. note:: + * **Toolchain** to compile code for {IDF_TARGET_NAME} + * **Build tools** - CMake and Ninja to build a full **Application** for {IDF_TARGET_NAME} + * **ESP-IDF** that essentially contains API (software libraries and source code) for {IDF_TARGET_NAME} and scripts to operate the **Toolchain** - If you are using our official `Eclipse Plugin `_ or `VSCode Extension `_ then you can skip downloading esp-idf and toolchain manually and instead follow onboarding process from the IDEs itself, `Eclipse Plugin Installing IDF Plugin `_ or `VSCode Extension Onboarding `_ - - -* **IDE** of your choice to write programs in C, we have official support for `Eclipse Plugin `_ and :doc:`VSCode Extension ` -* **Toolchain** to compile code for {IDF_TARGET_NAME} -* **Build tools** - CMake and Ninja to build a full **Application** for {IDF_TARGET_NAME} -* **ESP-IDF** that essentially contains API (software libraries and source code) for {IDF_TARGET_NAME} and scripts to operate the **Toolchain** +**or** get through the onboarding process using the following official plugins for integrated development environments (IDE) described in separate documents + * `Eclipse Plugin `_ (`installation link `_) + * `VS Code Extension `_ (`onboarding `_) .. figure:: ../../_static/what-you-need.png :align: center @@ -278,7 +277,7 @@ Step 5. Start a Project Now you are ready to prepare your application for {IDF_TARGET_NAME}. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. -Copy :example:`get-started/hello_world` to ``~/esp`` directory: +Copy the project :example:`get-started/hello_world` to ``~/esp`` directory: Linux and macOS ~~~~~~~~~~~~~~~ @@ -406,7 +405,7 @@ This command will compile the application and all ESP-IDF components, then it wi ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin or run 'idf.py -p PORT flash' -If there are no errors, the build will finish by generating the firmware binary .bin file. +If there are no errors, the build will finish by generating the firmware binary .bin files. .. _get-started-flash: @@ -414,7 +413,7 @@ If there are no errors, the build will finish by generating the firmware binary Step 9. Flash onto the Device ============================= -Flash the binaries that you just built onto your {IDF_TARGET_NAME} board by running: +Flash the binaries that you just built (bootloader.bin, partition-table.bin and hello-world.bin) onto your {IDF_TARGET_NAME} board by running: .. code-block:: bash @@ -537,7 +536,7 @@ When flashing, you will see the output log similar to the following: If there are no issues by the end of the flash process, the board will reboot and start up the “hello_world” application. -If you'd like to use the Eclipse/VSCode IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide `, :doc:`VSCode guide `. +If you'd like to use the Eclipse or VS Code IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide `, :doc:`VS Code guide `. .. _get-started-build-monitor: diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 929ca89873..f7926b793a 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -395,7 +395,7 @@ Windows 操作系统 第九步：烧录到设备 ============================= -请使用以下命令，将刚刚生成的二进制文件烧录至您的 {IDF_TARGET_NAME} 开发板： +请使用以下命令，将刚刚生成的二进制文件烧录 (bootloader.bin, partition-table.bin 和 hello-world.bin) 至您的 {IDF_TARGET_NAME} 开发板： ``idf.py -p PORT [-b BAUD] flash`` diff --git a/examples/get-started/hello_world/README.md b/examples/get-started/hello_world/README.md index 4fb3c40c13..0539ac7b24 100644 --- a/examples/get-started/hello_world/README.md +++ b/examples/get-started/hello_world/README.md @@ -1,5 +1,52 @@ # Hello World Example -Starts a FreeRTOS task to print "Hello World" +Starts a FreeRTOS task to print "Hello World". -See the README.md file in the upper level 'examples' directory for more information about examples. +(See the README.md file in the upper level 'examples' directory for more information about examples.) + +## How to use example + +Follow detailed instructions provided specifically for this example. + +Select the instructions depending on Espressif chip installed on your development board: + +- [ESP32 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/stable/get-started/index.html) +- [ESP32-S2 Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/get-started/index.html) + + +## Example folder contents + +The project **hello_world** contains one source file in C language [hello_world_main.c](main/hello_world_main.c). The file is located in folder [main](main). + +ESP-IDF projects are build using CMake. The project build configuration is contained in `CMakeLists.txt` files that provide set of directives and instructions describing the project's source files and targets (executable, library, or both). + +Below is short explanation of remaining files in the project folder. + +``` +├── CMakeLists.txt +├── example_test.py Python script used for automated example testing +├── main +│   ├── CMakeLists.txt +│   ├── component.mk Component make file +│   └── hello_world_main.c +├── Makefile Makefile used by legacy GNU Make +└── README.md This is the file you are currently reading +``` + +For more information on structure and contents of ESP-IDF projects, please refer to Section [Build System](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html) of the ESP-IDF Programming Guide. + +## Troubleshooting + +* Program upload failure + + * Hardware connection is not correct: run `idf.py -p PORT monitor`, and reboot your board to see if there are any output logs. + * The baud rate for downloading is too high: lower your baud rate in the `menuconfig` menu, and try again. + +## Technical support and feedback + +Please use the following feedback channels: + +* For technical queries, go to the [esp32.com](https://esp32.com/) forum +* For a feature request or bug report, create a [GitHub issue](https://github.com/espressif/esp-idf/issues) + +We will get back to you as soon as possible.