Get Started\r
***********\r
\r
-This document is intended to help users set up the software environment for developement of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.\r
+This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.\r
\r
.. note::\r
The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.\r
To develop applications for ESP32 you need:\r
\r
* **PC** loaded with either Windows, Linux or Mac operating system\r
-* **Toolchain** to build the **Application** for ESP32\r
+* **Toolchain** to compile code for ESP32\r
+* **Build tools** CMake and Ninja to build a full **Application** for ESP32\r
* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**\r
* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_\r
* The **ESP32** board itself and a **USB cable** to connect it to the **PC**\r
\r
Development of applications for ESP32\r
\r
-Preparation of development environment consists of three steps:\r
+Development Environment Steps:\r
\r
1. Setup of **Toolchain**\r
-2. Getting of **ESP-IDF** from GitHub\r
-3. Installation and configuration of **Eclipse**\r
+2. Getting **ESP-IDF** from GitHub\r
\r
-You may skip the last step, if you prefer to use different editor.\r
-\r
-Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:\r
+Once the development environment is set up, we will follow these steps to create an ESP-IDF application:\r
\r
1. Configuration of a **Project** and writing the code\r
2. Compilation of the **Project** and linking it to build an **Application**\r
-3. Flashing (uploading) of the **Application** to **ESP32**\r
-4. Monitoring / debugging of the **Application**\r
-\r
-See instructions below that will walk you through these steps.\r
+3. Flashing (uploading) the compiled **Application** to **ESP32** over a USB/serial connection\r
+4. Monitoring / debugging of the **Application** output via USB/serial\r
\r
\r
-Guides\r
-======\r
+Development Board Guides\r
+========================\r
\r
-If you have one of ESP32 development boards listed below, click on provided links to get you up and running.\r
+If you have one of ESP32 development boards listed below, click on the link for hardware setup:\r
\r
.. toctree::\r
:maxdepth: 1\r
\r
.. highlight:: batch\r
\r
-For Windows Command Prompt users, the equivalent commands are::\r
+For **Windows Command Prompt** users, the equivalent commands are::\r
\r
mkdir %userprofile%\esp\r
cd %userprofile%\esp\r
\r
.. highlight:: batch\r
\r
-For Windows Command Prompt users, the equivalent commands are::\r
+For **Windows Command Prompt** users, the equivalent commands are::\r
\r
cd %userprofile%\esp\r
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world\r
\r
.. important::\r
\r
- The esp-idf build system does not support spaces in paths to esp-idf or to projects.\r
+ The esp-idf build system does not support spaces in the path to either esp-idf or to projects.\r
\r
\r
.. _get-started-connect:\r
\r
You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.\r
\r
-\r
.. _get-started-configure:\r
\r
Configure\r
\r
.. highlight:: batch\r
\r
-For Windows Command Prompt users::\r
+For **Windows Command Prompt** users::\r
\r
cd %userprofile%\esp\hello_world\r
idf.py menuconfig\r
Here are couple of tips on navigation and use of ``menuconfig``:\r
\r
* Use up & down arrow keys to navigate the menu.\r
-* Use Enter key to go into a submenu, Escape key to go out or to exit.\r
+* Use Enter key to go into a submenu, Escape key to go up a level or exit.\r
* Type ``?`` to see a help screen. Enter key exits the help screen.\r
* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"\r
* Pressing ``?`` while highlighting a configuration item displays help about that item.\r
\r
If there are no issues, at the end of build process, you should see messages describing progress of flashing the project binary image onto the ESP32. Finally, the module will be reset and "hello_world" application will be running there.\r
\r
-If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.\r
+.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.\r
\r
\r
.. _get-started-build-monitor:\r
e���)(Xn@�y.!��(�PW+)��Hn9a/9�!�t5��P�~�k��e�ea�5�jA\r
~zY��Y(1�,1\15�� e���)(Xn@�y.!Dr�zY(�\ 6jpi�|�+z5Ymvp\r
\r
- or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.\r
+ or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.\r
\r
.. note::\r
\r
\r
.. highlight:: batch\r
\r
-For Windows Command Prompt users::\r
+For **Windows Command Prompt** users::\r
\r
cd %userprofile%\esp\esp-idf\r
git pull\r
\r
.. highlight:: bash\r
\r
-If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::\r
+To use a specific release of ESP-IDF, e.g. `v2.1`, run::\r
\r
cd ~/esp\r
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1\r
\r
.. highlight:: batch\r
\r
-For Windows Command Prompt users::\r
+For **Windows Command Prompt** users::\r
\r
cd %userprofile%\esp\r
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1\r
projects / esp-idf / commitdiff