From b5f3d6c83602325d21ba0f6c9974c6fd70d82fe6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Piln=C3=BD?= <34927466+PilnyTomas@users.noreply.github.com> Date: Wed, 23 Feb 2022 14:24:40 +0100 Subject: [PATCH] Update doc: Arduino as IDF component; fixes #5833 (#6299) Summary Updated documentation describing the usage of Arduino-esp32 core as ESP-IDF component. Impact Removed confusing mentions of advanced menuconfig options. Extended process of installation, setup, and usage. Related links Closes #5833 --- docs/source/esp-idf_component.rst | 103 ++++++++++++++++++++---------- 1 file changed, 71 insertions(+), 32 deletions(-) diff --git a/docs/source/esp-idf_component.rst b/docs/source/esp-idf_component.rst index 3be9d8557..f153f267e 100644 --- a/docs/source/esp-idf_component.rst +++ b/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 `_. ESP32 Arduino lib-builder ------------------------- -For a simplified method, see `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 `_ + 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. +.. 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 `_. -- Download and install `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 `_. +#. 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,19 +37,33 @@ 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 @@ -46,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(){ @@ -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 `_, 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 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 `_ 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. -- GitLab