From 43c6e77c2f4214d68f17b45c8f0f34de213dfc97 Mon Sep 17 00:00:00 2001 From: krzychb Date: Mon, 4 Feb 2019 21:51:50 +0100 Subject: [PATCH] Introduced installation steps to improve navigation through the installation process. Included some updates from GNU make section. --- docs/en/about.rst | 2 +- .../add-idf_path-to-profile.rst | 4 +- .../establish-serial-connection.rst | 30 +++++- .../get-started-devkitc-v2.rst | 10 +- .../get-started-cmake/get-started-devkitc.rst | 10 +- .../get-started-pico-kit-v3.rst | 12 +-- .../get-started-pico-kit.rst | 15 +-- .../get-started-wrover-kit-v2.rst | 14 +-- .../get-started-wrover-kit.rst | 16 +-- docs/en/get-started-cmake/index.rst | 100 +++++++++++------- .../get-started-cmake/linux-setup-scratch.rst | 2 +- docs/en/get-started-cmake/linux-setup.rst | 2 +- .../get-started-cmake/macos-setup-scratch.rst | 2 +- docs/en/get-started-cmake/macos-setup.rst | 2 +- .../windows-setup-scratch.rst | 2 +- docs/en/get-started-cmake/windows-setup.rst | 2 +- docs/zh_CN/get-started-cmake/index.rst | 4 + 17 files changed, 121 insertions(+), 108 deletions(-) diff --git a/docs/en/about.rst b/docs/en/about.rst index 3cd25190d8..fc86b65748 100644 --- a/docs/en/about.rst +++ b/docs/en/about.rst @@ -12,5 +12,5 @@ The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, 32 bit dual core chip with 600 D Espressif IoT Integrated Development Framework -The ESP-IDF, Espressif IoT Integrated Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32 using Windows, Linux and Mac OS operating systems. +The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32 using Windows, Linux and Mac OS operating systems. diff --git a/docs/en/get-started-cmake/add-idf_path-to-profile.rst b/docs/en/get-started-cmake/add-idf_path-to-profile.rst index b4f9c07088..87f9ae7c8a 100644 --- a/docs/en/get-started-cmake/add-idf_path-to-profile.rst +++ b/docs/en/get-started-cmake/add-idf_path-to-profile.rst @@ -32,7 +32,7 @@ You can set these environment variables for all users, or only for the current u - Click ``New...`` to add a new system variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\user-name\esp\esp-idf``. - Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt. -If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`. +If you got here from :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then you can continue with :ref:`get-started-get-packages-cmake`. .. _add-idf_path-to-profile-linux-macos-cmake: @@ -72,4 +72,4 @@ If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can e export IDF_PATH=~/esp/esp-idf export PATH="$IDF_PATH/tools:$PATH" -If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`. +If you got here from :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then you can continue with :ref:`get-started-get-packages-cmake`. diff --git a/docs/en/get-started-cmake/establish-serial-connection.rst b/docs/en/get-started-cmake/establish-serial-connection.rst index 4c89accc84..a02e04c88b 100644 --- a/docs/en/get-started-cmake/establish-serial-connection.rst +++ b/docs/en/get-started-cmake/establish-serial-connection.rst @@ -13,11 +13,29 @@ Connect the ESP32 board to the PC using the USB cable. If device driver does not Below are the links to drivers for ESP32 boards produced by Espressif: -* ESP32-PICO-KIT and ESP32-DevKitC - `CP210x USB to UART Bridge VCP Drivers `_ -* ESP32-WROVER-KIT and ESP32 Demo Board - `FTDI Virtual COM Port Drivers `_ +.. csv-table:: + :header: Development Board, USB Driver, Remarks + :widths: 40, 20, 40 -Above drivers are primarily for reference. They should already be bundled with the operating system and installed automatically once one of listed boards is connected to the PC. + :ref:`ESP32-DevKitC `, `CP210x`_ + `ESP32-LyraT `_, `CP210x`_ + `ESP32-LyraTD-MSC `_, `CP210x`_ + :ref:`ESP32-PICO-KIT `, `CP210x`_ + :ref:`ESP-WROVER-KIT `, `FTDI`_ + :ref:`ESP32 Demo Board `, `FTDI`_ + `ESP-Prog`_, `FTDI`_, Programmer board (w/o ESP32) + `ESP32-MeshKit-Sense `_, n/a, Use with `ESP-Prog`_ + `ESP32-Sense Kit `_, n/a, Use with `ESP-Prog`_ + +.. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers +.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm +.. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board + +* CP210x: `CP210x USB to UART Bridge VCP Drivers `_ +* FTDI: `FTDI Virtual COM Port Drivers `_ + +The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with and operating system and automatically installed upon connecting one of the listed boards to the PC. Check port on Windows @@ -55,8 +73,10 @@ MacOS :: ls /dev/cu.* +.. note:: + + MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI. -.. note: MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI. .. _linux-dialout-group-cmake: @@ -131,6 +151,6 @@ If you can see readable log output, it means serial connection is working and yo Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal. -If you got here from section :ref:`get-started-connect-cmake` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure-cmake`. +If you got here from :ref:`get-started-connect-cmake` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure-cmake`. .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader diff --git a/docs/en/get-started-cmake/get-started-devkitc-v2.rst b/docs/en/get-started-cmake/get-started-devkitc-v2.rst index fd566387e5..4892b5ce94 100644 --- a/docs/en/get-started-cmake/get-started-devkitc-v2.rst +++ b/docs/en/get-started-cmake/get-started-devkitc-v2.rst @@ -11,6 +11,8 @@ What You Need * 1 × USB A / micro USB B cable * 1 × PC loaded with Windows, Linux or Mac OS +If you want to start using this board right now, go directly to Section `Start Application Development`_. + Overview -------- @@ -63,13 +65,7 @@ Start Application Development Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage. -To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps: - -* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language -* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible -* :ref:`get-started-build-cmake` for an example application -* :ref:`get-started-flash-cmake` to run code on the ESP32 -* :ref:`get-started-build-monitor-cmake` instantly what the application is doing +To start development of applications, proceed to Section :doc:`index`, that will walk you through the :ref:`get-started-step-by-step-cmake`. Related Documents diff --git a/docs/en/get-started-cmake/get-started-devkitc.rst b/docs/en/get-started-cmake/get-started-devkitc.rst index 483a0ed622..86e0bd52a0 100644 --- a/docs/en/get-started-cmake/get-started-devkitc.rst +++ b/docs/en/get-started-cmake/get-started-devkitc.rst @@ -11,6 +11,8 @@ What You Need * 1 × USB A / micro USB B cable * 1 × PC loaded with Windows, Linux or Mac OS +If you want to start using this board right now, go directly to Section `Start Application Development`_. + Overview -------- @@ -78,13 +80,7 @@ Start Application Development Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage. -To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps: - -* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language -* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible -* :ref:`get-started-build-cmake` for an example application -* :ref:`get-started-flash-cmake` to run code on the ESP32 -* :ref:`get-started-build-monitor-cmake` instantly what the application is doing +To start development of applications, proceed to Section :doc:`index`, that will walk you through the :ref:`get-started-step-by-step-cmake`. Board Dimensions diff --git a/docs/en/get-started-cmake/get-started-pico-kit-v3.rst b/docs/en/get-started-cmake/get-started-pico-kit-v3.rst index 3abd213d4e..16f792498f 100644 --- a/docs/en/get-started-cmake/get-started-pico-kit-v3.rst +++ b/docs/en/get-started-cmake/get-started-pico-kit-v3.rst @@ -11,6 +11,8 @@ What You Need * 1 × USB A / Micro USB B cable * 1 × PC loaded with Windows, Linux or Mac OS +If you want to start using this board right now, go directly to Section `Start Application Development`_. + Overview -------- @@ -45,17 +47,11 @@ BOOT Button Start Application Development ------------------------------- +----------------------------- Before powering up the ESP32-PICO-KIT V3, please make sure that the board has been received in good condition with no obvious signs of damage. -To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps: - -* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language -* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible -* :ref:`get-started-build-cmake` for an example application -* :ref:`get-started-flash-cmake` to run code on the ESP32 -* :ref:`get-started-build-monitor-cmake` instantly what the application is doing +To start development of applications, proceed to Section :doc:`index`, that will walk you through the :ref:`get-started-step-by-step-cmake`. Related Documents diff --git a/docs/en/get-started-cmake/get-started-pico-kit.rst b/docs/en/get-started-cmake/get-started-pico-kit.rst index 9d73f34cb0..d011691178 100644 --- a/docs/en/get-started-cmake/get-started-pico-kit.rst +++ b/docs/en/get-started-cmake/get-started-pico-kit.rst @@ -1,6 +1,5 @@ ESP32-PICO-KIT V4 Getting Started Guide (CMake) =============================================== - This user guide shows how to get started with the ESP32-PICO-KIT V4 mini development board. For description of other versions of the ESP32-PICO-KIT check :doc:`../hw-reference/index`. @@ -12,7 +11,7 @@ What You Need * 1 × USB A / Micro USB B cable * 1 × PC loaded with Windows, Linux or Mac OS -If you like to start using this board right now, go directly to section `Start Application Development`_. +If you want to start using this board right now, go directly to Section `Start Application Development`_. Overview @@ -28,7 +27,7 @@ For easy interfacing, all the IO signals and system power on ESP32-PICO-D4 are l The 2 x 3 pads not populated with pin headers are internally connected to the flash memory embedded in the ESP32-PICO-D4 SIP module. For more details see module's datasheet in `Related Documents`_. -The board dimensions are 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4"), see section `Board Dimensions`_. An overview functional block diagram is shown below. +The board dimensions are 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4"), see Section `Board Dimensions`_. An overview functional block diagram is shown below. .. figure:: ../../_static/esp32-pico-kit-v4-functional-block-diagram.png :align: center @@ -54,7 +53,7 @@ Micro USB Port 5V Power On LED This light emitting diode lits when the USB or an external 5V power supply is applied to the board. For details see schematic in `Related Documents`_. I/O - All the pins on ESP32-PICO-D4 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc. For details please see section `Pin Descriptions`_. + All the pins on ESP32-PICO-D4 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc. For details please see Section `Pin Descriptions`_. BOOT Button Holding down the Boot button and pressing the EN button initiates the firmware download mode. Then user can download firmware through the serial port. EN Button @@ -89,13 +88,7 @@ Start Application Development Before powering up the ESP32-PICO-KIT V4, please make sure that the board has been received in good condition with no obvious signs of damage. -To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps: - -* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language -* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible -* :ref:`get-started-build-cmake` for an example application -* :ref:`get-started-flash-cmake` to run code on the ESP32 -* :ref:`get-started-build-monitor-cmake` instantly what the application is doing +To start development of applications, proceed to Section :doc:`index`, that will walk you through the :ref:`get-started-step-by-step-cmake`. Pin Descriptions diff --git a/docs/en/get-started-cmake/get-started-wrover-kit-v2.rst b/docs/en/get-started-cmake/get-started-wrover-kit-v2.rst index db31f20542..c896fd4fa6 100644 --- a/docs/en/get-started-cmake/get-started-wrover-kit-v2.rst +++ b/docs/en/get-started-cmake/get-started-wrover-kit-v2.rst @@ -3,7 +3,7 @@ ESP-WROVER-KIT V2 Getting Started Guide (CMake) This user guide shows how to get started with ESP-WROVER-KIT V2 development board including description of its functionality and configuration options. For description of other versions of the ESP-WROVER-KIT check :doc:`../hw-reference/index`. -If you like to start using this board right now, go directly to section :ref:`esp-wrover-kit-v2-start-development-cmake`. +If you want to start using this board right now, go directly to Section :ref:`esp-wrover-kit-v2-start-development-cmake`. What You Need @@ -70,7 +70,7 @@ Boot USB USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32 module. Power Select - Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in section :ref:`esp-wrover-kit-v2-setup-options-cmake`, jumper header JP7. + Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in Section :ref:`esp-wrover-kit-v2-setup-options-cmake`, jumper header JP7. Power Key Power on/off button: toggling to the right powers the board on; toggling to the left powers the board off. 5V Input @@ -85,7 +85,7 @@ I/O All the pins on the ESP32 module are led out to the pin headers on the ESPWROVER-KIT. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc. Micro SD Card - Micro SD card slot for data storage: when ESP32 enters the download mode, GPIO2 cannot be held high. However, a pull-up resistor is required on GPIO2 to enable the Micro SD Card. By default, GPIO2 and the pull-up resistor R153 are disconnected. To enable the SD Card, use jumpers on JP1 as shown in section :ref:`esp-wrover-kit-v2-setup-options-cmake`. + Micro SD card slot for data storage: when ESP32 enters the download mode, GPIO2 cannot be held high. However, a pull-up resistor is required on GPIO2 to enable the Micro SD Card. By default, GPIO2 and the pull-up resistor R153 are disconnected. To enable the SD Card, use jumpers on JP1 as shown in Section :ref:`esp-wrover-kit-v2-setup-options-cmake`. LCD ESP-WROVER-KIT supports mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`esp-wrover-kit-v2-board-back-cmake`. @@ -161,13 +161,7 @@ Do not install any other jumpers. Now to Development ^^^^^^^^^^^^^^^^^^ -To start development of applications for ESP32-DevKitC, proceed to section :doc:`index`, that will walk you through the following steps: - -* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language -* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible -* :ref:`get-started-build-cmake` for an example application -* :ref:`get-started-flash-cmake` to run code on the ESP32 -* :ref:`get-started-build-monitor-cmake` instantly what the application is doing +To start development of applications, proceed to Section :doc:`index`, that will walk you through the :ref:`get-started-step-by-step-cmake`. Related Documents diff --git a/docs/en/get-started-cmake/get-started-wrover-kit.rst b/docs/en/get-started-cmake/get-started-wrover-kit.rst index df027a43ae..9cb908ba9b 100644 --- a/docs/en/get-started-cmake/get-started-wrover-kit.rst +++ b/docs/en/get-started-cmake/get-started-wrover-kit.rst @@ -3,8 +3,6 @@ ESP-WROVER-KIT V3 Getting Started Guide (CMake) This user guide shows how to get started with ESP-WROVER-KIT V3 development board including description of its functionality and configuration options. For description of other versions of the ESP-WROVER-KIT check :doc:`../hw-reference/index`. -If you like to start using this board right now, go directly to section :ref:`get-started-esp-wrover-kit-start-development-cmake`. - What You Need ------------- @@ -13,6 +11,8 @@ What You Need * 1 x Micro USB 2.0 Cable, Type A to Micro B * 1 × PC loaded with Windows, Linux or Mac OS +If you want to start using this board right now, go directly to Section `Start Application Development`_. + Overview ^^^^^^^^ @@ -70,7 +70,7 @@ Boot USB USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32 module. Power Select - Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in section :ref:`get-started-esp-wrover-kit-setup-options-cmake`, jumper header JP7. + Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in Section :ref:`get-started-esp-wrover-kit-setup-options-cmake`, jumper header JP7. Power Key Power on/off button: toggling to the right powers the board on; toggling to the left powers the board off. 5V Input @@ -354,8 +354,6 @@ LCD / U5 +---+-----------+------------+ -.. _get-started-esp-wrover-kit-start-development-cmake: - Start Application Development ----------------------------- @@ -380,13 +378,7 @@ Do not install any other jumpers. Now to Development ^^^^^^^^^^^^^^^^^^ -To start development of applications for ESP-WROVER-KIT, proceed to section :doc:`index`, that will walk you through the following steps: - -* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language -* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible -* :ref:`get-started-build-cmake` for an example application -* :ref:`get-started-flash-cmake` to run code on the ESP32 -* :ref:`get-started-build-monitor-cmake` instantly what the application is doing +To start development of applications, proceed to Section :doc:`index`, that will walk you through the :ref:`get-started-step-by-step-cmake`. Related Documents diff --git a/docs/en/get-started-cmake/index.rst b/docs/en/get-started-cmake/index.rst index 61cab8bf05..1d19dff7f0 100644 --- a/docs/en/get-started-cmake/index.rst +++ b/docs/en/get-started-cmake/index.rst @@ -19,7 +19,6 @@ ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single ch Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features. - What You Need ============= @@ -39,18 +38,30 @@ To develop applications for ESP32 you need: Development of applications for ESP32 -Steps to set up Development Environment: +.. _get-started-step-by-step-cmake: -1. Setup of **Toolchain** -2. Getting **ESP-IDF** from GitHub +Installation Step by Step +========================= -Once the development environment is set up, we will follow these steps to create an ESP-IDF application: +This is a detailed roadmap to walk you through the installation process. -1. Configuration of a **Project** and writing the code -2. Compilation of the **Project** and linking it to build an **Application** -3. Flashing (uploading) the compiled **Application** to **ESP32** over a USB/serial connection -4. Monitoring / debugging of the **Application** output via USB/serial +Setting up Development Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* :ref:`get-started-setup-toolchain-cmake` for :doc:`Windows `, :doc:`Linux ` or :doc:`MacOS ` +* :ref:`get-started-get-esp-idf-cmake` +* :ref:`get-started-setup-path-cmake` +* :ref:`get-started-get-packages-cmake` + +Creating Your First Project +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* :ref:`get-started-start-project-cmake` +* :ref:`get-started-connect-cmake` +* :ref:`get-started-configure-cmake` +* :ref:`get-started-build-cmake` +* :ref:`get-started-flash-cmake` +* :ref:`get-started-build-monitor-cmake` Development Board Guides ======================== @@ -66,11 +77,10 @@ If you have one of ESP32 development boards listed below, click on the link for If you have different board, move to sections below. - .. _get-started-setup-toolchain-cmake: -Setup Toolchain -=============== +Step 1. Set up Toolchain +======================== The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions. @@ -104,14 +114,12 @@ The quickest way to start development with ESP32 is by installing a prebuilt too We are an using ``esp`` subdirectory in your user's home directory (``~/esp`` on Linux and MacOS, ``%userprofile%\esp`` on Windows) to install everything needed for ESP-IDF. You can use any different directory, but will need to adjust the respective commands. -Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup-cmake`. - -Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf-cmake`. +Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to Section :ref:`get-started-customized-setup-cmake`. .. _get-started-get-esp-idf-cmake: -Get ESP-IDF -=========== +Step 2. Get ESP-IDF +=================== Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository `_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command. @@ -147,8 +155,8 @@ Consult :doc:`/versions` for information about which version of ESP-IDF to use i .. _get-started-setup-path-cmake: -Setup Environment Variables -=========================== +Step 3. Set Environment Variables +================================= ESP-IDF requires two environment variables to be set for normal operation: @@ -157,12 +165,29 @@ ESP-IDF requires two environment variables to be set for normal operation: These two variables should be set up on your PC, otherwise projects will not build. -Setting may be done manually, each time PC is restarted. Another option is to set them permanently in user profile. To do this, follow instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in section :doc:`add-idf_path-to-profile`. +Setting may be done manually, each time PC is restarted. Another option is to set them permanently in user profile. To do this, follow instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in Section :doc:`add-idf_path-to-profile`. + +.. _get-started-get-packages-cmake: + +Step 4. Install the Required Python Packages +============================================ + +Python packages required by ESP-IDF are located in the ``$IDF_PATH/requirements.txt`` file. You can install them by running:: + + python -m pip install --user -r $IDF_PATH/requirements.txt + +.. note:: + + Please invoke that version of the Python interpreter which you will be using with ESP-IDF. The version of the + interpreter can be checked by running command ``python --version`` and depending on the result, you might want to + use ``python2``, ``python2.7`` or similar instead of ``python``, e.g.:: + + python2.7 -m pip install --user -r $IDF_PATH/requirements.txt .. _get-started-start-project-cmake: -Start a Project -=============== +Step 5. Start a Project +======================= Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. @@ -194,15 +219,15 @@ It is also possible to build examples in-place, without copying them first. .. _get-started-connect-cmake: -Connect -======= +Step 6. Connect the Device +========================== -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. +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. .. _get-started-configure-cmake: -Configure -========= +Step 7. Configure +================= Navigate to the directory of the ``hello_world`` application copy, and run the ``menuconfig`` project configuration utility: @@ -250,11 +275,10 @@ Here are couple of tips on navigation and use of ``menuconfig``: When using ESP32-DevKitC board with ESP32-SOLO-1 module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing example applications. - .. _get-started-build-cmake: -Build The Project -================= +Step 8. Build the Project +========================= .. highlight:: bash @@ -288,8 +312,8 @@ If there are no errors, the build will finish by generating the firmware binary .. _get-started-flash-cmake: -Flash To A Device -================= +Step 9. Flash to a Device +========================= Now you can flash the application to the ESP32 board. Run:: @@ -339,8 +363,8 @@ If there are no issues, at the end of flash process, the module will be reset an .. _get-started-build-monitor-cmake: -Monitor -======= +Step 10. Monitor +================ To see if "hello_world" application is indeed running, type ``idf.py -p PORT monitor``. This command is launching :doc:`IDF Monitor ` application:: @@ -384,25 +408,23 @@ To exit the monitor use shortcut ``Ctrl+]``. idf.py -p PORT flash monitor -Check the section :doc:`IDF Monitor ` for handy shortcuts and more details on using the monitor. +Check the Section :doc:`IDF Monitor ` for handy shortcuts and more details on using the monitor. -Check the section :ref:`idf.py` for a full reference of ``idf.py`` commands and options. +Check the Section :ref:`idf.py` for a full reference of ``idf.py`` commands and options. That's all what you need to get started with ESP32! Now you are ready to try some other :idf:`examples`, or go right to developing your own applications. - Updating ESP-IDF ================ -After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf-cmake`. +You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf-cmake`. If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts know where to find the ESP-IDF in its release specific location. Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using `. - Related Documents ================= diff --git a/docs/en/get-started-cmake/linux-setup-scratch.rst b/docs/en/get-started-cmake/linux-setup-scratch.rst index a5e62b1df1..0c71ad5b6b 100644 --- a/docs/en/get-started-cmake/linux-setup-scratch.rst +++ b/docs/en/get-started-cmake/linux-setup-scratch.rst @@ -74,4 +74,4 @@ Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follo Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. diff --git a/docs/en/get-started-cmake/linux-setup.rst b/docs/en/get-started-cmake/linux-setup.rst index c3f51c0a44..c8dd5b5615 100644 --- a/docs/en/get-started-cmake/linux-setup.rst +++ b/docs/en/get-started-cmake/linux-setup.rst @@ -105,7 +105,7 @@ Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6. Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. Related Documents diff --git a/docs/en/get-started-cmake/macos-setup-scratch.rst b/docs/en/get-started-cmake/macos-setup-scratch.rst index 6c036304b0..dfbbc50508 100644 --- a/docs/en/get-started-cmake/macos-setup-scratch.rst +++ b/docs/en/get-started-cmake/macos-setup-scratch.rst @@ -85,4 +85,4 @@ Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32- Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. diff --git a/docs/en/get-started-cmake/macos-setup.rst b/docs/en/get-started-cmake/macos-setup.rst index d83ea6bdd0..75130d71ae 100644 --- a/docs/en/get-started-cmake/macos-setup.rst +++ b/docs/en/get-started-cmake/macos-setup.rst @@ -75,7 +75,7 @@ Log off and log in back to make the ``.profile`` changes effective. Run the foll Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. Related Documents ================= diff --git a/docs/en/get-started-cmake/windows-setup-scratch.rst b/docs/en/get-started-cmake/windows-setup-scratch.rst index 49a59053df..5c33e77f5c 100644 --- a/docs/en/get-started-cmake/windows-setup-scratch.rst +++ b/docs/en/get-started-cmake/windows-setup-scratch.rst @@ -85,7 +85,7 @@ Double-click the ``Path`` variable (either User or System Path, depending if you Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. .. _ninja: https://ninja-build.org/ .. _Python: https://www.python.org/downloads/windows/ diff --git a/docs/en/get-started-cmake/windows-setup.rst b/docs/en/get-started-cmake/windows-setup.rst index fe420b5a6a..fa8735aba7 100644 --- a/docs/en/get-started-cmake/windows-setup.rst +++ b/docs/en/get-started-cmake/windows-setup.rst @@ -51,7 +51,7 @@ For the remaining Getting Started steps, we're going to use a terminal command p Next Steps ========== -To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`. +To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf-cmake`. Related Documents ================= diff --git a/docs/zh_CN/get-started-cmake/index.rst b/docs/zh_CN/get-started-cmake/index.rst index 99e3543d09..7e4ac5de65 100644 --- a/docs/zh_CN/get-started-cmake/index.rst +++ b/docs/zh_CN/get-started-cmake/index.rst @@ -52,6 +52,10 @@ ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了 4. 通过 USB/串口，监视/调试**应用程序**输出 +.. The label below is placeholder to link a new section "Installation Step by Step" + +.. _get-started-step-by-step-cmake: + 开发板指南 ========================