mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'doc/add-info-manual-boot-to-get-started-guide' into 'master'
Issues with entering Download mode automatically See merge request espressif/esp-idf!7616
This commit is contained in:
Krzysztof Budzynski
commit
61a272ba56
@ -8,7 +8,7 @@ Get Started (Legacy GNU Make)
|
||||
|
||||
This document is intended to help you set up the software development environment for the hardware based on Espressif ESP32.
|
||||
|
||||
After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then how to build and flash firmware onto an ESP32 board.
|
||||
After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then for building and flashing firmware onto an ESP32 board.
|
||||
|
||||
.. include-build-file:: inc/version-note.inc
|
||||
|
||||
@ -18,7 +18,7 @@ Introduction
|
||||
ESP32 is a system on a chip that integrates the following features:
|
||||
|
||||
* Wi-Fi (2.4 GHz band)
|
||||
* Bluetooth 4.2
|
||||
* Bluetooth
|
||||
* Dual high performance cores
|
||||
* Ultra Low Power co-processor
|
||||
* Several peripherals
|
||||
@ -298,37 +298,60 @@ Build and flash the project by running::
|
||||
|
||||
This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. After that, these binaries will be flashed onto your ESP32 board.
|
||||
|
||||
If there are no issues by the end of the flash process, you will see messages (below) describing progress of the loading process. Then the board will be reset and the "hello_world" application will start up.
|
||||
|
||||
.. highlight:: none
|
||||
Encountered Issues While Flashing?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is manual reset described below, and if it does not help you can find more details about possible issues in `Troubleshooting <https://github.com/espressif/esptool#bootloader-wont-respond>`_.
|
||||
|
||||
esptool.py v2.0-beta2
|
||||
``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``GPIO0`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the schematic for :ref:`esp-modules-and-boards-esp32-devkitc` development board.
|
||||
|
||||
In general, you should have no problems with the official esp-idf development boards. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
|
||||
|
||||
- Your hardware does not have the DTR and RTS lines connected to ``GPIO0`` and ``CIHP_PU``
|
||||
- The DTR and RTS lines are configured differently
|
||||
- There are no such serial control lines at all
|
||||
|
||||
Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset).
|
||||
|
||||
- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an esp-idf development board, hold down the **Boot** button (``GPIO0``) and press the **EN** button (``CHIP_PU``).
|
||||
- For other types of hardware, try pulling ``GPIO0`` down.
|
||||
|
||||
|
||||
Normal Operation
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
If there are no issues by the end of the flash process, you will see the output log similar to the one given below. Then the board will reboot and start up the "hello_world" application.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
esptool.py v3.0-dev
|
||||
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
|
||||
esptool.py v2.0-beta2
|
||||
Connecting........___
|
||||
esptool.py v3.0-dev
|
||||
Serial port /dev/cu.SLAB_USBtoUART
|
||||
Connecting........____
|
||||
Chip is ESP32D0WDQ6 (revision 1)
|
||||
Features: WiFi, BT, Dual Core, Coding Scheme None
|
||||
Crystal is 40MHz
|
||||
MAC: 30:ae:a4:15:21:b4
|
||||
Uploading stub...
|
||||
Running stub...
|
||||
Stub running...
|
||||
Changing baud rate to 921600
|
||||
Changed.
|
||||
Attaching SPI flash...
|
||||
Configuring flash size...
|
||||
Auto-detected Flash size: 4MB
|
||||
Flash params set to 0x0220
|
||||
Compressed 11616 bytes to 6695...
|
||||
Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
|
||||
Compressed 26704 bytes to 15930...
|
||||
Wrote 26704 bytes (15930 compressed) at 0x00001000 in 1.4 seconds (effective 151.9 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 408096 bytes to 171625...
|
||||
Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
|
||||
Compressed 147984 bytes to 77738...
|
||||
Wrote 147984 bytes (77738 compressed) at 0x00010000 in 6.9 seconds (effective 172.7 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 3072 bytes to 82...
|
||||
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
|
||||
Compressed 3072 bytes to 103...
|
||||
Wrote 3072 bytes (103 compressed) at 0x00008000 in 0.0 seconds (effective 1607.9 kbit/s)...
|
||||
Hash of data verified.
|
||||
|
||||
Leaving...
|
||||
Hard resetting...
|
||||
Hard resetting via RTS pin...
|
||||
|
||||
|
||||
If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
|
||||
@ -355,12 +378,12 @@ This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` a
|
||||
|
||||
After startup and diagnostic logs scroll up, you should see "Hello world!" printed out by the application.
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: bash
|
||||
|
||||
...
|
||||
Hello world!
|
||||
This is esp32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash
|
||||
Restarting in 10 seconds...
|
||||
I (211) cpu_start: Starting scheduler on APP CPU.
|
||||
Restarting in 9 seconds...
|
||||
Restarting in 8 seconds...
|
||||
Restarting in 7 seconds...
|
||||
|
||||
@ -6,7 +6,7 @@ Get Started
|
||||
|
||||
This document is intended to help you set up the software development environment for the hardware based on the {IDF_TARGET_NAME} chip by Espressif.
|
||||
|
||||
After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an {IDF_TARGET_NAME} board.
|
||||
After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then for building and flashing firmware onto an {IDF_TARGET_NAME} board.
|
||||
|
||||
.. include-build-file:: inc/version-note.inc
|
||||
|
||||
@ -18,10 +18,10 @@ Introduction
|
||||
{IDF_TARGET_NAME} is a system on a chip that integrates the following features:
|
||||
|
||||
* Wi-Fi (2.4 GHz band)
|
||||
* Bluetooth 4.2
|
||||
* Bluetooth
|
||||
* Dual high performance cores
|
||||
* Ultra Low Power co-processor
|
||||
* Several peripherals
|
||||
* Multiple peripherals
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
@ -29,7 +29,7 @@ Introduction
|
||||
|
||||
* Wi-Fi (2.4 GHz band)
|
||||
* Ultra Low Power co-processor
|
||||
* Several peripherals
|
||||
* Multiple peripherals
|
||||
|
||||
Powered by 40 nm technology, {IDF_TARGET_NAME} provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
|
||||
|
||||
@ -75,6 +75,10 @@ If you have one of {IDF_TARGET_NAME} development boards listed below, you can cl
|
||||
ESP32-PICO-KIT <../hw-reference/esp32/get-started-pico-kit>
|
||||
ESP32-Ethernet-Kit <../hw-reference/esp32/get-started-ethernet-kit>
|
||||
|
||||
.. only:: esp32s2
|
||||
|
||||
There are currently no hardware guides available for ESP32-S2.
|
||||
|
||||
|
||||
.. _get-started-step-by-step:
|
||||
|
||||
@ -86,7 +90,7 @@ This is a detailed roadmap to walk you through the installation process.
|
||||
Setting up Development Environment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* :ref:`get-started-get-prerequisites` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`macOS <macos-setup>`
|
||||
* :ref:`get-started-get-prerequisites` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>`, or :doc:`macOS <macos-setup>`
|
||||
* :ref:`get-started-get-esp-idf`
|
||||
* :ref:`get-started-set-up-tools`
|
||||
* :ref:`get-started-set-up-env`
|
||||
@ -205,7 +209,7 @@ Linux and macOS
|
||||
Customizing the tools installation path
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux and macOS, ``%USERPROFILE%\.espressif`` on Windows. If you wish to install the tools into a different directory, set the environment variable ``IDF_TOOLS_PATH`` before running the installation scripts. Make sure that your user has sufficient permissions to read and write this path.
|
||||
The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux and macOS, ``%USERPROFILE%\.espressif`` on Windows. If you wish to install the tools into a different directory, set the environment variable ``IDF_TOOLS_PATH`` before running the installation scripts. Make sure that your user account has sufficient permissions to read and write this path.
|
||||
|
||||
If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the Install script (``install.bat``, ``install.ps1`` or ``install.sh``) and an Export script (``export.bat``, ``export.ps1`` or ``export.sh``) are executed.
|
||||
|
||||
@ -357,7 +361,9 @@ To navigate and use ``menuconfig``, press the following keys:
|
||||
Step 8. Build the Project
|
||||
=========================
|
||||
|
||||
Build the project by running::
|
||||
Build the project by running:
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
idf.py build
|
||||
|
||||
@ -391,7 +397,9 @@ If there are no errors, the build will finish by generating the firmware binary
|
||||
Step 9. Flash onto the Device
|
||||
=============================
|
||||
|
||||
Flash the binaries that you just built onto your {IDF_TARGET_NAME} board by running::
|
||||
Flash the binaries that you just built onto your {IDF_TARGET_NAME} board by running:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py -p PORT [-b BAUD] flash
|
||||
|
||||
@ -405,7 +413,32 @@ For more information on idf.py arguments, see :ref:`idf.py`.
|
||||
|
||||
The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
Encountered Issues While Flashing?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you run the given command and see errors such as "Failed to connect", there might be several reasons for this. One of the reasons might be issues encountered by ``esptool.py``, the utility that is called by the build system to reset the chip, interact with the ROM bootloader, and flash firmware. One simple solution to try is manual reset described below, and if it does not help you can find more details about possible issues in `Troubleshooting <https://github.com/espressif/esptool#bootloader-wont-respond>`_.
|
||||
|
||||
``esptool.py`` resets {IDF_TARGET_NAME} automatically by asserting DTR and RTS control lines of the USB to serial converter chip, i.e., FTDI or CP210x (for more information, see :doc:`establish-serial-connection`). The DTR and RTS control lines are in turn connected to ``GPIO0`` and ``CHIP_PU`` (EN) pins of {IDF_TARGET_NAME}, thus changes in the voltage levels of DTR and RTS will boot {IDF_TARGET_NAME} into Firmware Download mode. As an example, check the `schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch-20180607a.pdf>`_ for the ESP32 DevKitC development board.
|
||||
|
||||
In general, you should have no problems with the official esp-idf development boards. However, ``esptool.py`` is not able to reset your hardware automatically in the following cases:
|
||||
|
||||
- Your hardware does not have the DTR and RTS lines connected to ``GPIO0`` and ``CIHP_PU``
|
||||
- The DTR and RTS lines are configured differently
|
||||
- There are no such serial control lines at all
|
||||
|
||||
Depending on the kind of hardware you have, it may also be possible to manually put your {IDF_TARGET_NAME} board into Firmware Download mode (reset).
|
||||
|
||||
- For development boards produced by Espressif, this information can be found in the respective getting started guides or user guides. For example, to manually reset an esp-idf development board, hold down the **Boot** button (``GPIO0``) and press the **EN** button (``CHIP_PU``).
|
||||
- For other types of hardware, try pulling ``GPIO0`` down.
|
||||
|
||||
|
||||
Normal Operation
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
After resetting, you will see the output log similar to the following:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Running esptool.py in directory [...]/esp/hello_world
|
||||
Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"...
|
||||
@ -436,7 +469,7 @@ For more information on idf.py arguments, see :ref:`idf.py`.
|
||||
Leaving...
|
||||
Hard resetting via RTS pin...
|
||||
|
||||
If there are no issues by the end of the flash process, the module will be reset and the “hello_world” application will be running.
|
||||
If there are no issues by the end of the flash process, the board will reboot and start up the “hello_world” application.
|
||||
|
||||
.. (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>`.
|
||||
|
||||
@ -468,7 +501,7 @@ After startup and diagnostic logs scroll up, you should see "Hello world!" print
|
||||
...
|
||||
Hello world!
|
||||
Restarting in 10 seconds...
|
||||
I (211) cpu_start: Starting scheduler on APP CPU.
|
||||
This is esp32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 2MB external flash
|
||||
Restarting in 9 seconds...
|
||||
Restarting in 8 seconds...
|
||||
Restarting in 7 seconds...
|
||||
@ -502,7 +535,7 @@ See also:
|
||||
- :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor.
|
||||
- :ref:`idf.py` for a full reference of ``idf.py`` commands and options.
|
||||
|
||||
**That's all that you need to get started with ESP32!**
|
||||
**That's all that you need to get started with {IDF_TARGET_NAME}!**
|
||||
|
||||
Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user