From 1a96b11733ef703915f60024271bc45b79697411 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 16 Feb 2022 13:10:21 +0100 Subject: [PATCH 1/7] Documentation update preview (esp idf component) --- docs/source/esp-idf_component.rst | 76 +++++++++++++++++++++++-------- 1 file changed, 58 insertions(+), 18 deletions(-) diff --git a/docs/source/esp-idf_component.rst b/docs/source/esp-idf_component.rst index 3be9d85575d..e88fc4c4e59 100644 --- a/docs/source/esp-idf_component.rst +++ b/docs/source/esp-idf_component.rst @@ -5,7 +5,8 @@ Arduino as a ESP-IDF component ESP32 Arduino lib-builder ------------------------- -For a simplified method, see `lib-builder `_. +For a simplified method, see `Installing using Boards Manager `_. + Installation ------------ @@ -13,6 +14,8 @@ Installation .. note:: Latest Arduino Core ESP32 version is now compatible with `ESP-IDF v4.4 `_. Please consider this compability when using Arduino as component in ESP-IDF. - Download and install `ESP-IDF `_. + + - For more information see `Installation step by step `_. - 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. @@ -26,17 +29,32 @@ Installation cd ../.. && \ idf.py menuconfig +Configuration +------------- + +Depending on one the two following options, in the menuconfig set the appropriate settings. +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. +While in the menuconfig go to `Arduino Configuration --->` -.. code-block:: bash +- Turn on ``Autostart Arduino setup and loop on boot`` +- Turn off ``Disable mutex locks for HAL`` +- Save and exit - idf_component_register(SRCS "main.cpp" INCLUDE_DIRS ".") +- 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. - Your main.cpp should be formated like any other sketch. @@ -57,10 +75,16 @@ Option 1. Using Arduino setup() and loop() Option 2. Using ESP-IDF appmain() ********************************* -- You need to implement ``app_main()`` and call ``initArduino();`` in it. +While in the menuconfig go to `Arduino Configuration --->` + +- Turn off ``Autostart Arduino setup and loop on boot`` +- Turn on ``Disable mutex locks for HAL`` +- Save and exit + +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 `_, 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 normal function so if you need infinite loop as in Arduino place it there. .. code-block:: cpp @@ -69,23 +93,39 @@ If you plan to base your code on examples provided in `examples flash monitor`` -- It will build, upload and open serial monitor to your board. + + - The port is usually ``/dev/ttyUSB0`` search the active port with ``ls /dev/ttyUSB*`` + +- The project will build, upload and open 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 successful flash you may need to press RST button again + + - To terminate the serial monitor press [Ctrl] + [ ] ] Logging To Serial ----------------- From a92758b8ef433516d6ae47731af9cf470c1d9626 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Wed, 16 Feb 2022 15:04:48 +0100 Subject: [PATCH 2/7] Deleted mention about HAL locks from doc --- docs/source/esp-idf_component.rst | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/docs/source/esp-idf_component.rst b/docs/source/esp-idf_component.rst index e88fc4c4e59..a92e4724e8d 100644 --- a/docs/source/esp-idf_component.rst +++ b/docs/source/esp-idf_component.rst @@ -7,6 +7,8 @@ ESP32 Arduino lib-builder For a simplified method, see `Installing using Boards Manager `_. +To build your own Arduino core see `Arduino lib builder `_ + Installation ------------ @@ -33,6 +35,13 @@ Configuration ------------- Depending on one the two following options, in the menuconfig set the appropriate settings. +Go to 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] @@ -46,12 +55,6 @@ After the setup you can save and exit: Option 1. Using Arduino setup() and loop() ****************************************** -While in the menuconfig go to `Arduino Configuration --->` - -- Turn on ``Autostart Arduino setup and loop on boot`` -- Turn off ``Disable mutex locks for HAL`` -- Save and exit - - 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. @@ -75,12 +78,6 @@ While in the menuconfig go to `Arduino Configuration --->` Option 2. Using ESP-IDF appmain() ********************************* -While in the menuconfig go to `Arduino Configuration --->` - -- Turn off ``Autostart Arduino setup and loop on boot`` -- Turn on ``Disable mutex locks for HAL`` -- Save and exit - 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. @@ -107,11 +104,6 @@ Furthermore the ``app_main()`` is single execution as normal function so if you // WARNING: if program reaches end of function app_main() the MCU will restart. } -- "Disable mutex locks for HAL" - - - If enabled, there will be no protection on the drivers from concurently accessing them from another thread/interrupt/core - - Build, flash and monitor ************************ From f62b4717e995a52bd50f28ce6ba09ee163af6a7f Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Thu, 17 Feb 2022 11:49:06 +0100 Subject: [PATCH 3/7] Finished formatting doc - arduino as idf component --- docs/source/esp-idf_component.rst | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/source/esp-idf_component.rst b/docs/source/esp-idf_component.rst index a92e4724e8d..abad14a657a 100644 --- a/docs/source/esp-idf_component.rst +++ b/docs/source/esp-idf_component.rst @@ -2,24 +2,29 @@ Arduino as a 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 `_. + ESP32 Arduino lib-builder ------------------------- -For a simplified method, see `Installing using Boards Manager `_. +If you don't need any modifications in the default Arduino ESP32 core, we recommend you to install using the Boards Manager. -To build your own Arduino core see `Arduino lib builder `_ +Arduino lib builder will allow you to build your own version of Arduino core for Arduino IDE. +To build your own Arduino core see `Arduino lib builder `_ Installation ------------ .. note:: Latest Arduino Core ESP32 version is now compatible with `ESP-IDF v4.4 `_. Please consider this compability when using Arduino as component in ESP-IDF. -- Download and install `ESP-IDF `_. +#. Download and install `ESP-IDF `_. - - For more information see `Installation step by step `_. -- 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 `_. +#. 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. .. code-block:: bash @@ -35,6 +40,7 @@ Configuration ------------- Depending on one the two following options, in the menuconfig set the appropriate settings. + Go to section ``Arduino Configuration --->`` 1. For usage of ``app_main()`` function - Turn off ``Autostart Arduino setup and loop on boot`` @@ -45,11 +51,8 @@ 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() @@ -59,7 +62,7 @@ Option 1. Using Arduino setup() and loop() - 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 From 4841cc7bb82699f2afd63bc6def208a84689a124 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Fri, 18 Feb 2022 08:20:36 +0100 Subject: [PATCH 4/7] Fixes in doc --- docs/source/esp-idf_component.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/source/esp-idf_component.rst b/docs/source/esp-idf_component.rst index abad14a657a..6474cd37540 100644 --- a/docs/source/esp-idf_component.rst +++ b/docs/source/esp-idf_component.rst @@ -18,7 +18,8 @@ To build your own Arduino core see `Arduino lib builder `_. 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 `_. Please consider this compability when using Arduino as component in ESP-IDF. #. Download and install `ESP-IDF `_. @@ -70,7 +71,10 @@ Option 1. Using Arduino setup() and loop() #include "Arduino.h" void setup(){ - Serial.begin(115200); + Serial.begin(115200); + while(!Serial){ + ; // wait for serial port to connect + } } void loop(){ @@ -97,11 +101,13 @@ Furthermore the ``app_main()`` is single execution as normal function so if you // Arduino-like setup() Serial.begin(115200); + while(!Serial){ + ; // wait for serial port to connect + } // Arduino-like loop() - while(!Serial){ + while(true){ Serial.println("loop"); - delay(1000); } // WARNING: if program reaches end of function app_main() the MCU will restart. From 2bff48b36ed76bc937568e057b8a81a08c8fa58c Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Fri, 18 Feb 2022 08:32:32 +0100 Subject: [PATCH 5/7] Hopefully fixing note block --- docs/source/esp-idf_component.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/esp-idf_component.rst b/docs/source/esp-idf_component.rst index 6474cd37540..d335a35c9c7 100644 --- a/docs/source/esp-idf_component.rst +++ b/docs/source/esp-idf_component.rst @@ -19,7 +19,7 @@ Installation ------------ .. note:: - Latest Arduino Core ESP32 version is now compatible with `ESP-IDF v4.4 `_. Please consider this compability when using Arduino as component in ESP-IDF. + Latest Arduino Core ESP32 version is now compatible with `ESP-IDF v4.4 `_. Please consider this compability when using Arduino as component in ESP-IDF. #. Download and install `ESP-IDF `_. From d05a210c370236099fe514bb3f5b873df92a482e Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Fri, 18 Feb 2022 09:23:53 +0100 Subject: [PATCH 6/7] Spelling fixes --- docs/source/esp-idf_component.rst | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/source/esp-idf_component.rst b/docs/source/esp-idf_component.rst index d335a35c9c7..88ddeee5898 100644 --- a/docs/source/esp-idf_component.rst +++ b/docs/source/esp-idf_component.rst @@ -1,6 +1,6 @@ -############################## -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. @@ -18,14 +18,13 @@ To build your own Arduino core see `Arduino lib builder `_. 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 `_. Please consider this compatibility when using Arduino as a component in ESP-IDF. #. Download and install `ESP-IDF `_. * For more information see `Get Started `_. -#. 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. +#. 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 @@ -40,9 +39,9 @@ Installation Configuration ------------- -Depending on one the two following options, in the menuconfig set the appropriate settings. +Depending on one of the two following options, in the menuconfig set the appropriate settings. -Go to section ``Arduino Configuration --->`` +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`` @@ -88,7 +87,7 @@ Option 2. Using ESP-IDF appmain() 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. -Furthermore the ``app_main()`` is single execution as normal function so if you need infinite loop as in Arduino place it there. +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 @@ -120,18 +119,18 @@ Build, flash and monitor - The port is usually ``/dev/ttyUSB0`` search the active port with ``ls /dev/ttyUSB*`` -- The project 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 successful flash you may need to press RST button again + - 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 @@ -148,4 +147,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 `_ 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 `_ to roll esp-idf back to a different version. From 3adc54498da665c3328826077d7b9959c2953c08 Mon Sep 17 00:00:00 2001 From: Tomas Pilny Date: Mon, 21 Feb 2022 11:41:44 +0100 Subject: [PATCH 7/7] Updated doc --- docs/source/esp-idf_component.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/source/esp-idf_component.rst b/docs/source/esp-idf_component.rst index 88ddeee5898..f153f267e6b 100644 --- a/docs/source/esp-idf_component.rst +++ b/docs/source/esp-idf_component.rst @@ -11,9 +11,10 @@ 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 will allow you to build your own version of Arduino core for Arduino IDE. +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 `_ -To build your own Arduino core see `Arduino lib builder `_ Installation ------------ @@ -84,7 +85,7 @@ Option 1. Using Arduino setup() and loop() Option 2. Using ESP-IDF appmain() ********************************* -In main.c or main cpp 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. Furthermore the ``app_main()`` is single execution as a normal function so if you need an infinite loop as in Arduino place it there. @@ -117,8 +118,6 @@ Build, flash and monitor - For both options use command ``idf.py -p flash monitor`` - - The port is usually ``/dev/ttyUSB0`` search the active port with ``ls /dev/ttyUSB*`` - - 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