Update doc: Arduino as IDF component; fixes #5833

docs/source/esp-idf_component.rst

@@ -1,20 +1,31 @@
-##############################
-Arduino as a ESP-IDF component
-##############################
+###############################
+Arduino as an ESP-IDF component
+###############################
+
+This method is recommended for advanced users. To use this method, you will need to have the ESP-IDF toolchain installed.
+
+For a simplified method, see `Installing using Boards Manager <https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#installing-using-boards-manager>`_.
 
 ESP32 Arduino lib-builder
 -------------------------
 
-For a simplified method, see `lib-builder <https://github.com/espressif/esp32-arduino-lib-builder>`_.
+If you don't need any modifications in the default Arduino ESP32 core, we recommend you to install using the Boards Manager.
+
+Arduino Lib Builder is the tool that integrates ESP-IDF into Arduino. It allows you to customize the default settings used by Espressif and try them in Arduino IDE.
+
+For more information see `Arduino lib builder <https://github.com/espressif/esp32-arduino-lib-builder>`_
+
 
 Installation
 ------------
 
-.. note:: Latest Arduino Core ESP32 version is now compatible with `ESP-IDF v4.4 <https://github.com/espressif/esp-idf/tree/release/v4.4>`_. Please consider this compability when using Arduino as component in ESP-IDF.
+.. note:: Latest Arduino Core ESP32 version is now compatible with `ESP-IDF v4.4 <https://github.com/espressif/esp-idf/tree/release/v4.4>`_. Please consider this compatibility when using Arduino as a component in ESP-IDF.
+
+#. Download and install `ESP-IDF <https://github.com/espressif/esp-idf>`_.
 
-- Download and install `ESP-IDF <https://github.com/espressif/esp-idf>`_.
-- Create blank ESP-IDF project (use sample_project from /examples/get-started) or choose one of the examples.
-- In the project folder, create a new folder called `components` and clone this repository inside the new created folder.
+   * For more information see `Get Started <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#installation-step-by-step>`_.
+#. Create a blank ESP-IDF project (use sample_project from /examples/get-started) or choose one of the examples.
+#. In the project folder, create a new folder called ``components`` and clone this repository inside the newly created folder.
 
 .. code-block:: bash
     
@@ -26,27 +37,44 @@ Installation
     cd ../.. && \
     idf.py menuconfig
 
+Configuration
+-------------
+
+Depending on one of the two following options, in the menuconfig set the appropriate settings.
+
+Go to the section ``Arduino Configuration --->``
+
+1. For usage of ``app_main()`` function - Turn off ``Autostart Arduino setup and loop on boot``
+2. For usage of ``setup()`` and ``loop()`` functions - Turn on ``Autostart Arduino setup and loop on boot``
+
+Experienced users can explore other options in the Arduino section.
+
+After the setup you can save and exit:
+
+- Save [S]
+- Confirm default filename [Enter]
+- Close confirmation window [Enter] or [Space] or [Esc]
+- Quit [Q]
+
 Option 1. Using Arduino setup() and loop()
 ******************************************
 
-- The `idf.py menuconfig` has some Arduino options.
-    - Turn on `Autostart Arduino setup and loop on boot`.
-    - In main folder rename file `main.c` to `main.cpp`.
-    - In main folder open file `CMakeList.txt` and change `main.c` to `main.cpp` as described below.
-
-.. code-block:: bash
+- In main folder rename file `main.c` to `main.cpp`.
 
-    idf_component_register(SRCS "main.cpp" INCLUDE_DIRS ".")
+- In main folder open file `CMakeList.txt` and change `main.c` to `main.cpp` as described below.
 
-- Your main.cpp should be formated like any other sketch.
+- Your main.cpp should be formatted like any other sketch.
 
 .. code-block:: c
 
     //file: main.cpp
     #include "Arduino.h"
 
     void setup(){
-        Serial.begin(115200);
+      Serial.begin(115200);
+      while(!Serial){
+        ; // wait for serial port to connect
+      }
     }
 
     void loop(){
@@ -57,10 +85,10 @@ Option 1. Using Arduino setup() and loop()
 Option 2. Using ESP-IDF appmain()
 *********************************
 
-- You need to implement ``app_main()`` and call ``initArduino();`` in it.
+In main.c or main.cpp you need to implement ``app_main()`` and call ``initArduino();`` in it.
 
 Keep in mind that setup() and loop() will not be called in this case.
-If you plan to base your code on examples provided in `examples <https://github.com/espressif/esp-idf/tree/master/examples>`_, please make sure to move the app_main() function in main.cpp from the files in the example.
+Furthermore the ``app_main()`` is single execution as a normal function so if you need an infinite loop as in Arduino place it there.
 
 .. code-block:: cpp
 
@@ -69,28 +97,39 @@ If you plan to base your code on examples provided in `examples <https://github.
 
     extern "C" void app_main()
     {
-        initArduino();
-        pinMode(4, OUTPUT);
-        digitalWrite(4, HIGH);
-        //do your own thing
-    }
+      initArduino();
+
+      // Arduino-like setup()
+      Serial.begin(115200);
+      while(!Serial){
+        ; // wait for serial port to connect
+      }
+
+      // Arduino-like loop()
+      while(true){
+        Serial.println("loop");
+      }
 
-- "Disable mutex locks for HAL"
-- If enabled, there will be no protection on the drivers from concurently accessing them from another thread/interrupt/core
-    - "Autoconnect WiFi on boot"
-- If enabled, WiFi will start with the last known configuration
-- Otherwise it will wait for WiFi.begin
+      // WARNING: if program reaches end of function app_main() the MCU will restart.
+    }
 
 Build, flash and monitor
 ************************
 
 - For both options use command ``idf.py -p <your-board-serial-port> flash monitor``
-- It will build, upload and open serial monitor to your board.
+
+- The project will build, upload and open the serial monitor to your board
+
+  - Some boards require button combo press on the board: press-and-hold Boot button + press-and-release RST button, release Boot button
+
+  - After a successful flash, you may need to press the RST button again
+
+  - To terminate the serial monitor press [Ctrl] + [ ] ]
 
 Logging To Serial
 -----------------
 
-If you are writing code that does not require Arduino to compile and you want your `ESP_LOGx` macros to work in Arduino IDE, you can enable the compatibility by adding the following lines after:
+If you are writing code that does not require Arduino to compile and you want your `ESP_LOGx` macros to work in Arduino IDE, you can enable the compatibility by adding the following lines:
 
 .. code-block:: c
 
@@ -107,4 +146,4 @@ To fix that behavior, you need to set FreeRTOS tick rate to 1000Hz in `make menu
 Compilation Errors
 ------------------
 
-As commits are made to esp-idf and submodules, the codebases can develop incompatibilities which cause compilation errors.  If you have problems compiling, follow the instructions in `Issue #1142 <https://github.com/espressif/arduino-esp32/issues/1142>`_ to roll esp-idf back to a different version.
+As commits are made to esp-idf and submodules, the codebases can develop incompatibilities that cause compilation errors.  If you have problems compiling, follow the instructions in `Issue #1142 <https://github.com/espressif/arduino-esp32/issues/1142>`_ to roll esp-idf back to a different version.